TestComplete Command Line

Applies to TestComplete 15.47, last modified on January 20, 2023

Command-line syntax

In general, the TestComplete command line is as follows:

Here the parenthesis mean the group of command-line arguments. The “|” means OR, for example, “/r | /run” means you can use either /r OR /run. Square brackets mean the argument or group of arguments is optional.

Note that TestComplete has two executables for 32-bit and 64-bit:

  • The TestComplete 32-bit executable is located in the <TestComplete>\Bin folder.

  • The TestComplete 64-bit executable is located in the <TestComplete>\x64\Bin folder.

Prerequisites

To run TestComplete by using Windows Task Scheduler (or other tools that launch TestComplete via command line), you may need to configure TestComplete to have proper permissions. See Scheduling Automated Tests.

Calling from CI systems

To run TestComplete tests, an interactive user session is required. CI systems like Jenkins or Bamboo typically use non-interactive user sessions. So, if you run TestComplete from a command line from the CI systems, then your tests will not run successfully.

To work around the issues, we recommend that you use the SessionCreator command line utility — it supports opening interactive user sessions. If you use Jenkins, you can also try a special plugin.

Command-line arguments

file_name

Launches TestComplete and loads the specified project (.mds file) or project suite (.pjs) into it.

/run (or /r)

Commands TestComplete to execute tests provided by the project suite or project specified by the file_name argument or tests provided by a project item or script routine that belongs to this project suite or project. The action TestComplete will perform depends on what other command-line arguments are specified:

/project:project_name

TestComplete will run all enabled test items of the specified project. Project_name is the name of the project as it is shown in the Project Explorer panel. You can view the list of test items in the Execution Plan editor of the project.

TestComplete will run only the enabled test items, it will not run the disabled items.

Note: Do not confuse test items with project items. Test items are a sequence of tests to run that you specify 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 Project Explorer.
/project:project_name  /projectitem:item_name

TestComplete will run test(s) provided by 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. The /projectitem command-line argument must specify the name of a project item. Using this argument, 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. Item_name is the name of the desired project item.

Note: Do not confuse project items with test items. Test items are what is displayed in the Execution Plan editor of the project.
/project:project_name  /test:test_name

TestComplete will run the specified test (or tests). This can be any of the following:

  • A test item you specify on the View > Organize Tests page of the project editor

  • A keyword test

  • A script routine

  • A BDD scenario or feature file

  • A low-level procedure

  • A network suite

  • A network suite’s job

  • A network suite’s task

  • A manual test

  • A Selenium or unit test

  • A ReadyAPI test

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

Test_name specifies the test to run. It can be either the full name of the needed test or a tag:

Full name

Tag

/project:project_name  /unit:unit_name  /routine:routine_name

TestComplete will run the specified script routine. 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_name and unit_name should be the same as the project and unit names shown in the Project Explorer.

/project:project_name  /tags:tag_expression

TestComplete will run all the script functions, keyword tests, BDD scenarios and BDD features that the specified project contains and that match the specified tag or tag expression. Project_name is the name of the project that holds the needed tests (use the same name as shown in the Project Explorer panel). Tag_expression specifies the needed tag or tag expression.

Tag expression syntax

For example:

/tags:@AllTests

/tags:"@low-priority and @normal-priority"

/tags:"(@high-priority or (@Web-Store-Tests and @FF))"

Notes:

  • The tests that match the specified tag or tag expression will be run in an arbitrary order.
  • If both the /test and /tags arguments are specified in the command line, the /test argument will be ignored.
  • If the tags argument specifies an empty tag expression, the command will execute all the tagged tests and scenarios of the specified project.
No /project, /unit or /routine arguments specified.

TestComplete will run the tests provided by the opened project suite.

Notes:

  • Pay attention to the colon between the argument name and the element to which the argument refers. The colon separates the argument name and the element name. Do not insert spaces before or after the colon.

  • If the project name includes spaces, it must be enclosed in double quotes: /project:"My project".

  • The argument names can be shortened. /project can be replaced with /p, /projectitem – with /pi, /test – with /t, /unit – with /u, and /routine – with /rt.

/AccessKey:access_key

This parameter is for those who use SmartBear ID-based licenses of TestComplete. It specifies the access key associated with your SmartBear account and is used to license the product in automated runs that don’t require user interaction. For more information on this and on how to get the key, see Activate TestComplete in CI/CD build runs.

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

Starting from version 14.40, this 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.

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

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

For example:

