SessionCreator

Applies to TestComplete 14.40, last modified on April 22, 2021

About

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

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

You control the utility via the 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 <TestComplete>\Bin folder. It controls the 32-bit version of TestComplete.

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

RunTest

The RunTest command opens an interactive user session (or connects to an existing session) using the specified credentials and runs the specified TestComplete 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 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, TestComplete 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, TestComplete will save the file to the current TestComplete folder (by default, it is the project folder).

/ExportSummary:file_name (or /es:file_name)

The utility commands the product 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, the product will overwrite it.

  • We recommend that the file_name parameter specify a fully-qualified file name. If the parameter value does not include the path to a folder, TestComplete saves 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 TestComplete 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 TestComplete (or TestExecute) and the test run time.

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

Starting from version 14.40, this command line argument is available only if you have an active license for the Intelligent Quality add-on. Enables (On) or disables (Off) self-healing tests in TestComplete.

If self-healing tests are enabled and TestComplete 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 continue the test run. After the test run is over, the test log will include a warning message informing about the issue and suggesting that you update the recognition criteria of the missing object to match the replacement object.

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

/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 on its Test Items page.

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. Project items are elements that belong to your project (for instance, a keyword test) and that you can view in the Project Explorer.

/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.

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. Project items are elements that belong to your project (for instance, a keyword test) and that you can view in the Project Explorer.

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

The utility commands the product to run the specified test of the specified project or 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 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 the parent test items and groups. Enclose full test names in quotes.

      For example:

      "ProjectTestItem1"

      "ProjectTestItem1|ProjectChildTestItem1"

      "Group1|ProjectTestItem1"

    Note: TestComplete executes only those test items that are enabled on the Test Items page. 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 containing 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 TestComplete 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 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 using the utility. They show how 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 TestComplete 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 TestComplete 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 TestComplete 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 TestComplete 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 TestComplete 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 TestComplete 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 TestComplete 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 TestComplete 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 TestComplete 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 TestComplete 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:

  • The project (or project suite) path is specified incorrectly.

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

  • There are no selected test items to be run.

  • A test item refers to an unavailable test (for example, a keyword test or 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 file the /ExportLog argument specifies already exists.

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, the test engine considers the test was unable to start.
4 The test run was stopped by the timeout specified via the /Timeout command-line argument. For more information, see Terminating Tests on Timeout.
7 Failed to run TestComplete (or TestExecute).
8 Failed to parse the specified command.
127 Unable to launch TestComplete, because some TestComplete files are missing or the installation is damaged.
1000 Unable to launch TestComplete, because another instance of TestComplete is already running.
1001 Unable to start TestComplete, because there is not enough free disk space.
-1 Unable to launch TestComplete because the license check has failed and TestComplete cannot obtain a license. You can find information on TestComplete licensing in Licensing.

You can inspect 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 TestComplete

Highlight search results