Overview

Scriptworks provides a feature for launching test execution from Command Line calls. The core of this process is to provide a call to the Scriptworks-Client component specifying the tests and configurations to execute using curl (or other command line HTTP request tools).

The client requests test information from the Scriptworks cloud server and in turn orchestrates execution of the tests against the appropriate Selenium or Appium environment:

The Scriptworks Client App can be local or on a remote machine, and the Selenium/Appium Hub can also be on any machine or a cloud provider like Saucelabs or Bitbar, allowing for total flexibility of architecture.

The curl call can also be invoked by Continuous Integration tools, like Jenkins, Bamboo or TeamCity with test execution output in JUnit format for reporting purposes. Please see appropriate documentation for individual tools.

Basic Command Call

The Basic call takes the form:

curl -d '{<params>}' -H "Content-Type: application/json" -X POST '<scriptworks-client-url>/ci/runTests/'

An example of a call to a local client to run all tests tagged as ‘Regression’ using a single target runsetting combination is as follows:

curl -d '{"apiUrl": "https://app.scriptworks.io/api", "projectId": 2, "tags":["Regression"], "runSettingIds":[1],"username":"myuser","password":"mypass"}' -H "Content-Type: application/json" -X POST 'http://127.0.0.1:8081/ci/runTests/'

Mandatory Parameters

The following are basic required parameters, note parameters are case sensitive:

• apiUrl

The URL of the Scriptworks server, usually – https://app.scriptworks.io/api (may be a local server for on-premise deployments)

• username

Username of the Scriptworks user usually Email address of the user

• password

Password of the Scriptworks user

• projectId     

The Numeric id of the project, shown in the Id column of the projects table:

Other Supported Parameters

The following shows other support parameters:

• authToken

Alternative to supplying plain text credentials

• isAsync

For specifying Asynchronous (Concurrent) execution. Valid values: true, false (default)

• outputFormat

To specify alternative output format for results, useful for execution under CI tools e.g. Jenkins, TeamCity. Valid values: Json (default) or JUnit

• runAll

To specify that all tests for a given project are to be executed. Valid values: true, false (default). Overrides testIds and tags settings.

• runSettingsIds

An Array specifying which RunSettings should be used for Execution. Can contain one or more numeric values. Found in the Run Settings List through the UI:

• runSettingsGroupIds

An Array specifying any RunSettings groups that should be used for execution.  Can contain one or more numeric values.

• tags

An Array specifying text of tags used to match tests for execution. Useful as a way of batching tests for execution.

• testIds

An Array specifying the list of numeric test Ids for execution, Ids are found in the Test List through the UI:

Examples

Common scenarios showing examples of parameter combinations are shown in the sections below:

Specifying Tests

Tests can be specified using their Id, Tags or Run All. Test Information is shown in the Test List table for a given project:

Running Individual Tests

Running an individual test requires specifying the test by id, an example for the project above is shown:

curl -d '{"apiUrl": "https://app.scriptworks.io/api", "projectId": 2, "testIds":[1], "runSettingIds":[1],"username":"myuser","password":"mypass"}' -H "Content-Type: application/json" -X POST 'http://127.0.0.1:8081/ci/runTests/'

Running Multiple Tests

Fine control over the individual tests for execution can be achieved by specifying each test in sequence using their individual Id.

curl -d '{"apiUrl": "https://app.scriptworks.io/api", "projectId": 2, "testIds":[1,18,25], "runSettingIds":[1],"username":"myuser","password":"mypass"}' -H "Content-Type: application/json" -X POST 'http://127.0.0.1:8081/ci/runTests/'

Running Tests Specified by Tags

A useful way of grouping tests, a single or set of tags can be executed without the need to specify individual tests:

curl -d '{"apiUrl": "https://app.scriptworks.io/api", "projectId": 2, "tags":["Register"], "runSettingIds":[1],"username":"myuser","password":"mypass"}' -H "Content-Type: application/json" -X POST 'http://127.0.0.1:8081/ci/runTests/'

This way all tests for a particular area can be tagged, or a Confidence/Smoke pack created and executed.

Running All Tests for a Project

To simply run all tests, use the runAll parameter:

curl -d '{"apiUrl": "https://app.scriptworks.io/api", "projectId": 2, "runAll": true, "runSettingIds":[1],"username":"myuser","password":"mypass"}' -H "Content-Type: application/json" -X POST 'http://127.0.0.1:8081/ci/runTests/'

Specifying Run Settings

Run Settings provide information on target environments, browsers and script parameters, it is possible to configure execution to use one or more Run Settings or Run Settings Groups. Id information can be found in the Run Settings List as shown below:

Running with an Individual Run Setting Configuration

curl -d '{"apiUrl": "https://app.scriptworks.io/api", "projectId": 2, "tags":["Register"], "runSettingIds":[1],"username":"myuser","password":"mypass"}' -H "Content-Type: application/json" -X POST 'http://127.0.0.1:8081/ci/runTests/'

Running Multiple Run Settings Configurations

curl -d '{"apiUrl": "https://app.scriptworks.io/api", "projectId": 2, "tags":["Register"], "runSettingIds":[1,3],"username":"myuser","password":"mypass"}' -H "Content-Type: application/json" -X POST 'http://127.0.0.1:8081/ci/runTests/'

Running with a Run Settings Group

curl -d '{"apiUrl": "https://app.scriptworks.io/api", "projectId": 2, "tags":["Register"], "runSettingsGroupIds":[35],"username":"myuser","password":"mypass"}' -H "Content-Type: application/json" -X POST 'http://127.0.0.1:8081/ci/runTests/'

Other Settings

Specifying a Run Name

Run Names are displayed in the Results Dashboard for a given run. When executed through the UI a run name based on Date and Time is generated automatically. When using the CLI features, this can be specified in free text form for filtering purposes:

Specifying a run name is shown below:

curl -d '{"apiUrl": "https://app.scriptworks.io/api", "projectId": 2, "tags":["Register"], "runSettingIds":[1],"runName":"Build1.2.3","username":"myuser","password":"mypass"}' -H "Content-Type: application/json" -X POST 'http://127.0.0.1:8081/ci/runTests/'

Specifying Concurrent Execution

By default tests are run in sequence. To specify Asynchronous (concurrent) execution specify the parameter as shown:

curl -d '{"apiUrl": "https://app.scriptworks.io/api", "isAsync": true, "projectId": 2, "tags":["Register"], "runSettingIds":[1],"runName":"Build1.2.3","username":"myuser","password":"mypass"}' -H "Content-Type: application/json" -X POST 'http://127.0.0.1:8081/ci/runTests/'

Providing Output in JUnit Format

To provide output in Json or JUnit Format and save this as a file, the combination of outputFormat and the -o parameter to curl can be used:

curl -d '{"apiUrl": "https://app.scriptworks.io/api", "isAsync": true, "projectId": 2, "tags":["Register"], "runSettingIds":[1],"username":"myuser","password":"mypass", "outputFormat": "JUnit"}' -H "Content-Type: application/json" -X POST 'http://127.0.0.1:8081/ci/runTests/' -o Results.xml

This will save the result of the tests in the run in the Results.xml file. This can be picked up by Build Orchestration and CI tools like Jenkins for indicators of Build Health.