TestComplete.exe "C:\Work\My Projects\MySuite.pjs" /run /pv:userName=john.smith

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.

Notes:

  • The name of a passed variable should include only alphanumeric characters ('A'..'Z', 'a'..'z' and '0'..'9') and underscores ('_') and does not start with a digit.

  • TestComplete treats variable values passed via the command line as strings. If the value includes spaces, enclose it in quotes.

For details, see Passing Variables via Command Line.

/ExportLog:file_name (or /el:file_name)

Commands TestComplete to export test results to a file specified by the file_name parameter after the test run is over.

Notes:

  • file_name should specify the name of a non-existent 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).

  • For exported results, TestComplete supports the following file extensions:

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

For more information on exporting test results with TestComplete, see Exporting Test Results.

/ExportLogToXMLAlso

When you command TestComplete to export results in the HTML format, it generates JSON data files and HTML, CSS, images, and other helper files. Using this argument in the command line tells TestComplete to generate data files in the XML format in addition to the JSON data files. See Exporting Test Results.

/ExportSummary:file_name (or /es:file_name)

Commands TestComplete 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.

If there are test cases specified for the run, TestComplete will export their results. If no test cases are specified, TestComplete will export the results of the executed tests.

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, TestComplete 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).

/ShareResults:File_To_Save_URL (or /shr:File_To_Save_URL)

Uploads the test results to our online storage and saves the resulting link to the File_To_Save_URL file.

File_To_Save_URL can specify a fully qualified file path, or it can specify the file name only. If the folder path is omitted, TestComplete will save the file to the current TestComplete folder. If a project is run, the current folder is the project folder, if a project suite is run, the current folder is the project suite folder.

File_To_Save_URL must specify a nonexistent file, otherwise TestComplete will not share the results and will report an error.

/SharedResultsName:Name (or /shrn:Name)

This argument can only be used with the /ShareResults argument above.

It specifies the name that will be used for the shared results report. If omitted, the name of the log item will be used.

/SharedResultsExpireIn:Days (or /shrei:Days)

This argument can only be used with the /ShareResults argument above.

Specifies the number of days during which the shared results will be available. Possible values are:

  • 1
  • 7
  • 14

If the argument is omitted, the shared results will expire in 14 days. If a non-supported value is specified, the test results will not be shared and an error will occur.

/SkipVisualizerData

This argument can be used with /ExportLog or with /ShareResults, or with both. If specified, TestComplete will not include Test Visualizer images in the exported results. This can help reduce the exported results' size.

/ErrorLog:file_name

Commands TestComplete to save information on the errors that occurred during the run to the text file the file_name parameter specifies. This file will include information on the errors that occurred in your tests and on the errors that did not allow opening the project or running the test (for example, an incorrect project path).

Notes:

  • file_name should specify a non-existent file. If you specify the name of an existing file, TestComplete will fail to run the test.

  • We recommend 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).

/NoSummary

TestComplete will not include the Summary report in the test log exported by using the /ExportLog command-line argument. It does not affect the /ExportSummary argument.

/exit (or /e)

If this argument is used along with the /run argument, TestComplete will close after the project (or project suite) run is over. If the /exit command-line argument is used without /run, then neither the specified project (project) suite will be run, nor will TestComplete be closed.

Note: If you run tests, the project (or project suite) file will be changed because it will contain a reference to the new log file. TestComplete will display the Confirm dialog asking you to save the changes. To suppress displaying the dialog on exit, specify the /SilentMode command-line argument along with /exit.

/SilentMode

If this argument is specified, TestComplete works in Silent mode, that is, it neither displays dialogs, nor informs you about errors or warnings. The dialogs and messages to be displayed are handled as if you pressed the default button in them. Information about these dialogs and messages is posted to Silent.log file to the <System_Drive>:\Documents and Settings\<UserName>\Application Data\SmartBear\TestComplete\15.0 folder on Windows XP and Windows Server 2003 and to the <System_Drive>:\Users\<UserName>\AppData\Roaming\SmartBear\TestComplete\15.0 folder on Windows Vista, Windows 7, Windows Server 2008 and later operating systems (the file must not be read-only or locked by another application). The errors that occur during the test execution are posted to the test log.

If TestComplete is running in Silent mode, it does not press the default button in the window asking if the user wants to convert the project created in earlier TestComplete versions to the new format. This was done to prevent users from accidental project conversion. To force TestComplete to convert such a project automatically, use the /ForceConversion command-line argument.

