Running Spec Explorer from the Command Line

  • Article

Spec Explorer includes a stand-alone executable, SpecExplorer.exe, that can be run from the command line. This tool is useful in automated unattended applications such as those driven by a batch file or a build system.

SpecExplorer.exe provides the Exploration Manager functionality of Spec Explorer without Visual Studio dependencies. It provides a command-line means to generate test suites from existing machines, persist exploration results of one or more machines, and run custom post-processors on these results. The manually-operated UI of Spec Explorer allows one machine per operation such as exploration or test code generation. An advantage of command-line invocation is that a batch file or script can use one or more invocations of SpecExplorer.exe to apply the same operation to multiple machines.

SpecExplorer.exe is placed in the %VSInstallDir%\Common7\IDE\Extensions\Microsoft\Spec Explorer 2010\3.6 directory by the Spec Explorer installer. To deploy Spec Explorer to an automation environment without Visual Studio, copy that entire directory branch to your environment. See Getting and Installing Spec Explorer for more information on installing Spec Explorer in Visual Studio.

Usage Syntax

When used, all of the following optional arguments are specified (following the SpecExplorer.exe command invocation itself) on the same command line and are separated by at least one space character. They are listed here on separate lines for clarity.

  • SpecExplorer.exe

    • /task:{DoOnTheFlyTests | GenerateTests | PersistExploration | PerformUserTasks | Validate}
       
    • /assemblies: <Model.dll>, <Implementation.dll>, ...
       
    • /lib: <DirPath>, ...
       
    • /scripts: <A.cord>, <B.cord>, ...
       
    • /machines: <TestSuite>, ...
       
    • /ExplorationResultPath: <DirPath>
       
    • /OnTheFlyMaximumExperimentCount: number | 'none'
       
    • /OnTheFlyAllowEndingAtEventState: true | false
       
    • /ReplayTestResultFile: <filename>
       
    • /TestResultPath: <DirPath>
       
    • /UserTasks: <ClassNameA>, <ClassNameB>, ...
       
    • /verbose
       
    • /?
       

Argument Descriptions

