Studio:WorkspaceSetup.pl: Difference between revisions

Latest revision as of 04:54, 7 May 2010

The WorkspaceSetup.pl script (found in the STRIDE scripts directory) provides a command line tool for creating canonical STRIDE Studio workspaces suitable for organizing your test scripts. This script requires perl for execution as well as the STRIDE Test Utilities.

Usage

Summary

WorkspaceSetup.pl -w MyWorkspace -d "MyDir" [-c customconfig -l]

Parameters
-w | --workspacename = WorkspaceName: Specifies the name new workspace to be created. This workspace will be created in the directory specified by the --dirworkspace argument or in the current directory (if no workspace directory is specified). Defaults to 'MyWorkspace'.
-d | --dirworkspace = WorkspaceDirectory: Specifies the directory in which to create the new workspace. Defaults to the current directory.
-c | --workspaceconfig = MyConfig.pm: Allows users to specify a different an optional WorkspaceConfig.pm file to use when creating the workspace. This allows users to generate a workspace with custom config parameters.
-l | --launch: Launches STRIDE Studio and opens the newly created workspace.

Workspace Layout

The workspaces that are created by WorkspaceSetup will have the following files and folders (items in <brackets> indicate folders):

 < Script Files > 
   <setup>
     s2StartPrintLog.pl
   <test> 
   <teardown>
     s2StopPrintLog.pl
     s2TweakResults.pl
   <utility>
     <recovery>
       s2OnError.pl

 < Source Files >

setup Folder

This folder is intended to contain the scripts necessary to prepare the device for testing. For the canonical workspace, we add a script that opens a traceview to capture srPrint* output messages. Users might choose to add scripts for starting and initializing the device under test.

test Folder

This folder is intended to contain the test scripts to be executed on the device. It is created by this setup and test script writers are free to organize test scripts however they want in this folder. This folder also has the "OnRunConnect" property set to true so that a target connection will be initiated when it is executed. The connection is established using your global connection settings (see STRIDE Studio reference guide for more information).

teardown Folder

This folder contains the scripts necessary to cleanup after testing is completed. This might involve, for example, stopping the device. The canonical workspace contains one script to process the srPrint* info sent to the logging traceview and another to adjust the hierarchy of the final report results.

utility Folder

This folder should be used to hold utility libraries that are associated with the workspace. This directory is not included in execution; as such, the files therin are provided for convenience to the users.

recovery Folder

This folder contains the sample s2OnError script that we provide. This is intended as a template for customization depending on your device's needs.

WorkspaceConfig.pm

WorkspaceSetup.pl provides a limited way to configure the settings used when creating the new workspace. This file (WorkspaceConfig.pm), if specified, is executed during workspace creation and is used to configure the compiler, target, and workspace level settings for each new workspace.

WorkspaceConfig must define, at a minimum, a single hash variable named %WorkspaceConfig::Settings (i.e., the hash is called Settings and is in the WorkspaceConfig package namespace). This hash may contain any or all of the following members:

Compiler
Target
Database
Workspace

Each of these elements are themselves hashes (anonymous), each of which has entries that correspond to the properties of the corresponding automation studio automation model, e.g.:

Compiler corresponds to studio.Workspace.Settings.Compiler
Target corresponds to studio.Workspace.Settings.Target
Database corresponds to studio.Workspace.Settings.Database
Workspace corresponds to studio.Workspace

Provided Scripts

s2StartPrintLog.pl

This script creates one or more traceviews to capture messages from the STRIDE Runtime.

s2StopPrintLog.pl

This script processes the content of the traceview(s) that were created by s2StartPrintLog.pl. The contents of the traceview(s) is added to the resulting test report as annotations.

s2TweakResults.pl

Since the workspace organization includes several folders that produce no test results, this script consolidates the result from the test folder into a more convenient test report hierarchy. The final report that is generated contains all test results from the test folder under the top-level workspace suite.

s2OnError.pl

This script demonstrates how one might implement a recovery script for use in STRIDE Studio (as an OnError or OnTimeout property). This implementation verifies that the connection to the device is still active. If the connection has been lost, it attempts to "restart" the device by running the scripts in the setup and teardown folders. For most devices, the restart logic should probably be customized to better suit the device.

