SessionCreator

Applies to TestExecute 14.72, last modified on January 12, 2021

About

To run automated tests that simulate user actions over GUI, TestExecute requires an interactive user session to be opened on your test workstation. Otherwise, the test engine will not be able to access the GUI and tests will fail. If your tests run in an unattended mode (for example, if they are run on remote test agents controlled by a continuous integration system), your testing environment must have an interactive session opened before the testing starts.

To open user sessions and start test runs, you can use the SessionCreator utility. The utility is shipped with TestExecute. It allows opening interactive user sessions so that the test engine is able to interact with GUI. You can use the utility to create a user session using the specified credentials or connect to an existing session and then command the product to start testing or to launch the REST service on the specified port.

You control the utility by using command line.

Command-Line Syntax

The SessionCreator utility command line is as follows:

SessionCreator.exe RunTest {options} | StartRestServer {options} [/Help]

Here, the pipe character means OR. The square brackets mean that the argument or a group of arguments is optional.

Note: The utility has 32-bit and 64-bit executables:

  • The SessionCreator 32-bit executable is located in the <TestExecute>\Bin folder. It controls the 32-bit version of TestExecute.

  • The SessionCreator 64-bit executable is located in the <TestExecute>\x64\Bin folder. It controls the 64-bit version of TestExecute.

RunTest

The RunTest command opens an interactive user session (or connects to an existing session) using the specified credentials and runs the specified TestExecute test.

The following options are available:

/UserName:user_name

Specifies the user name that will be used to start a session or to connect to an existing session.

/Password:password

Specifies the password that will be used to start a session or to connect to an existing session.

The password will not be encrypted.

/PasswordFile:password_file_name

Specifies the file from which the utility will read the password that will be used to start a session or to connect to an existing session. The file must support the UTF-8 encoding and must reside in a location where the utility can access it.

/UseActiveSession (or /UA)

Specifies whether the utility will use the currently active session. If you omit this parameter, the utility will stop the current session and will start a new session using the provided credentials.

/ScreenResolution:resolution

The screen resolution to set in the created user session, in the width*height format. The default value is '1280*1024'.

/ProjectPath:file_name

Specifies the path to the project suite file (.pjs) or to the project file (.mds) that contains the tests you want to run.

/ExportLog:file_name (or /el:file_name)

The utility commands the product to export the test results to the file specified by the file_name parameter after the test run is over.

The following formats are supported:

  • .mht
  • .tcLogX
  • .html
  • .htm

Notes:

  • file_name should specify the name of a non-existing file. If it specifies an existing file, TestExecute will fail to run the test.

  • It is recommended that file_name specify the fully-qualified file name. If the parameter value does not include the folder path, TestExecute will save the file to the current TestExecute folder (by default, it is the project folder).

/ExportSummary:file_name (or /es:file_name)

The utility commands TestExecute to generate a Summary report for the current test run and to save it in the JUnit report format to the XML file specified by the file_name parameter.

The report will include the total number of run tests, the number of passed tests and the number of failed tests.

Notes:

  • If the file_name parameter specifies an existing file, TestExecute will overwrite it.

  • We recommend that the file_name parameter specify the fully-qualified file name. If the parameter value does not include the folder path, TestExecute will save the file to the current working folder (by default, it is the project folder).

/Timeout:time_in_seconds

Specifies a timeout for the testing session, in seconds.

If the testing session is still running after the timeout has elapsed, the utility will stop the session and report an error. The other tests will be canceled and TestExecute will be closed.

Possible values are 30…4 294 967 seconds (49.7 days). If the specified value is out of range, the closest in-range value is used.

Note: The timeout includes both the time it takes to launch TestExecute and the test run time.

/SelfHealing:On | Off (or /SH:On | Off)

Enables (On) or disables (Off) self-healing tests in TestExecute.

If self-healing tests are enabled (default behavior) and TestExecute fails to find a tested object during the test run, it will try to find a replacement object to use it in the test instead of the missing one and will continue the test run. After the test run is over, the test log will include a warning message informing about the issue and suggesting updating the mapping criteria of the missing object to match the replacement object. Open the project in TestComplete and update the criteria as suggested.

If self-healing tests are disabled and TestExecute fails to find a tested object during the test run, it will report the “The Object Does Not Exist” error. Depending on the project settings, it will stop the test run.

/PSVar:VarName=VarValue (or /psv)   /PrjVar:VarName=VarValue (or /pv)

TestExecute will assign a specified value to a specified project suite or project variable at runtime.

Variable values you pass via the command line are temporary. At the beginning of the test run, they overwrite the initial value of appropriate variables of your project or project suite. After the test run is over, the variable values are restored to their initial state.
If the variable you set via the command line does not exist in your project or project suite, it will be created at the beginning of the test run and removed after the test run is complete.
If you run several projects that have a project variable with the same name, the command will set the variable value in all executed projects.

