Create a manual test run

The following flow demonstrates how to use the REST API to run a manual test.

Entity relationship diagram

We need to access the following entities for this flow, and understand the relationships between these entities.

Entity relationship diagram for Tests, Runs, Releases, and List Node entities.

The following shows the relations in the flow.

Entity	Relationships in this flow	Description of relationship	Reference / relationship fields
Tests	Manual Tests, Gherkin Tests, and Test Suites	This aggregate resource collection represents types of tests, including manual tests, Gherkin tests, automated tests, and test suites.	subtype
Manual Tests	Tests	The manual test is a subtype of the tests aggregate resource collection. The manual test can also be accessed in the manual_tests resource collection. There is no field that relates back to the aggregate resource collection, tests.	None
Manual Tests	Steps	Manual test steps are stored in the internal repository. Steps are accessed as a script resource under the corresponding test in the tests resource collection.	`tests\<test_ID>\script`
Runs	Manual Test Runs and Test Suite Runs	This aggregate resource collection represents types of test runs, including manual runsand test suite runs.	subtype
Manual Runs	Runs	The manual test run is a subtype of the runs aggregate resource collection. The manual test run can also be accessed in the manual_runs resource collection. There is no field that relates back to the aggregate resource collection, runs.	None
Manual Runs	Steps	Manual run steps are created when you execute the manual run. If a manual run is only planned, the run steps are not created until the test is executed. Note: This behavior is controlled by the CREATE_STEPS_DURING_RUN_CREATION configuration parameter. For more details, see Configuration parameters. To generate the steps of a planned run without executing the run, you can run a PUT request to the runs custom resource: PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/runs/{run_id}/steps	None
Manual Runs	Manual Tests	Manual test runs are associated with their respective tests.	test
Releases	Manual Runs	Runs can be associated with releases.	release
List Nodes	Manual Runs	Run statuses are in the list_node resource collection.	native_status

Flow

Let's create the REST API call for creating a manual test run step-by-step.

Create a manual test

Generally, we create manual tests with their phase set to New. So first let's check the phases entity to see which ID corresponds to the New phase for manual tests.

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/phases?query="logical_name EQ 'phase.test_manual.new'"

This GET operation returns phase.test_manual.new as the phase ID:

{
  "total_count": 1,
  "data": [
    {
      "type": "phase",
      "creation_time": "2017-04-02T19:06:49Z",
      "is_system": true,
      "logical_name": "phase.test_manual.new",
      "version_stamp": 1,
      "is_start_phase": true,
      "description": null,
      "name": "New",
      "id": "phase.test_manual.new",
      "metaphase": {
        "type": "metaphase",
        "id": "1005"
      },
      "last_modified": "2017-04-02T19:06:49Z",
      "entity": "test_manual"
    }
  ],
  "exceeds_total_count": false
}

We now POST a manual test whose name is MyManualTest with the New phase.

POST .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/manual_tests

Payload

     {"data":[

         "phase":{

                    "id": phase.test_manual.new,

                    "type":"phase"

},

         "name":"MyManualTest"

       }    ]

In response, the manual test is created with ID 1079.

{
  "total_count": 1,
  "data": [
    {
      "type": "test_manual",
      "id": "1079"
    }
  ],
  "exceeds_total_count": false
}

We now update the newly-created MyManualTest (with ID 1079) by adding test steps to it using the PUT operation.

Our manual test has three steps plus one validation step.

Scripts are added using the tests resource collection, and not the manual_tests resource collection.

Test scripts support versioning. So when we update the test with its steps, we can specify a comment and a revision type for this version of test steps. In this flow, the version has blank comment, and its revision type is considered minor. Revision types can be either Major or Minor.

PUT /api/shared_spaces/<space_id>/workspaces/<workspace_id>/tests/1079/script

Payload
```
{  "script":"- Enter user name. \n - Enter password. \n - Press <ENTER>.\n - ? Was login successful? ",
```
```
   "comment":"These are the steps I am adding.",
```
```
   "revision_type":"Minor" 
```
```
}
```
The steps are added to the manual test.

Run the manual test

We now POST a manual test run called MyManualRun. To create the run, we must supply:

The name and ID of the test we are "running."
The native status we want to assign to the run. Statuses are accessed in the list_node resource collection. In this flow, we will assign status 1091, which corresponds to list_node.run_native_status.failed.
The release associated with the run.

Payload

POST /api/shared_spaces/<space_id>/workspaces/<workspace_id>/manual_runs

{  "data":[
   { 
      "test":{"id":1065,"type":"test_manual"},
      "native_status":{"id":"list_node.run_native_status.passed","type":"list_node"},
      "name":"MyManualRun",
      "release":{"id":1001,"type":"release"}
    }
  ]
}

The test run is created with ID 1195.

{
  "total_count": 1,
  "data": [
    {
      "type": "run_manual",
      "id": "1195"
    }
  ],
  "exceeds_total_count": false
}