TestEngine Command-Line Tool

Applies to TestEngine 1.31, last modified on June 07, 2024

Use the TestEngine command-line tool to administer TestEngine and run tests.

The tool is the testengine.js file that is not shipped with TestEngine. Download it by using the npm tool.

Requirements

To use the TestEngine command-line tool, you need to download and install node.js:

https://nodejs.org/en/

Install the TestEngine command-line tool

You install the command-line tool by using the npm tool from the node installation:

npm install -g testengine-cli

After you execute this command, the testengine command will be available in your terminal.

Connecting to TestEngine

The TestEngine command-line tool requires the address of the host to which it should connect and the credentials of a TestEngine user. You can specify them either in the command line, or in a configuration file.

Add the following parameters to your command line:

Parameter Description
-u The name of the user in TestEngine.
-p The user password.
-H The address (host:port) of TestEngine to which you want to connect.

For example:

testengine -u john.smith -p passwOrd -h http://localhost:8080 [other options] <command> <command parameters>

  • Create a text file containing the following JSON object:

    JSON

    JSON

    {
        "username": "string",
        "password": "string",
        "host": "string"
    }

    where —

    Parameter Description
    username The name of the user in TestEngine.
    password The user password.
    host The address (host:port) of TestEngine to which you want to connect.

  • Specify the path to the configuration file in the command line by using the -c argument. For example:

    testengine -c testengine.conf [other options] <command> <command parameters>

Command line options

These options configure the command-line tool.

testengine [options] <command> <command parameters>

-c (--config) <filename>

Specifies the configuration file to use in the command (see above).

-H (--host) <hostname>

Specifies the address of TestEngine you want to connect to (see above).

-h (--help)

Displays a help message.

-P (--progress)

Enables showing progress in the output.

-p (--password) <password>

Specifies the user password used to connect to TestEngine (see above).

-q (--quiet)

Runs the command in silent mode. The command-line tool will not print the output.

-u (--username) <username>

Specifies the username used to connect to TestEngine (see above).

-V (--version)

Displays the version of the command-line tool.

-v (--verbose)

Enables more detailed output.

Available commands

The command line must also contain a command to run and the desired parameters:

testengine [options] <command> <command parameters>

The command line tool provides the following commands:

Command Description
auditlog Gets the TestEngine Audit Log.
jobs Retrieves, cancels or removes test jobs.
run Runs a test.
user Adds, removes or modifies TestEngine users.

auditlog dump [format=text/csv/json] [limit=n] [date=YYYY-MM-DD[:YYYY-MM-DD]] [user=username]

Prints the Audit Log.

  • format (Optional) The output format. Possible values:

    • text - Prints the Audit Log in a reader-friendly format.

    • csv - Prints the Audit Log in a comma-separated format.

    • json - Prints the Audit Log in the JSON format.

  • limit=n (Optional) Limits the output entries.

  • date=YYYY-MM-DD[:YYYY-MM-DD] (Optional) Specifies the date filter applied to the Audit Log. Possible values:

    • Single date: date=YYYY-MM-DD - Outputs entries for the specified date.
    • Date range: date=YYYY-MM-DD:YYYY-MM-DD - Outputs entries within the specified date range (including borders). The first date must be earlier than the second.

  • user=username (Optional) Filters the Audit Log entries by the specified user.

Example:

testengine -c .\testengine.conf auditlog dump format=text limit=10 date=2019-06-15:2019-06-19 user=john.smith

jobs list [format=text/csv/json] [user=usernames] [status=statuses)]

Prints a list of tests sent to TestEngine.

  • format - (Optional) The output format. Possible values:

    • text - Prints the list in a reader-friendly format.

    • csv - Prints the list in a comma-separated format.

    • json - Prints the list in the JSON format.

  • user - (Optional) A comma-separated list of users whose test jobs should be listed.

  • status - (Optional) A comma-separated list of statuses to filter the test jobs by.

Example:

testengine -c .\testengine.conf jobs list format=text user=admin,john.smith status=failed,canceled

jobs report output=<directory> [format=excel/json/junit/pdf]<testjobId>

Gets a test job report.

  • output - (Required) The folder where TestEngine should save the test report.

  • format - (Optional) The report type. Possible values:

    • junit - (Default) Saves a report to the JUnit XML format (an XML file).

    • excel - Saves a report in a Microsoft Excel sheet (a XSLX file).

    • json - Saves a report in the JSON format (a JSON file).

    • pdf - Saves a report in a PDF file.

  • testjobId - (Required) The ID of the test job to cancel. You can get the test job id by running jobs list, or by clicking on the Overview page in the web interface.

printReport <testjobId>

Prints a test job report to the console.

  • testjobId - (Required) The ID of the test job the report of which you want to get. You can get the test job id by running jobs list, or by clicking on the Overview page in the web interface.

Example:

testengine -c .\testengine.conf jobs printReport 810a8344-9a74-4f20-a1fc-2f32121f4c36

jobs status <testjobId>

Gets the status of a test job.

  • testjobId - (Required) The ID of the test job the status of which you want to get. You can get the test job id by running jobs list, or by clicking on the Overview page in the web interface.

Example:

testengine -c .\testengine.conf jobs status 810a8344-9a74-4f20-a1fc-2f32121f4c36

jobs cancel <testjobId>