Once the device connection is determined to be healthy, the script attempts to verify that the intercept module thread is active by calling a stock function called __strideIMProbe__. If this function exists and returns an expected value when returned, the target is deemed to be functional and ready for more tests. Otherwise, the device is assumed to be non-functional and testing is halted.

Prerequisites

This component is written in the Perl scripting language and therefore requires that Perl be installed. See Perl requirements for more information.

@@ Line 1: / Line 1: @@
-The WorkspaceSetup.pl script (found in the STRIDE ''scripts'' directory) provides a command line tool for creating workspaces from a Framework.  This script requires perl for execution as well as the STRIDE Test Utilities.
+The WorkspaceSetup.pl script (found in the STRIDE ''scripts'' directory) provides a command line tool for creating canonical [[STRIDE Studio]] workspaces suitable for organizing your test scripts.  This script requires perl for execution as well as the STRIDE Test Utilities.
 ==Usage==
@@ Line 6: / Line 6: @@
 :{|
-|style="background:linen" | <font face="courier">WorkspaceSetup.pl -w MyWorkspace -d "MyDir" -f fxname [-g fxdir -p pkg -q pkgdir -s customsettings -c customconfig -l]</font>
+|style="background:linen" | <font face="courier">WorkspaceSetup.pl -w MyWorkspace -d "MyDir" [-c customconfig -l]</font>
 |}
@@ Line 14: / Line 14: @@
 ;-d | --dirworkspace = WorkspaceDirectory
 :Specifies the directory in which to create the new workspace. Defaults to the current directory.
-;-f | --framework = TargetFramework
-:Specifies the STRIDE Target Framework to use when creating the workspace. As of this writing, STRIDE provides several basic frameworks:
-:*'''''Linux''''' for strideAgent-based tests on a FedoraCore7 target machine.
-:*'''''WindowsStrideAgent''''' for strideAgent-based tests on the host platform.
-:*'''''WindowsTestApp''''' for TestApp-based tests on the host platform.
-:*'''''WinMobile''''' for strideAgent-based tests on a WinMobile device.
-:*'''''GenericStrideAgent''''' for a skeleton framework that prompts the user at each step that requires action (e.g. building or starting the target application).
-:*'''''GenericTestApp''''' for a skeleton framework that prompts the user at each step that required action.
-:Customers can create additional custom frameworks and specify additional search paths for this script to use to locate the frameworks.
-;-g | --dirframework = FrameworkSearchDirectory
-:Specifies an additional directory path to search for the specified framework. If the framework is not found in the default STRIDE frameworks directory, these directories will be searched. This option can be specified multiple times to add multiple directories to the framework search path.
-;-p | --package = PackageName
-:Specifies a Test Package to add to the workspace when it is created. If no packages are specified, the workspace will be created without any tests in it. This option can be specified multiple times to add multiple packages to the new workspace
-;-q | --dirpackage = PackageSearchDirectory
-:Specifies an additional directory path to search for packages. For any package that is specified with the --package option, we first look in the packages directory in the STRIDE insatllation directory. If it is not found there, we will search in the location(s) specified by this option. This option can be specified multiple times to add multiple additional directories to the packages search path.
-;-s | --commonsettings = MySettings.pm
-:Allows users to specify a different CommonSettings file to copy into the generated workspace directory. This allows framework users to generate a workspace with a customized set of local settings.
 ;-c | --workspaceconfig = MyConfig.pm