If TestComplete running in Silent mode is integrated into a source control system, it tries to enable the batch mode for the source control system. This mode allows working with the source control system without displaying dialogs and messages invoked by the source control system provider. If the source control system does not support the batch mode, TestComplete disables source control integration support. For more information, see Working With Source Control Systems in Silent Mode.

/ForceConversion

If this argument is specified and TestComplete is running in Silent mode, TestComplete automatically converts projects created in earlier versions of the tool to the new format when they are opened.

Notes:

/Timeout:time_in_seconds

Timeout for the TestComplete session in seconds.

This timeout includes both the TestComplete startup time and the test run time.

If a test is still running after the timeout elapses, TestComplete will post an error to the test log and stop the test run. See Stopping Tests on Timeout. All further tests will be canceled. 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.

/ns

Opens TestComplete without displaying the splash screen.

/agpatcheroff

Disables Silverlight auto-patching.

/UsageStatistics:File_name (or /US:File_name)

Commands TestComplete to collect statistics on usage of Name Mapping items during test runs. TestComplete will save the gathered data to the specified file. You can then use this data in the Name Mapping editor and remove unused mapping items. See Find and Remove Unused Mapping Items for details.

If the file name includes spaces, enclose it in quotes:

TestComplete.exe /UsageStatistics:"c:\some shared folder\Name Mapping Data.stat"

/install:extension_name (or /ip:extension_name)

Installs the specified TestComplete plugin and enables it on the product start. The extension_name parameter specifies the fully-qualified name of the desired plugin file (.pls). This command may help you customize a testing environment on remote computers according your needs.

Notes:

  • If the name of the plugin file includes spaces, it must be enclosed in double quotes:

    TestComplete.exe /install:"C:\TestComplete plugins\plugin.pls"
  • You can install only one plugin at a time.

  • When you use the command line to load a project, the specified plugin will be installed before the project is opened.

  • You cannot use this command-line argument to install script extensions.

/uninstall:extension_name (or /up:extension_name)

Uninstalls the specified TestComplete plugin on the product start. The extension_name parameter specifies the fully-qualified name of the plugin file (.pls). This command may help you customize a testing environment on remote computers according your needs.

Notes:

  • If the name of the plugin file includes spaces, it must be enclosed in double quotes:

    TestComplete.exe /uninstall:"C:\TestComplete plugins\plugin.pls"
  • You can uninstall only one plugin at a time.

  • This command will not delete the actual file from the disk.

  • When you use the command line to load a project, the specified plugin will be uninstalled before the project is opened.

  • You cannot use this command-line argument to uninstall script extensions.

/EnableModule:module_set

Available in TestComplete 12.50 and later. Enables or disables available TestComplete modules and add-ons on startup. module_set is the name of the module or add-on to enable, which can be:

  • Desktop

  • Mobile

  • Web

  • Intelligent Quality (or IntelligentQuality, or IQ)

  • DeviceCloud (or DC)

    Note: This add-on can only be used together with the Web module.

If a module or an add-on is not specified, it will be disabled. If the module or add-on name includes spaces, enclose it in double quotes: /EnableModule:"Intelligent Quality".

For example, the following command will run TestComplete with the Desktop and Mobile modules enabled. The Web module and the add-ons will be disabled:

TestComplete.exe /EnableModule:Desktop /EnableModule:Mobile

The following command will run TestComplete with the Desktop module and the Intelligent Quality add-on enabled. The Web and Mobile modules will be disabled:

TestComplete.exe /EnableModule:Desktop /EnableModule:IQ

The following command will run TestComplete with the Web module enabled. The Desktop and Mobile modules and the Intelligent Quality add-on will be disabled:

TestComplete.exe /EnableModule:Web

Note: If you start TestComplete with this command-line argument, the File > Install Extensions dialog will be disabled.

/RestServerPort:port

The port used by the TestComplete RESTful service that is provided by the REST API plugin. The default port is 2377. Make sure this port is allowed through your firewall or antivirus.

/ForkLimitUnlimited

If you use Name Mapping in your tests and have your tested web page added to the Name Mapping repository, it commands the test engine to search for the tested web page in all the web browsers running in your system.

/ForkLimitBrowser

If you use Name Mapping in your tests and have your tested web page added to the Name Mapping repository, it commands the test engine to search for the tested web page only among web pages opened in your current web browser (default behavior).

/ZephyrVersion:version

You can use this argument only if you have TestComplete version 14.10 or later.