Some of the following arguments depend on the current machine's Cord configuration switch settings to determine functionality. For more details on such switches see SwitchClause.

  • /task:{DoOnTheFlyTests | GenerateTests | PersistExploration | PerformUserTasks | Validate}
    This argument is used to perform one of the following optional tasks. Argument short form: /t:
    • /task:DoOnTheFlyTests
      This option of the /task: argument enables on-the-fly testing. A detailed explanation of on-the-fly testing and its relationship to test code generation testing can be found through the Testing link in the Related Topics section of this page.
    • /task:GenerateTests
      This option of the /task: argument requests creation of test cases. It uses the following Cord switch values to enable generation and determine the path and file names of the generated tests. These switches are not specified on the command line. Their values exist within the running Spec Explorer. GenerateTests is the default option of this argument.
      • TestEnabled
        This switch value must be true to permit test cases to be generated for the current machine.
      • ForExploration
        This switch value must be true to permit test cases to be generated for the current machine.
      • GeneratedTestPath
        This switch value is used relative to the directory from where SpecExplorer.exe was launched. The default value of this switch is TestSuite, which yields an effective directory path of <specexplorer.exe launch dirpath>/TestSuite.
      • GeneratedTestFile
        This switch value specifies the file name given to the generated test suite. The default file name is <MachineName>.cs. Any existing file of the same name in the GeneratedTestPath directory will be overwritten without warning.
    • /task:PersistExploration
      This option of the /task: argument outputs the current machine's exploration graph in the form of a .SEEXPL file to a directory determined by the /ExplorationResultPath: argument. The name for the SEEXPL files will be <MachineName>.seexpl. The current machine's ForExploration Cord configuration switch must be true for this argument to operate.
    • /task:PerformUserTasks
      This option of the /task: argument performs the available post-processor user tasks. By default, all pre-registered or argument-specified user tasks will be run for each eligible machine given by the /machines: argument. The ForExploration Cord configuration switch must be true for each of those machines to enable the user tasks to be performed for that machine. The order in which the user tasks are performed is not guaranteed for pre-registered post-processors but will follow the order specified in an overriding /UserTasks: argument.
    • /task:Validate
      This option of the /task: argument performs validation of the model project, similar to the validate scripts feature available from Exploration Manager. If the validate task is present, SpecExplorer.exe ignores other arguments, except for the /assemblies:, /lib:, and /script: arguments.
  • /assemblies: <Model.dll>, <Implementation.dll>, ...
    This argument specifies the list of assemblies necessary to resolve references in the Cord scripts. This includes assemblies containing model programs and any type referenced from the Cord scripts or other assemblies in the list not present in Global Assembly Cache (GAC). The first assembly must be the model assembly. Other assemblies with the ModelingAssemblyAttribute attribute will be regarded as model assemblies. Short form: /a:
  • /lib: <DirPath>,...
    This argument works in conjunction with the /assemblies: argument. It specifies a list of directories that are searched for the assemblies that are listed in the /assemblies: argument. Each <DirPath> is an absolute directory path. Short form /l:
  • /scripts: <A.cord>, <B.cord>, ...
    This argument names the Cord scripts where the machines to explore are defined. Short form: /s:
  • /machines: <TestSuite>, ...
    This argument specifies the machines to explore in order to generate either tests or persistent transition systems. The syntax supports regular expressions in C# syntax so that users are able to specify several machines in a short expression such as "TestSuite.*" (meaning all machines whose names begin with the string "TestSuite"). Each <TestSuite> will be interpreted as an exact match unless regular expression meta-characters are used. Thus, if <TestSuite> is not specified with a leading "^", it will be automatically prepended and if <TestSuite> is not specified with a trailing "$", it will be automatically appended. For example, if the argument is /machines:Test, the effective argument used will be /machines:^Test$ (which means exactly match string "Test"). Short form: /m:
  • /ExplorationResultPath: <DirPath>
    This argument specifies the directory for storing exploration result files. The <DirPath> value determines the effective path to the directory that is used in all SpecExplorer.exe operations that generate exploration results, notably including those results generated by the /task:PersistExploration argument. The <DirPath> value is used relative to the current working directory from where SpecExplorer.exe was launched to determine an effective path: <specexplorer.exe launch dirpath>/<DirPath>. If this argument is not specified, the default effective path used is: <specexplorer.exe launch dirpath>/ExplorationResults. Short form: /erp:
  • /OnTheFlyAllowEndingAtEventState: true | false
    This switch allows OTF testing to end at a state where one or more following events are expected. Default is "false". Short form: /otfaeaes:
  • /OnTheFlyMaximumExperimentCount: number, 'none'
    Defines the maximum number of experiments allows in one on-the-fly testing test run before attempting to shut down (at the first encountered accepting state). The value of "none" (without quotation marks) means that the number of experiments is not limited.
  • /ReplayTestResultFile: <filename>
    The name of an exploration result file used to replay a test case in on-the-fly testing. The file is required for this switch. When set, on-the-fly testing will replay the test case in the file. /task:DoOnTheFlyTests must be specified to use this switch. This switch supports only one file per test run. Short form: /rtrf:
  • /TestResultPath: <DirPath>
    Specifies the directory for storing on-the-fly testing test result files. The <DirPath> value is used relative to the current working directory from where SpecExplorer.exe was launched to determine an effective path: <specexplorer.exe launch dirpath>/<DirPath>. If this argument is not specified, the default effective path is: <specexplorer.exe launch dirpath>/TestResults. Short form: /trp:
  • /UserTasks: <ClassNameA>, <ClassNameB>, ...
    This optional argument works only in conjunction with the /task:PerformUserTasks argument. This argument specifies a comma-separated list of class names. Each is the class name of a post-processor class that implements the IPostProcessor interface. For example,
    /UserTasks:RequirementCoveragePostProcessor,AnotherPostProcessor. The class names can be either the full name or short name of the class. If this argument is not specified, the default list of user tasks corresponds to the set of pre-registered post-processor user tasks. For more details on implementing post-processors, see Customized Post-Processing. Short form: /u:
  • /verbose
    This argument enables console status messages that list the user tasks found in the post-processor directory and that provide periodic status during post-processing. By default such messages are disabled. Short form: /v
  • /?
    Lists SpecExplorer.exe invocation usage help to console output.

Example

Here is an example invocation of SpecExplorer.exe (all on one command line):

Specexplorer.exe /task:generatetests /assemblies:cashModel.dll,cashSystem.dll /scripts:deposit.cord,printnewmoney.cord /machines:bank.*

Assuming the machines bankBig, bankMedium, and bankSmall are the action machines specified by the /machines: argument, this generates the test suites for those machines using assemblies cashModel.dll and cashSystem.dll to resolve references from scripts deposit.cord and printnewmoney.cord, and from other referenced types not in the GAC (that is, the .NET Global Assembly Cache).

See Also

Concepts

Using Spec Explorer
Getting and Installing Spec Explorer
Customized Post-Processing
Testing