SessionCreator is a SmartBear utility shipped with TestComplete (as well as with TestExecute and TestLeft).

The utility opens interactive user sessions required for the TestComplete interaction with your tested application GUI. If an interactive user session is not opened, the test engine will not be able to access the GUI, and your tests will fail.

SessionCreator allows you to run automated tests remotely via continuous integration systems or nightly by the Task Scheduler. Additionally, you can launch a REST service on the specified port.

You control the utility via the command line.

Requirements

Requirements

For correct work with SessionCreator, the following requirements must be met:

1. Enable Remote Desktop connections

By default, computers prohibit remote connections. For SessionCreator to be able to connect to a test workstation and open user sessions on it:

On your test machine, set the System properties > Remote > Remote Desktop option to:
- In Windows 10 and Windows 8.1 – Allow remote connections to this computer.
- In Windows 7 – Allow connections from computers running any version of Remote Desktop (less secure).
Add a user account under which you will run tests on the test workstation to the Remote Desktop Users group.
Make sure that the user account has a non-empty password.

Otherwise, SessionCreator will not be able to open a session.

2. Configure group policies

To be able to connect to a workstation and open a user session on it, configure the following group policies:

On the test workstation, open the Group Policy editor (type gpedit.msc in the Search dialog and press Enter).
Disable the following policies:
- Always prompt client for password upon connection
- Prompt for credentials on the client computer
To disable these policies
To disable these policiesTo disable these policies
1. In the tree on the left of the Group Policy editor, select the following category:
  
  On Windows 10, Windows 8.1, Windows 7, and Windows Server 2012:
  
  Local Computer Policy > Computer Configuration > Administrative Templates > All Settings
  
  On Windows Vista and Windows Server 2008:
  
  Local Computer Policy > Computer Configuration > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Security
2. In the list on the right, double-click the Always prompt client for password upon connection item.
  
  Click Disabled and then click OK.
3. Repeat step 2 for the Prompt for credentials on the client computer item.
If the computer belongs to a domain, you may need to ask your system administrator to disable these policies on the domain controller as well.
If the test workstation is running under Windows 10, enable the Require use of specific security layer for remote (RDP) connections group policy and set the security layer to Negotiate.

To configure the group policy
To configure the group policyTo configure the group policy
1. In the tree on the left of the Group Policy editor, select Local Computer Policy > Computer Configuration > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Security.
2. In the Setting list on the right, double-click the Require use of specific security layer for remote (RDP) connections item.
3. In the subsequent dialog, click Enabled.
4. In the Security Layer drop-down list of the dialog, select Negotiate.
5. Click OK to close the dialog and save the changes.
If the test workstation is running under a non-server edition of Windows and it has other users logged in, log off those users.
If the test workstation is running under a server edition of Windows, enable the following policy:
- Require use of specific security layer for remote (RDP) connections (on Windows Server 2016 or Windows Server 2019)
- Restrict Remote Desktop Services users to a single Remote Desktop Services session (on Windows Server 2012 or Windows Server 2008)
- Restrict Terminal Services users to a single remote session (on Windows Server 2003)
To enable the needed policy on Windows Server 2016 or Windows Server 2019
To enable the needed policy on Windows Server 2016 or Windows Server 2019To enable the needed policy on Windows Server 2016 or Windows Server 2019
1. In the tree on the left of the Group Policy editor, select Local Computer Policy > Computer Configuration > Administrative Templates > Windows Components.
2. Then, select Remote Desktop Services > Remote Desktop Session Host > Security.
3. In the Setting list on the right, double-click the Require use of specific security layer for remote (RDP) connections item.
4. In the subsequent dialog, click Enabled.
5. In the Security Layer drop-down list of the dialog, select Negotiate.
6. Click OK to close the dialog and save the changes.
To enable the needed policy on Windows Server 2008 and later
To enable the needed policy on Windows Server 2008 and laterTo enable the needed policy on Windows Server 2008 and later
1. In the tree on the left of the Group Policy editor, select Computer Configuration > Administrative Templates > Windows Components.
2. Then select Remote Desktop Services > Remote Desktop Session Host > Connections.
3. In the list on the right, double-click the Restrict Remote Desktop Services users to a single Remote Desktop Services session item.
4. Click Enabled and click OK.
To enable the needed policy on Windows Server 2003
To enable the needed policy on Windows Server 2003To enable the needed policy on Windows Server 2003
1. In the tree on the left of the Group Policy editor, select Computer Configuration > Administrative Templates > Windows Components.
2. Then select Terminal Services.
3. In the list on the right, double-click the Restrict Terminal Services users to a single remote session item.
4. Click Enabled and click OK.
If the test workstation is running in Remote Administration Server mode and there are user sessions opened on it, close unnecessary sessions.
If the test workstation is configured to show a logon message when a user logs on, disable the message.

