TestComplete Service REST API

Your test hosts (the computers where you will enable the API and run tests) must meet the following requirements:

• TestComplete 14 or TestExecute 14 must be installed on the computer.

• TestComplete 14 Service must be running on the computer (by default, the service is launched automatically at Windows startup).

• The TestComplete Service API must be enabled. To learn how to enable the API, see below.

• The TCP port through which you will access the API must be opened inbound by the firewall on the test host. To learn how to specify the port and how to allow traffic through it, see below.

• The user account under which you want to run tests must be allowed to connect to your test host via RDP:

  See instructions

  See instructionsSee instructions

  1. On your test host, set the System properties > Remote > Remote Desktop option to:

     • In Windows 10 and Windows 8 – Allow remote connections to this computer.

     • In Windows 7 – Allow connections from computers running any version of Remote Desktop (less secure).

  2. Add a user account under which you will run tests to the Remote Desktop Users group.

  3. Make sure that the user account has a non-empty password.

• To be able to connect to your test host and create interactive user sessions on it, configure group policies on the host in the following way:

  See instructions

  See instructionsSee instructions

  1. On your test host, open the Group Policy editor (type gpedit.msc in the Search dialog and press Enter).

  2. Disable the following policies:

     • Require user authentication for remote connection by using Network Level Authentication

     • 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, Windows 7 and Windows Server 2012:

        Local Computer Policy > Computer Configuration > Administrative Templates > All Settings

        On 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 and Require user authentication for remote connection by using Network Level Authentication items.

     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.

  3. If the computer 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.

  4. If the computer is running under a non-server edition of Windows and it has other users logged in, log off those users.

  5. If the computer 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)

     • 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

     To enable the needed policy on Windows Server 2016To enable the needed policy on Windows Server 2016

     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 node is running in Remote Administration Server mode and there are user sessions opened on it, close unnecessary sessions.

  6. If the slave computer 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 your slave computer, 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.

• If your TestComplete tests require administrator privileges to run, disable User Account Control (UAC) on the test host. To learn how to disable UAC, see Using TestComplete With Administrator Privileges.

  Disabling UAC reduces Windows security.

• The project suite must not have any external dependencies. For example, if the test uses an Excel or CSV data file, the file must be included in the project suite. To learn how to add external files to your project suites, see Adding Arbitrary Files to Projects.

• The tests you will run must not take parameters.

• Your tests must be computer-independent. See Avoiding Computer-Specific Settings.

• The tests you will run must have access to all the resources they need to run from the test host. For example, your tests must be able to access your tested application from the test host. If your tests get test data from a data storage, they must be able to access it from the test host.

• Your project suite and all its files must be packed to a ZIP archive:

  • The resulting .zip archive should include all the files needed for your tests to run.

  • The project suite file (.pjs) should be in the archive root. Do not place it in a subfolder.

  • The archive must include only one project suite.

  Show me

  Show meShow meCorrect

  

  Incorrect

By default, the TestComplete Service API is disabled. You can enable it:

Using a batch file

Manually, by using the Windows registry

1. On test host, open the Windows Control Panel.

2. In the search box, type Firewall and then select Windows Firewall.

3. On the left of the Windows Firewall window, click Advanced settings.

4. In the Windows Firewall with Advanced Settings window, click Inbound rules.

5. Click New Rule in the Actions panel of the window.

6. In the resulting New Inbound Rule Wizard, create a new rule:

   • On the Rule Type page, select Port.

   • On the Protocol and Ports page, select Port. In the local ports edit box, enter the API port (by default, 1880).

   • On the Actions page, select All the connections and click Next.

   • On the Profile page, select the network location for which you want to open the port.

   • On the Name page, in the Name field, enter the rule name.

Open API 3.0: http://<your_test_host>:<port>/1/resources/swagger_v3.json

Swagger 1.2: http://<your_test_host>:<port>/1/resources/swagger_v1.json