If your TestComplete tests are connected to Zephyr tests in your Jira project, this argument specifies the release version of your Jira project to which TestComplete test results will be added. To learn more, see Integration With Zephyr Squad.

/ZephyrCycle:cycle

You can use this argument only if you have TestComplete version 14.10 or later.

If your TestComplete tests are connected to Zephyr tests in your Jira project, this argument specifies the test cycle in your Jira project to which TestComplete test results will be added. To learn more, see Integration With Zephyr Squad.

Note: If neither a release version, nor a test cycle is specified, TestComplete will send the test results to the release version and test cycle that your project settings specify. If the project settings do not specify a release version or a test cycle, TestComplete will send the test results to the default release version (Unscheduled ) and to the default test cycle (Ad hoc).

/DisableExternalReporting

Disables how to send test results to external test management systems (for instance, Zephyr Squad).

Custom parameters

To learn how you can handle custom command-line parameters, see Passing Test Parameters via Command Line.

Stop tests on errors and exceptions

If an error occurs during the test run (for example, if a tested object is not found), TestComplete will post information about it to the test log. Its further behavior depends on the way the test was run:

  • If the test was run as a test item (the /project or the /project and /test:test_item_name arguments were used), the further behavior will be specified by the test item’s On error property. You specify it in the Execution Plan editor of your project.

  • If the test was run by its name or by tag, its behavior will be specified by the project’s Playback > On error property.

Depending on the appropriate property value, TestComplete can do one of the following:

  • Ignore the error and continue the test run.

  • Stop the current test and proceed with the next test (applicable, for example, when running a project or tests by a tag or tag expression).

  • Stop the entire test run.

To learn how to do this, see About Controlling Test Execution Flow.

Remarks

  • Running TestComplete from the command line is, probably, the easiest way to launch it from third-party tools. This approach is used rather frequently for running TestComplete from continuous integration (CI) systems and custom test frameworks. Note that TestComplete requires an interactive user session for simulating user actions. So, if your CI system or test framework runs TestComplete on a remote machine (typically called an agent or node), this CI system or framework should create an interactive user session for the TestComplete run on that agent (node). For information on how to do this, see the CI system documentation.

  • You can determine what parameters were passed to TestComplete in its command line by using the ParamStr function. It allows you to get a TestComplete command-line argument specified by its index. To get the total number of arguments in the command line, use the ParamCount function.

    The following code demonstrates how you can determine command-line arguments:

    JavaScript, JScript

    function CommandLineArgs()
    {
      var i;
      var nArgs = BuiltIn.ParamCount();
      Log.Message("Total number of command-line arguments: " + nArgs);
      Log.Message("The fully-qualified name of the TestComplete executable: " + BuiltIn.ParamStr(0));

      for (i = 1; i <= nArgs ; i++)
        Log.Message("Arg " + i + ": " + BuiltIn.ParamStr(i));
    }

    Python

    def CommandLineArgs():
      nArgs = BuiltIn.ParamCount()
      Log.Message("Total number of command-line arguments: " + str(nArgs))
      Log.Message("The fully-qualified name of the TestComplete executable: " + BuiltIn.ParamStr(0))
    
      for i in range (1, nArgs+1):
        Log.Message("Arg " + str(i) + ": " + BuiltIn.ParamStr(i))

    VBScript

    Sub CommandLineArgs
      Dim nArgs, i

      nArgs = BuiltIn.ParamCount
      Log.Message "Total number of command-line arguments: " & nArgs
      Log.Message "The fully-qualified name of the TestComplete executable: " & BuiltIn.ParamStr(0)

      For i = 1 To nArgs
        Log.Message "Arg " & i & ": " & BuiltIn.ParamStr(i)
      Next
    End Sub

    DelphiScript

    procedure CommandLineArgs;
    var nArgs, i;
    begin
      nArgs := BuiltIn.ParamCount;
      Log.Message('Total number of command-line arguments: ' + VarToStr(nArgs));
      Log.Message('The fully-qualified name of the TestComplete executable: ' + BuiltIn.ParamStr(0));

      for i := 1 to nArgs do
        Log.Message('Arg ' + VarToStr(i) + ': ' + BuiltIn.ParamStr(i));
    end;

    C++Script, C#Script

    function CommandLineArgs()
    {
      var nArgs = BuiltIn["ParamCount"]();
      Log["Message"]("Total number of command-line arguments: " + nArgs);
      Log["Message"]("The fully-qualified name of the TestComplete executable: " + BuiltIn["ParamStr"](0));

      for (var i = 1; i <= nArgs ; i++)
        Log["Message"]("Arg " + i + ": " + BuiltIn["ParamStr"](i));
    }

  • It is not recommended to launch TestComplete using the runas command, since this significantly slows down the test execution.