To disable the message
To disable the messageTo disable the message
1. In the tree on the left of the Group Policy editor, select Configuration > Windows Settings > Security Settings > Local Policies > Security Options.
2. In the list on the right, double-click the Interactive logon: Message title for users attempting to log on item.
3. In the resulting dialog, set the title of the logon message to an empty string and click OK to save the changes.
4. Then, right-click the Interactive logon: Message text for users attempting to log on item.
5. Set the text of the logon message to an empty string and click OK.
If the message persists
If the message persistsIf the message persists
1. On the workstation, open the Registry editor (type regedit in the Search dialog and press Enter).
2. Navigate to the following registry key:
  
  HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon
3. Make sure that its LegalNoticeCaption and LegalNoticeText values are set to an empty string.

You can check whether the workstation is configured correctly by connecting to it manually. If it does not show any additional messages or prompts, the group policies are configured correctly. Otherwise, you may need to ask your system administrator to disable those messages.

Sometimes, Windows is configured so that the user has to press Ctrl+Alt+Delete before signing in to prevent unwanted actions the software that simulates user behavior may perform. TestComplete does not provide any means to work around this feature, so we recommend you to turn it off:

On the test workstation, press Win+R to open the Run dialog.
Type control userpasswords2 and press Enter.
In the subsequent User Accounts dialog, switch to the Advanced tab.
Clear the Require users to press Ctrl+Alt+Delete check box.
Click OK or Apply.

4. Disable additional screens

To avoid issues during the testing, make sure that when you connect to the test machine its desktop opens up immediately — that is, no additional screens appear (such as the login form, account selection window, or RDP Certificate Warning windows). To learn how to disable these additional screens, contact your IT department.

Command-Line Syntax

The SessionCreator utility command line is as follows:

SessionCreator.exe RunTest {options} | StartRestServer {options} [/AccessKey:access_key] [/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:

SessionCreator.exe RunTest [/UserName:domain_name\user_name /Password:password | /PasswordFile:password_file_name [/UseActiveSession] [/ScreenResolution:resolution]
/ProjectPath:file_name [/ExportLog:file_name] [/ExportSummary:file_name] [/Timeout:seconds] [/SelfHealing:(On | Off) ]
[/project:project_name | (/project:project_name /projectitem:item_name) | (/project:project_name /test:test_name) | (/project:project_name /unit:unit_name /routine:routine_name) | (/project:project_name /tags:tag_expression)] [/arg:argument_value]] [/Help]

/UserName:domain_name\user_name

Specifies the user name (including a domain 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 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 in the Execution Plan editor 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 in the Execution Plan editor 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 in the View > Organize Tests editor, 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 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 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))"

/arg:argument_value

The utility commands the product to pass the specified argument value as is to the test. You can work with such values in your script tests as described in the Passing Test Parameters via Command Line topic.

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

SessionCreator.exe StartRestServer [/RestServerPort:port_number /UserName:user_name /Password:password | /PasswordFile:password_file_name [/UseActiveSession]] [/Help]

/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 (including a domain 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.

/AccessKey:access_key

If you use SmartBear License Management to control your TestComplete (TestExecute) licenses, use this parameter to specify the access key assigned to your SmartBear account and that will be used to license the TestComplete (TextExecute) instances that will run tests.

Learn how to get the access key

/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:domain\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:domain\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:domain\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:domain\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:domain\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:domain\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:domain\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:domain\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:domain\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:domain\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:domain\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 TestComplete 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
Other codes	You may receive codes different from those above (for example, -10, -12). This can happen if your operating system, firewall, or a third-party application that manages TestComplete test runs overwrites the actual TestComplete exit code. In this case, to learn the received exit code definition, contact your system administrator or the SmartBear Support team.

The exit codes that TestComplete returns depend on whether the project is configured to rerun failed tests. See Stop and Rerun the Current Test Item After an Error for all the details.

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.
If you run tests under a user account other than the one under which the utility is launched, the utility will not be able to open the needed user session. To avoid the issue, launch the utility in Session 0 (an isolated Windows session for services), or use a server edition of your Windows OS to run tests.

SessionCreator 32-bit executable is located in the <TestComplete>\Bin folder. It controls the 32-bit version of the product.