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.