/project:project_name (or /p:project_name)

The utility will command the product to run the specified project. Specify the project name as it is shown in the Project Explorer.

The project will run all the test items enabled in its Execution Plan editor.

Note: Do not confuse test items with project items. Test items are a sequence of tests to run. You specify them on the Test Items page of your project in TestComplete. Project items are elements that belong to your project (for instance, a keyword test) and that you can view in the Project Explorer in TestComplete.

/project:project_name (or /p:project_name)  /projectitem:item_name (or /pi:item_name)

The utility will command the product to run the specified project item. You can view project items in the Project Explorer panel in TestComplete.

Project_name is the name of the project as it is shown in the Project Explorer panel.

Item_name is the name of a project item (you can view these items in the Project Explorer). You can run only those project items that have the Run item in their context menu. For example, in this way, you can run the Network Suite project item.

Note: Do not confuse test items with project items. Test items are a sequence of tests to run. You specify them on the Test Items page of your project in TestComplete. Project items are elements that belong to your project (for instance, a keyword test) and that you can view in the Project Explorer in TestComplete.

/project:project_name (or /p:project_name)  /test:test_name (or /t:test_name)

The utility commands the product to run the specified project’s test or the project’s tests that match the specified tag.

Project_name specifies the name of the project that holds the needed test or tests (use the same name as that shown in the Project Explorer panel).

Test_name is the full name of the needed test or the tag assigned to the needed tests:

  • Test full name

    • For project items, the full name includes the name of the collection to which the item belongs and the item name separated by the pipe character. For script tests, the full name also includes the the name of the unit. Enclose your tests’ full names in quotes.

      Do not include any logical project folders in your test's full name.

      For example:

      "KeywordTests|Test1"

      "Scenarios|FeatureFile1"

      "Scenarios|Feature 1|My scenario description"

      "Scenarios|@tag"

      "LLCollection1|LLP1"

      "ManualTests|ManualTest1"

      "ReadyAPI1|Test1"

      "UnitTesting1|NUnit1"

      "Script|Unit1|Main"

      "NetworkSuite|Jobs|Job1|Job1" (For a network suite’s jobs, the name of the Jobs collection and the name of the job are the same)

      "NetworkSuite|Jobs|Job1|Task1"

    • For test items, the full name is specified according to the item hierarchy on the View > Organize Tests page, including parent test items and groups. Enclose the test full names in quotation marks.

      For example:

      "ProjectTestItem1"

      "ProjectTestItem1|ProjectChildTestItem1"

      "Group1|ProjectTestItem1"

    Note: TestExecute executes only those test items that are enabled in the Execution Plan editor. The disabled items are not run.
  • Tag

    To run scripts, keyword tests, and BDD scenarios that match a tag, specify the tag name in the @tag_name format. For example:

    "@AllTests"

    "@low-priority"

/project:project_name (or /p:project_name)  /unit:unit_name (or /u:unit_name)  /routine:routine_name (or /rt:routine_name)

The utility commands the product to run the specified script routine of the specified project. Project_name specifies the name of the project to which the routine belongs. Unit_name specifies the name of the unit holding the desired routine. Routine_name is the name of the script routine to be called. The routine to be called must not use parameters or return any values.

/project:project_name (or /p:project_name)  /tags:tag_expression

The utility commands the product to run the specified project’s test or tests that match the specified tag expression.

Tag expression syntax

For example:

"@AllTests"

"@low-priority and @normal-priority"

"(@high-priority or (@Web-Store-Test and @FF))"

/Help (or /H)

Shows information on the RunTest command.

Note: If this parameter is used, the utility will not open any sessions and run any tests (if any are specified).

StartRestServer

The StartRestServer command opens an interactive user session (or connects to an existing session) using the specified login and password and runs the RESTful web service.

The following options are available:

/RestServerPort:port_number (or /R:port_number)

Specifies a port for the RESTful web service. The default value is 2377.

/UserName:user_name (or /u:user_name)

Specifies the user name that will be used to start a session or to connect to an existing session.

/Password:password

Specifies the password that will be used to start a session or to connect to an existing session.

The password will not be encrypted.

/PasswordFile:password_file_name

Specifies the file from which the utility will read the password that will be used to start a session or to connect to an existing session. The file must support the UTF-8 encoding and must reside in a location where the utility can access it.

/UseActiveSession (or /UA)

Specifies whether the utility will use the currently active session. If you omit this parameter, the utility will stop the current session and will start a new session using the provided credentials.

/Help (or /H)

Shows information on the StartRestServer command.

/Help

Shows help information on the utility.

Examples

Below are several examples of how to use the utility to start interactive user sessions, run tests and how to start the REST web service.

