Studio:Interfacing Sample

Introduction

The following content relates to the sample files and workspaces installed in %STRIDE_DIR%\Samples\Scripting\AutoScript. This sample consists of a Visual Studio workspace for building an off-target simulator, sample source code and test scripts, and a STRIDE workspace for sample code execution.

Prerequisites

Before starting, some prerequisites must be satisfied. For details and instructions, see Host Installation.

Specifically:

• STRIDE must be installed on the Windows PC to be used in the training, and any required licenses must be present.
• Active State Perl must be installed, and additional perl packages must be downloaded and installed. Note: when the sample workspace is executed, a script runs that verifies that the required Perl packages have been installed correctly.
• Microsoft Visual Studio 2005 or a later version must be installed. If you do not currently have any version of Visual Studio, we recommend that you install the current free version of Visual Studio Express.

Getting Started

To begin, open the Visual Studio Solution file in the sample directory. This solution (and corresponding project) were created for Visual Studio 2005. If you have a later version of Visual Studio installed, you should be able to open this solution and it will be automatically upgraded if necessary. If you do not currently have any version of Visual Studio, we recommend that you install the current free version of Visual Studio Express.

Once you have successfully opened the solution, rebuild it. The build process has custom STRIDE build rules integrated and will produce a STRIDE database, intercept module source files, and an off-target simulator application that incorporates the sample source code.

Once the build is complete, perform the following steps to run the sample scripts in the workspace:

1. launch the off-target simulator, Ascript_Samples.exe. This will run in a standard console window.
2. open a command prompt window and change to this sample's directory.
3. at the command prompt, run the command WorkspaceRun.pl -x setup -x teardown. This will execute all of the sample test scripts in the workspace and displays the results. You may open a browser and display the report written to the Ascript_Samples.html file in the sample's directory .
4. quit the Ascript_Samples.exe application by typing 'q' in its console window.

Sample Tests

Now that you have built the off-target simulator and executed the scripting samples, you can take time to peruse the sample scripts and the corresponding results that each produces. This section provides a brief description for each script.

User Owner

This folder contains scripts that implement both the user and owner sides of a function call. This sample is completely host based - no target simulator is required. Only the user script is executed by the Studio test runner; the owner script is started by the user script, running it with a non-blocking call (using the studio object, described in the Studio Online Help).

The user.pl script first runs the owner.pl script, as described. Then it loops until it determines that the test function has been owner registered. Once this has occurred it calls the function, blocking until the call is returned.

The owner.pl script registers as an owner of the test function and then enters an event wait loop where a blocking call to WaitForEvent is made. WaitForEvent returns with a function call event when the the test function is called from the user script. From there the owner script sets the function OutPointer and return values, returns the call, and exits the loop and script.

Register Override

This folder contains scripts that again implement both the user and owner sides of a function call. The difference here is that this time the scripted owner is registered as an override owner - which will receive calls from the user instead of the original function owner. This sample is not completely host based - the target simulator is required to provide the original owner of the function. Only the user script is executed by the Studio test runner; the owner script is started by the user script, running it with a non-blocking call.

The regOverrideUser.pl script first calls the original owner of the function, which is the function implemented in the target simulator application, which should be running and connected at this time (the setup folder runs the console application, and the OnRunConnect property is set on the Register Override folder to connect before executing the scripts). Once the function call is returned, the user script starts the regOverrideOwner.pl script. After that the user script loops until it detects that the function has been registered override (for synching purposes with the owner script) and then it calls the function again.

The regOverrideOwner.pl script is started by the regOverrideUser.pl script, as described above. It immediately registers itself as an override owner for the test function and loops until the function call event is received. From there it sets the function OutPointer and return values, returns the call, and exits the loop and script.

Collections

This folder contains scripts that implement both the user and owner sides for multiple function calls. This sample shows how to access the AutoScript Functions collection. The sample is completely host based - no target simulator is required. Only the user script is executed by the Studio test runner; the owner script is started by the user script, running it with a non-blocking call.

The MultiFnUser.pl script first runs the MultiFnOwner.pl script, then loops through the Functions collection, checking for each to be owner registered. Note: this is only necessary as a synching mechanism with the owner script. If the function owner is implemented on the target application then all interfaces are access class registered at the start of the application.
Once all the function owners have been registered, the user script loops through the Functions collection again, calling each Function through the Function User interface. In the sample script, special processing is done for the fMultiFnTestIntPtr function before the call is made. The integer pointer field in the ParameterList is set to NULL by accessing the synthesized PointerNuller object (for more details refer to the pointer auto-dereferencing section of the AutoScript reference.) Before the user script exits, it waits for the function owners to unregister prior to verifying the results, and generating the report.

The MultiFnOwner.pl script loops through the Functions collection and registers as an owner of each test function. Then the script enters an event wait loop where the blocking call to WaitForEvent is made which will return when registered function calls events occur. Another event that will trigger a return from the WaitForEvent call is the timeout event, which was enabled earlier in the script by setting the AutoScript WaitTimeoutPeriod property to a positive, non-zero value. (See the AutoScript API page for more details on WaitForEvent and WaitTimeoutPeriod.) When each function call event is received, the owner script sets the function OutPointer and return values, and returns the call. When the timeout event is received, and the timeout period has elapsed, the event wait loop is exited. Before the script is exited, the Functions collection is traversed again, where each function is unregistered, thereby re-synching with the user script which is waiting for the function owner unregistration before verifying the function call results.

Test Execution

This sample demonstrates two different techniques for executing the sample test scripts.

Command Line Execution

Command line execution for sample STRIDE test workspace is done using the WorkspaceRun utility. Here is an example of specific syntax to execute a test workspace. All of these commands can be invoked from a standard command shell (or other shell of your choosing) and the arguments shown assume that the commands are executed with the sample's directory as the starting directory. You must have your Ascript_Samples.exe application running in order for the runner to be able to initiate a connection to the target simulator.

 WorkspaceRun.pl -x setup -x teardown

When you run this command, you should see console output like:

 Opening workspace C:\S2\Seaside\Samples\Scripting\AutoScript/Ascript_Samples.ssw..
 excluding folder setup in workspace C:\S2\Seaside\Samples\Scripting\AutoScript/Ascript_Samples.ssw
 running folder test in workspace C:\S2\Seaside\Samples\Scripting\AutoScript/Ascript_Samples.ssw
 excluding folder teardown in workspace C:\S2\Seaside\Samples\Scripting\AutoScript/Ascript_Samples.ssw
 Test results written to C:\S2\Seaside\Samples\Scripting\AutoScript\Ascript_Samples.html
 ***************************************************************************
 Results Summary
 ***************************************************************************
   Passed:               7
   Failed:               0
   In Progress:          0
   Not Applicable:       0
   ...in 5 suites.
 ***************************************************************************

Workspace-Based Execution

We provide a sample STRIDE workspace (.ssw file) that demonstrates the use of script execution with STRIDE Studio to manage the test order and hierarchy. The setup and teardown folders provide basic infrastructure scripts that start and stop the simulator application (Ascript_Samples.exe). The scripts that drive the testing are in the workspace test folder, and are described in the Sample Tests section above. The test functions are declared in the header files under Source Files and are implemented in the target application, in the ".c" files that correspond to the header files in the sample workspace. Since these functions are owner registered by the test scripts, most of the functions implemented in the target application are never executed. The real purpose of the target application is to illustrate the RegisterOverride concept, explained in the Sample Tests section above. Note: these ".c" files are part of the Visual Studio project, you may view these files in Visual Studio, or you may locate them on disk in the same directory as the sample header files, under the Tests directory under the installed sample directory.