Perl Script Snippets

Below are some brief examples of script test modules that use the Perl Script APIs for STRIDE. Most of these examples are incomplete and are only intended to give a quick overview of how this API can be used.

With any perl module that you write, we recommend that you perform a quick syntax check before attempting to execute the module using the STRIDE runner. Syntax checking with warnings is easily accomplished by running with the -cw option, e.g.:

• Windows

 perl -I %STRIDE_DIR%\lib\perl -I %STRIDE_DIR%\lib\perl\5.10 -cw MyTests.pm

• Linux

 perl -I $STRIDE_DIR/lib/perl -I $STRIDE_DIR/lib/perl/5.10 -cw MyTests.pm

This will compile the perl script without running it, and it will emit any syntax errors that are found.

Canonical module format

use strict;
use warnings;

package MyTests;
use base qw(STRIDE::Test);
use STRIDE::Test;

sub test_one : Test
{
    ASSERT_TRUE(1);
}

sub test_two : Test
{
    ASSERT_TRUE(0);
}

1;

Subroutine attributes to declare test methods and fixtures

sub a_test : Test {
    # test method
}

sub startup_method : Test(startup) {
    # startup fixturing
}

sub shutdown_method : Test(shutdown) {
    # shutdown fixturing
}

sub setup_method : Test(setup) {
    # setup fixturing
}

sub teardown_method : Test(teardown) {
    # teardown fixture
}

Test module including POD documentation

package MyTests;
use base qw(STRIDE::Test);
use STRIDE::Test;

=head1 NAME

MyTests - example tests

=head1 DESCRIPTION

This is MyTests_1, a deeply funky piece of Perl code.

=head1 METHODS

=cut


=head2 test_one

this is a simple "passing" test.

=cut
sub test_one : Test
{
    ASSERT_TRUE(1);
}


=head2 test_two

this is a simple "failing" test.

=cut
sub test_two : Test
{
    ASSERT_TRUE(0);
}

1;

Simple expectation test

sub sync_exact : Test {    
    my $h = TestPointSetup(
        ordered => 1,
        expected => [
            "point a",
            "point b",
            "point c"
        ],
        unexpected => [ TEST_POINT_EVERYTHING_ELSE ]
    );
    
    #...start source under test, if necessary

    # use Check if the events have all happened by the time 
    # you validate the test points. Otherwise use Wait with 
    # a reasonable timeout value.
    $h->Check(); 
}

Expectation test with predicate

Here's how to specify a predicate for validating a test point. The predicate shown is just a stub and doesn't do any actual validation.

sub _myPredicate
{
    my ($test_point, $expected_data) = @_;
    # $test_point is a hashref with the following fields:
    #  label, data, size, bin, file, line
    # use the test point data to perform validation and return 
    # nonzero value on success, 0 on failure.

    return 1;
}

sub use_a_predicate : Test {
    # use arrayref notation to specify label, count, predicate and expected data
    # if you want to specify a predicate. Predicates can be specified for some, all
    # or none of the test points. The fourth field is optional - it is just passed
    # to the predicate as the second argument and is typically used to specify some 
    # expected data for the predicate to validate against.    
    my $h = TestPointSetup(
        expected => [
            ["point a", 1, \&_myPredicate, 54321],
            "point b",
            ["point c", 1, \&_myPredicate]
        ]
    );

    $h->Check(); 
}

Reusing a trace data file as expectation

This examples shows a simple way to reuse captured yaml trace data from a file as your expectation (this is an alternative to specifying the expected array directly). This example assumes the trace_data.yaml file lives in the same directory as the test module file, but you are free to change this - just change the expect_file argument accordingly.

# these standard modules are only required for the file 
# path logic used to generate a full file path for trace_data.yaml
use File::Basename;
use File::Spec;

sub trace_data : Test {    
    my $h = TestPointSetup(
        ordered => 1,
        expect_file => File::Spec->catfile(dirname(__FILE__), 'trace_data.yaml'),
    );

    # make any function calls necessary to start the SUT, 
    # then do a Check or Wait, depending on your scenario

    $h->Check();   
}

Invoking a function on the target

Standalone two-line script for invoking a remote function

This simple script shows the minimal code required to make a remote function call of a function that has been enabled with STRIDE remoting.

use STRIDE;
$STRIDE::Remote->MyRemoteFunction();

More functions can be added to this script by making additional calls using the $STRIDE::Remote object. If your remote function accepts arguments, they should be added to the function call parameters (see the Perl API Reference for more information).

Making calls with test modules

Within test modules, remote functions can be easily invoked using the exported Remote object. The following two examples illustrate this.

Blocking syntax (blocks until function returns)

my $retval = Remote->foo(1, "input string");
Remote->bar();

asynchronous execution (return immediately, function continues to execute on device)

my $fh = Remote->async->foo(1, "input string");
my $retval = $fh->Wait(1000); #waits up to one second for the function to return

Accessing compiler macro values (constants)

/* some compilation unit included in the STRIDE compilation process */
#define SOME_DEFINED_VALUE 42

my $value = Remote->{SOME_DEFINED_VALUE};