Cancels the running test job.

  • testjobId - (Required) The ID of the test job to cancel. You can get the test job id by running jobs list, or by clicking on the Overview page in the web interface.

Example:

testengine -c .\testengine.conf jobs cancel 810a8344-9a74-4f20-a1fc-2f32121f4c36

jobs delete <testjobId>

Removes a test job from the history.

  • testjobId - (Required) The ID of the test job you want to delete. You can get the test job id by running jobs list, or by clicking on the Overview page in the web interface.

Example:

testengine -c .\testengine.conf jobs delete 810a8344-9a74-4f20-a1fc-2f32121f4c36

jobs prune [before=YYY-MM-DD]

Removes test jobs from TestEngine’s database.

  • before - (Optional) Specifies the date before which the test jobs will be deleted. By default, TestEngine will delete the test jobs according to the Maximum days to keep and Maximum jobs to keep options (see Configure TestEngine).

Example:

testengine -c .\testengine.conf jobs prune before=2019-06-01

run project  [testsuite=<name>] [testcase=<name>] [tags=tag1,tag2] [output=<directory>] [printReport] [report=<filename>] [format=<json/junit/excel] [environment=<environment name>] [async] [skipdeps] [priorityJob] [timeout=<seconds>] [projectPassword=<password>] [proxyHost=<hostname>] [proxyPort=<port>] [proxyUser=<username>] [proxyPassword=<password>] <filename>

Runs a test.

  • filename - (Required) Specifies the ReadyAPI project to run.

  • testsuite - (Optional) Specifies the test suite to run.

  • testcase - (Optional) Specifies the test case to run.

  • securitytest - (Optional) Specifies the security test to run.

    If you specify a security test to be run, do not specify the testsuite and testcase options because TestEngine cannot run both functional tests and security tests within the same test job.

  • tags - (Optional) Specifies a comma-separated list of tags to run.

  • output - (Optional) Exports a test report to the specified folder.

  • printReport - (Optional) Command the command-line tool to print test job report to the console.

  • reportFileName - (Optional) Specifies the name of the report file.

  • format - (Optional) Specifies the report type. Possible values:

    • junit - (Default) Saves a report to the JUnit XML format (an XML file).

    • excel - Saves a report in a Microsoft Excel sheet (a XSLX file).

    • json - Saves a report in the JSON format (a JSON file).

  • environment - (Optional) Specifies the environment to use during the test run.

  • async - (Optional) If this option is specified, the command-line tool will not wait for the test job to finish.

  • skipdeps - (Optional) If this option is specified, the command-line tool will not scan the project for external dependencies. It helps you improve the performance of running large projects.

  • priorityJob - (Optional) Specify this option to skip all non-priority jobs in the queue (requires administrator rights).

  • timeout - (Optional) Specifies a timeout for a test job run in seconds. If a test job runs for the specified amount of time, TestEngine stops it with the FAILED status.

  • projectPassword - (Optional) Specifies the project password (see Protecting Sensitive Data).

  • proxyHost - (Optional) Specifies the proxy host.

  • proxyPort - (Optional) Specifies the port of the proxy.

  • proxyUser - (Optional) Specifies the username to access the proxy.

  • proxyPassword - (Optional) Specifies the password to access the proxy.

Example:

testengine -c .\testengine.conf run project tags=pet,user output=C:\Work\Reports environment=dev C:\Work\ready-api-project.xml

user add <username> <password>

Adds a non-admin user.

  • username - (Required) Specifies the name of a new user.
  • password - (Required) Specifies the password of the new user.

Example:

testengine -c .\testengine.conf user add john.smith passw0rd

user delete <username>

Removes a TestEngine user.

  • username (Required) Specifies the name of the user to be deleted.

Example:

testengine -c .\testengine.conf user delete john.smith

user edit <username> [password=<new password>] [admin=<true or false>]

Modifies the specified user.

  • username (Required) Specifies the name of the user to be modified.

  • password (Optional) Specifies a new password of the user.

  • admin (Optional) Specify true to give the user administrator permissions.

Example:

testengine -c .\testengine.conf user edit john.smith password=NewPassw0rd admin=true

user import <filename>

Imports users from a CSV list. Returns a list of added users.

  • filename (Required) The address (a path or URL) of the CSV file.
    The first row of the file must contain headers:

    username (Required) The name of the user to add.
    password (Optional) If you specify the password column, you will have to to specify passwords for new users, otherwise, they will not be imported.
    If you omit the password column, TestEngine will generate passwords for new users. The output message will contain the generated passwords.
    admin (Optional) Specifies whether a user has administrator permissions. The default value is false.

Example:

testengine -c .\testengine.conf user import C:\Work\newusers.csv

user list [format=text/csv]

Prints a list of existing users.

  • format (Optional) The output format. Possible values:

    • text - Prints the list in a reader-friendly format.

    • csv - Prints the list in a comma-separated format.

Example:

testengine -c .\testengine.conf user list format=text

Exit codes

The command-line tool uses the following exit codes:

0 The latest test job was run successfully.
1 There was an error: the test job failed, the project file was not valid, the command-line tool could not connect to TestEngine, or any other error occurred.

To get the exit code from the command line, use the following command:

PowerShell (Windows)

Command Prompt (Windows)

Terminal (macOS and Linux)

See Also

Administrative Tasks

Highlight search results