-:Allows users to specify a different WorkspaceConfig file to use when creating the workspace. This allows framework users to generate a workspace with custom config parameters.
+:Allows users to specify a different an optional [[#WorkspaceConfig.pm|WorkspaceConfig.pm]] file to use when creating the workspace. This allows users to generate a workspace with custom config parameters.
 ;-l | --launch
 :Launches STRIDE Studio and opens the newly created workspace.
@@ Line 40: / Line 23: @@
 The workspaces that are created by WorkspaceSetup will have the following files and folders (items in '''<brackets>''' indicate folders):
    '''< Script Files >'''
-    '''<[[#build Folder|build]]> (only if present in the input framework)'''
-      [[Creating Frameworks#CheckEnv.pl|CheckEnv.pl]]
-      [[Creating Frameworks#CompileWorkspace.pl|CompileWorkspace.pl]]
-      [[Creating Frameworks#CreateInterceptModule.pl|CreateInterceptModule.pl]]
-      [[Creating Frameworks#BuildStrideAgent.pl|BuildStrideAgent.pl]]
-      '''<[[#Intercept Module Overrides Folder|Intercept Module Overrides]]>'''
-        '''<{Package_X}>'''
-          (optional package specific scripts, grouped into a package folder)
-        '''<...>'''
      '''<[[#setup Folder|setup]]>'''
-       [[Creating Frameworks#StartPrintLog.pl|StartPrintLog.pl]]
+       [[#s2StartPrintLog.pl|s2StartPrintLog.pl]]
-      [[Creating Frameworks#StartTestAgent.pl|StartTestAgent.pl]]
+     '''<[[#test Folder|test]]>'''
-        (OR any other files that exist in the input framework's setup folder)
-     '''<[[#test Folder|test]]>'''
-        '''<{Package_X}>'''
-          (package specific test scripts, grouped into a package folder)
-        '''<...>'''
      '''<[[#teardown Folder|teardown]]>'''
-       [[Creating Frameworks#StopTestAgent.pl|StopTestAgent.pl]]
+       [[#s2StopPrintLog.pl|s2StopPrintLog.pl]]
-        (OR any other files that exist in the input framework's teardown folder)
+       [[#s2TweakResults.pl|s2TweakResults.pl]]
-      [[Creating Frameworks#StopPrintLog.pl|StopPrintLog.pl]]
-       [[Creating Frameworks#TweakResults.pl|TweakResults.pl]]
      '''<[[#utility Folder|utility]]>'''
-      (optional [[Creating Frameworks#utility Directory (framework)|Framework specific]] utility libraries)
-      [[Creating Frameworks#BuildUtilities.pm|BuildUtilities.pm]]
-      [[Creating Frameworks#TargetUtilities.pm|TargetUtilities.pm]]
        '''<[[#recovery Folder|recovery]]>'''
-         [[Creating Frameworks#OnError.pl (framework)|OnError.pl]]
+         [[#s2OnError.pl|s2OnError.pl]]
-        [[Creating Frameworks#OnTimeout.pl (framework)|OnTimeout.pl]]
-      [[Creating Frameworks#CommonSettings.pm|CommonSettings.pm]]
-      [[Creating Frameworks#FrameworkUtilities.pm|FrameworkUtilities.pm]]
    '''< Source Files >'''
-    '''<[[#Framework Folder|Framework]]>'''
-      [[Creating Frameworks#strideIMProbe_SCL.h|strideIMProbe_SCL.h]]
-    '''<{Package_X}>'''
-      (optional package specific source, grouped into a package folder)
-    '''<...>'''
-===build Folder===
-This folder contains the general and Framework-specific scripts necessary for building the STRIDE workspace and strideAgent device image. If this folder is not present in the input framework (e.g. with a TestApp framework), then it will be omitted from the generated workspace.
-===Intercept Module Overrides Folder===
-This folder may contain one or more Test Package-specific scripts for properly configuring the Intercept Module settings for the interfaces associated with the package.
 ===setup Folder===
-This folder contains the scripts necessary to prepare the device for testing. For TestAgent-based frameworks, this might involve transfer of the TestAgent image and starting of the process on the device.
+This folder is intended to contain the scripts necessary to prepare the device for testing. For the canonical workspace, we add a script that opens a traceview to capture srPrint* output messages. Users might choose to add scripts for starting and initializing the device under test.
 ===test Folder===
-This folder contains all package-specific tests, grouped in sub-folders by package name. For TestAgent-based frameworks, this folder also has the "OnRunConnect" property set to true so that a target connection will be initiated when it is executed. The connection is established using your global connection settings (see STRIDE Studio reference guide for more information).
+This folder is intended to contain the test scripts to be executed on the device. It is created by this setup and test script writers are free to organize test scripts however they want in this folder. This folder also has the "OnRunConnect" property set to true so that a target connection will be initiated when it is executed. The connection is established using your global connection settings (see STRIDE Studio reference guide for more information).
 ===teardown Folder===
-This folder contains the scripts necessary to cleanup after testing is completed. For TestAgent-based frameworks, this might involve stopping the TestAgent process and removing the TestAgent image from the device.
+This folder contains the scripts necessary to cleanup after testing is completed. This might involve, for example, stopping the device. The canonical workspace contains one script to process the srPrint* info sent to the logging traceview and another to adjust the hierarchy of the final report results.
 ===utility Folder===
-This folder contains utility libraries that are associated with the workspace.  Some files come from the common STRIDE Framework, while others are Framework-specific. Not all of the files in this directory tree are included in execution; as such, they are in the workspace primarily for convenience to the users.
+This folder should be used to hold utility libraries that are associated with the workspace.  This directory is not included in execution; as such, the files therin are provided for convenience to the users.
 ===recovery Folder===
-This folder contains the OnError and OnTimeout scripts &ndash; either a [[Creating Frameworks#OnError.pl (framework)|specific implementation]] provided by the Framework or the [[Creating Frameworks#OnError.pl (common)|default implementation]] provide by the STRIDE common files.
+This folder contains the sample s2OnError script that we provide. This is intended as a template for customization depending on your device's needs.
+==WorkspaceConfig.pm==
+WorkspaceSetup.pl provides a limited way to configure the settings used when creating the new workspace.  This file (WorkspaceConfig.pm), if specified, is executed during workspace creation and is used to configure the compiler, target, and workspace level settings for each new workspace.
+WorkspaceConfig must define, at a minimum, a single hash variable named %WorkspaceConfig::Settings (i.e., the hash is called Settings and is in the WorkspaceConfig package namespace).  This hash may contain any or all of the following members:
+*Compiler
+*Target
+*Database
+*Workspace
+Each of these elements are themselves hashes (anonymous), each of which has entries that correspond to the properties of the corresponding automation studio automation model, e.g.:
+*Compiler corresponds to studio.Workspace.Settings.Compiler
+*Target corresponds to studio.Workspace.Settings.Target
+*Database corresponds to studio.Workspace.Settings.Database
+*Workspace corresponds to studio.Workspace
+==Provided Scripts==
+===s2StartPrintLog.pl===
+This script creates one or more traceviews to capture messages from the STRIDE Runtime.
+===s2StopPrintLog.pl===
+This script processes the content of the traceview(s) that were created by [[#s2StartPrintLog.pl|s2StartPrintLog.pl]].  The contents of the traceview(s) is added to the resulting test report as annotations.
+===s2TweakResults.pl===
+Since the workspace organization includes several folders that produce no test results, this script consolidates the result from the test folder into a more convenient test report hierarchy. The final report that is generated contains all test results from the test folder under the top-level workspace suite.
+===s2OnError.pl===
+This script demonstrates how one might implement a recovery script for use in STRIDE Studio (as an OnError or OnTimeout property). This implementation verifies that the connection to the device is still active. If the connection has been lost, it attempts to "restart" the device by running the scripts in the '''setup''' and '''teardown''' folders.  For most devices, the restart logic should probably be customized to better suit the device.
+Once the device connection is determined to be healthy, the script attempts to verify that the intercept module thread is active by calling a stock function called ''__strideIMProbe__''.  If this function exists and returns an expected value when returned, the target is deemed to be functional and ready for more tests. Otherwise, the device is assumed to be non-functional and testing is halted.
-===Framework Folder===
+== Prerequisites ==
-This folder contains source code required for general Framework test execution and recovery.
+This component is written in the Perl scripting language and therefore requires that Perl be installed. See [[Studio:Desktop Installation#Third Party Requirements|Perl requirements]] for more information.
-[[Category: Frameworks]]
+[[Category:Studio:Scripts]]