To run tests on a remote computer, you need to upload your project suite to it. To do this, first you need to pack all the project suite files into a .zip archive. You can use any ZIP archiver to do that.

For the requirements the project suite and the resulting archive must meet, see above.

To upload the .zip archive with your project suite to the remote computer, use the POST /suites operation:

The API will return the project suite ID that you can use in further requests:

After you upload your project suite to the test computer, use the POST /suites/{id}/open operation to create an interactive session on the test computer, start TestComplete (or TestExecute) in that session and load the project suite in that TestComplete (or TestExecute) instance. id is the identifier of the project suite you uploaded on the previous step.

If the remote computer is working under a server operating system, then every call to this operation will create a new user session. If the operating system is a non-server one, this operation will close the existing session and will start a new one.

Here is an example of the response

The instance response field is the identifier of the started TestComplete instance with the loaded project suite in it.

A successful response here means the request has been accepted and is being processed. It does not mean a user session has already been opened. To determine that the session has been created, TestComplete has started and the project suite has been loaded, query GET /instances/{id}/ repeatedly until you get ready or error in its result.state response field. creating means the instance is still being initialized. If you get error, check the result.message field to learn what went wrong.

Before running tests, you can check what runnable items (script functions, keywords tests, project items, projects, and so on) your project suite contains. To do this, use the GET /instances/{id}/runnables operation. id here is the identifier of the instance you created on the previous step:

The operation response looks as follows. The projects.items.name field contains the names of runnable tests:

To run a test on the remote computer, use the POST /instances/{id}/run?project=...&run_item=... operation. It has the following parameters:

• id is the identifier of the project suite instance that you created at step 3.

• project is the name of the project that contains the desired test.

• run_item is the name of the test to be run. Use the format like “Script|Unit1|Function1” or “KeywordTests|Test1”, that is, the format you see in the response at step 4.

Here are some examples:

• Run the whole project suite (no project and run_item parameters are specified):

  curl -u DOMAIN\user:password -X POST https://tchost:1880/1/instances/15743972/run

• Run a project:

  curl -u DOMAIN\user:password -X POST https://tchost:1880/1/instances/15743972/run?project=ProjectName

• Run a test in a project:

  curl -u DOMAIN\user:password -X POST https://tchost:1880/1/instances/15743972/run?project=ProjectName&run_item=Project|Item|Name

Result

A successful result indicates that the service accepted the request. It does not mean that the test run is over.

After receiving a request, the service sets the instance state to executing. To detect the end of the test run, query GET /instances/{id} in a loop until you get ready or error in its result.state response field.

ready means the test run is over (passed or failed), and you can get the test results (see step 6). error indicates the test engine faced some unexpected error (rarely), could not complete the run and could not generate test results.

To get the latest test results, use the GET /instances/{id}/summary operation. Here id is the identifier of the desired instance:

To close the instance, use the operation DELETE /instances/{id}. It will unload TestComplete (or TestExecute) from memory and close the interactive user session TestComplete Service created to run your tests.

If needed, you can also delete your project suite from the remote computer:

The batch file is shipped with TestComplete (and TestExecute) and resides in the product folder.

1. Log in to your test host.

2. Locate the batch file and run it as administrator:

   <TestComplete 14>\Bin\TestCompleteService14RestApiDisable.bat

The batch file will disable the API, restart TestComplete Service and will close automatically.

1. Log in to your test host.

2. Launch the Registry editor (regedit.exe).

3. Locate one of the following Registry keys (depending on whether your computer is running under a 32-bit or 64-bit operating system):

   On the 64-bit version of Windows:

   HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\SmartBear\TestCompleteService\14.0

   On the 32-bit version of Windows:

   HKEY_LOCAL_MACHINE\SOFTWARE\SmartBear\TestCompleteService\14.0

4. Locate the RestAPIEnabled value and set it to 0.

5. For the changes to come into effect, restart TestComplete Service running on the test host.