Examples

Below are several examples of running TestComplete via the command line.

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 TestComplete, type all command-line arguments into the same line.
  • The following command runs TestComplete, loads the specified project suite (MySuite.pjs), and commands TestComplete to execute test items of the MyProj project:

    TestComplete.exe "C:\My Projects\MySuite.pjs" /r /p:MyProj

  • The following command runs TestComplete, loads the specified project suite (MySuite.pjs), and commands TestComplete to execute all projects that are enabled. TestComplete waits until the run is over, and then gets closed.

    TestComplete.exe "C:\Work\My Projects\MySuite.pjs" /r /e

  • The following command runs TestComplete, loads the specified project suite (MySuite.pjs), and commands TestComplete to run the ProjectTestItem3 test item of the MyProj project:

    TestComplete.exe "C:\Work\My Projects\MySuite.pjs" /r /p:MyProj /t:"ProjectTestItem1|ProjectTestItem2|ProjectTestItem3"

  • The following command runs TestComplete, loads the specified project suite (MySuite.pjs), and commands TestComplete to run the tests associated with the NetworkSuite project item of the MyTest project:

    TestComplete.exe "C:\Work\My Projects\MySuite.pjs" /r /p:MyTest /pi:NetworkSuite

  • The following command runs TestComplete, loads the specified project suite (MySuite.pjs), and commands TestComplete to execute the Test1 keyword test of the MyProj project:

    TestComplete.exe "C:\Work\My Projects\MySuite.pjs" /r /p:MyProj /t:"KeywordTests|Test1"

  • The following command runs TestComplete, loads the specified project suite (MySuite.pjs), and commands TestComplete to execute the MyProj project's tests that match the Tag1 tag:

    TestComplete.exe "C:\Work\My Projects\MySuite.pjs" /r /p:MyProj /t:"@Tag1"

  • The following command runs TestComplete, loads the specified project suite (MySuite.pjs), and commands TestComplete to execute the MyProj project’s tests that match the tag expression tag:

    TestComplete.exe "C:\Work\My Projects\MySuite.pjs" /r /p:MyProj /tags:"@tag1 or (@tag2 and @tag3)"

  • The following command runs TestComplete, loads the specified project suite (MySuite.pjs), and commands TestComplete to run the Main script routine located in the Unit1 unit of the MyProj project:

    TestComplete.exe "C:\Work\My Projects\MySuite.pjs" /r /p:MyProj /u:Unit1 /rt:Main

    – or –

    TestComplete.exe "C:\Work\My Projects\MySuite.pjs" /r /p:MyProj /t:"Script|Unit1|Main"

  • The following command launches TestComplete, runs tests of the MyProj project, uploads the test log to our online storage, and saves the resulting link to a text file:

    TestComplete.exe "C:\My Projects\MyProj.mds" /r /sl:"C:\logs\new-log.txt"

  • The following command launches TestComplete, runs tests of the MyProj project, uploads the test results to our online storage, and saves the resulting link to a text file. The shared results will have the specified name and be available for 7 days:

    TestComplete.exe "C:\My Projects\MyProj.mds" /r /shr:"C:\logs\new-log.txt" /shrn:NewTestLog /shrei:7

  • The following command runs TestComplete, loads the MySuite.pjs project suite, commands TestComplete to execute the test items of the MyProj project and to send their test results to the Regression test cycle of the 2.1 version of the Jira project bound to the MyProj project:

    TestComplete.exe "C:\Work\My Projects\MySuite.pjs" /r /p:MyProj /ZephyrVersion:2.1 /ZephyrCycle:Regression

Note: TestComplete waits until the specified project suite, project, test, and so on is executed in all the examples above. However, the command line is ready to receive new commands right after TestComplete has been launched.

If you want the command line to wait until the test (project and so on) execution is over, you can use the START command as shown in the example below:

start "My Title" /wait TestComplete.exe "C:\Work\My Projects\MySuite.pjs" /run /exit /SilentMode

Pay attention to the string after the START command in the example above. It is the title of the command-line window and it is needed for the command to work correctly.

See Also

TestComplete Exit Codes
Scheduling Automated Tests

Highlight search results