Note: The sample command lines below may split into two or more lines. This is a visual effect that depends on the width of the help viewer’s window. When specifying a command line for the utility, type all the command-line arguments in the same line.
  • The following command starts a user session and commands TestExecute to run the specified project:

    SessionCreator.exe RunTest /UserName:Tester /password:mypassword1 /ProjectPath:"C:\tests\MyProject.mds"

  • The following command connects to an existing user session and commands TestExecute to run the specified project suite:

    SessionCreator.exe RunTest /UserName:Tester /password:mypassword1 /UseActiveSession /ProjectPath:"C:\tests\MyProjectSuite.pjs"

  • The following command reads a password from a file, uses the password to start a session, and runs the specified project:

    SessionCreator.exe RunTest /UserName:Tester /PasswordFile:"C:\MyPassword.txt" /ProjectPath:"C:\tests\MyProject.mds"

  • The following command starts a user session, sets a display resolution for the session, and commands TestExecute to run the specified project:

    SessionCreator.exe RunTest /UserName:Tester /password:mypassword1 /ScreenResolution:"1920*1020" /ProjectPath:"C:\tests\MyProject.mds"

  • The following command starts a user session and commands TestExecute to run the specified project of a project suite:

    SessionCreator.exe RunTest /UserName:Tester /password:mypassword1 /ProjectPath:"C:\tests\MyProjectSuite.pjs" /project:Test_Project

  • The following command starts a user session and commands TestExecute to run the keyword test Test1 from the specified project:

    SessionCreator.exe RunTest /UserName:Tester /password:mypassword1 /ProjectPath:"C:\tests\MyProjectSuite.pjs" /project:Test_Project /test:KeywordTests|Test1

  • The following command starts a user session and commands TestExecute to run the Test1 script routine of the Unit1 unit that belongs to the specified project:

    SessionCreator.exe RunTest /UserName:Tester /password:mypassword1 /ProjectPath:"C:\tests\MyProjectSuite.pjs" /project:Test_Project /unit:Unit1 /routine:Test1

  • The following command starts a user session and commands TestExecute to run the specified project. It sets the 300-second timeout for the test run:

    SessionCreator.exe RunTest /UserName:Tester /password:mypassword1 /ProjectPath:"C:\tests\MyProject.mds" /Timeout:300

  • The following command starts a user session and commands TestExecute to run the specified project and to save the test results to an MHT file:

    SessionCreator.exe RunTest /UserName:Tester /password:mypassword1 /ProjectPath:"C:\tests\MyProject.mds" /ExportLog:"C:\tests\results\test-results.mht"

  • The following command starts a user session and commands TestExecute to start its REST service. The REST service will be available through the default port (2377):

    SessionCreator.exe StartRestServer /UserName:Tester /password:mypassword1

  • The following command starts a user session and commands TestExecute to start its REST service. The service will be available through the specified port:

    SessionCreator.exe StartRestServer /RestServerPort:6001 /UserName:Tester /password:mypassword1

Exit Codes

The SessionCreator utility provides the following exit codes:

Exit Code Description
0 The test run was successful (contains no warnings or errors in the test log).
1 The test run passed with warnings.
2 The test run failed (the test log contains errors). The utility will also return the error messages.
3 Failed to run the tests. Typical reasons for this can include the following:
  • TestComplete or TestExecute is already running (only one instance of TestComplete or TestExecute can be run at once on a single computer).

  • The specified project (or project suite) cannot be opened because the current user does not have appropriate permissions for this.

  • Test items are not selected to be run.

  • A test item refers to an unavailable element to be run (for example, a script routine that does not exist, or a project item that is unavailable because the needed plugins are disabled or not installed).

  • A test item is disabled or does not exist (for example, it could be deleted or renamed).

  • A project item file does not exist (for example, it could have been deleted, renamed, or moved to another folder).

  • The script contains a syntax error.

The test engine also returns the code 3, if you run a project or project suite and the test was stopped with a call to the Runner.Stop method within the OnStartTest event handler. In this case, TestExecute considers the test was unable to start.

4 The test run was stopped by the timeout specified via the /Timeout command-line argument.
7 Failed to run TestExecute.
8 Failed to parse the specified command.
127 Unable to launch the product, because some product files are missing or the installation is damaged.
1000 Unable to launch the product, because another instance of the product is already running.
1001 Unable to start the product, because there is not enough free disk space.
-1 Unable to launch the product because the license check has failed and the product cannot obtain a license. You can find information on licensing in Licensing TestExecute.

You can view the Silent.log file to get more information on possible reasons of the license check failure. The file is in the <System_Drive>:\Users\<User_Name>\AppData\Roaming\SmartBear\TestComplete\14.0 folder.

To resolve licensing problems, you can use the Licensing Troubleshooter on our web site:

Licensing Troubleshooter

Known Issues

If your test workstation is running under a non-server version of Windows, and a session for the user account under which you want to run your test is already open on the workstation, use the /UseActiveSession argument to command the utility to connect to the existing session. Otherwise, the testing will not start.

See Also

Automating TestExecute Test Runs

Highlight search results