Create a test suite with manual and Gherkin tests

The following example shows how to use the REST API to create a test suite with manual and Gherkin tests.

Entity relationship diagram

You need to access the following entities for this example. The diagram illustrates the relationships between these entities.

Entity relationship diagram with Tests and Tests in Suite entities.

The following table shows the relations in the example.

Entity	Relationships in this example	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`
Gherkin Tests	Tests	The Gherkin test is a subtype of the tests aggregate resource collection. The Gherkin test can also be accessed in the gherkin_tests resource collection. There is no field that relates back to the aggregate resource collection, tests.	None
Gherkin Tests	Scripts	Gherkin test scripts are stored in the internal repository. Scripts are accessed as a script resource under the corresponding test in the tests resource collection.	`tests\<test_ID>\script`
Tests in Suite	Test Suites	The test_suite_link_to_tests resource collection manages the associations between a test suite, and all of its manual and Gherkin tests. Its only purposes is to link the entities.	test_suite
Tests in Suite	Gherkin Tests	The test_suite_link_to_tests resource collection manages the associations between a test suite, and all of its manual and Gherkin tests. Its only purposes is to link the entities.	test
Tests in Suite	Manual Tests	The test_suite_link_to_tests resource collection manages the associations between a test suite, and all of its manual and Gherkin tests. Its only purposes is to link the entities.	test

Step 1: Create a manual test

Create a manual test and its steps using the REST API.

To create a manual test:

Generally, manual tests are created with their phase set to New. Using the GET operation, 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
}

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
}

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

This 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. When you update the test with its steps, you can specify a comment and a revision type for this version of test steps. Revision types can be Major or Minor.

In this example, the version has blank comment, and its revision type is considered minor. Revision types can be 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":"Testing login procedure.",
```
```
    "revision_type":"Minor" 
```
```
}
```
The steps are added to the manual test.

Step 2: Create a Gherkin test

Create a Gherkin test and its script using the REST API.

To create a Gherkin test:

Generally, Gherkin tests are created with their mandatory phase set to New. Using the GET operation, check the phases entity to see which ID corresponds to the New phase for Gherkin tests.

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

This GET operation returns 1014 as the phase ID:

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

POST a Gherkin test whose name is MyGherkinTest.

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

Payload

     {"data":[

         "phase":{

                    "id": 1014,

                    "type":"phase"

},

         "name":"MyGherkinTest"

       }    ]

In response, the Gherkin test is created with ID 1074.

{
  "total_count": 1,
  "data": [
    {
      "type": "gherkin_test",
      "id": "1074"
    }
  ],
  "exceeds_total_count": false
}

Update the newly-created MyGherkinTest (with ID 1074) by adding a script to it using the PUT operation.

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

ThisGherkin test has one feature and one scenario.

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

PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/tests/1074/script

Payload:
```
{
            "script": "Feature: Buying items in shopping cart, single user\n \n\tBackground: \n\t\tGiven payment security system is up\n \n\tScenario: Julio buys items in his cart\n\t\tGiven a customer named \"Julio Brown\" \n\t\tGiven I am logged in as Julio \n\t\tGiven I have at least one item in cart\n\t\tWhen I try to buy items in my cart\n\t\tThen I should be asked for my payment method",
            
```
```
            "comment": "Testing shopping cart functionality.",
            "revision_type": "Minor"
}
```
The script is added to the Gherkin test.

Back to top

Step 3: Add the tests to a test suite

Create a test suite and add the two tests to the suite, using the REST API.

To add the tests to a test suite:

Create an empty test suite called MyTestSuite using the test_suites resource collection with the POST operation.

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

Payload:
```
{"data":[
```
```
 { "name":"MyTestSuite" }
```
```
 ]
```
```
} 
```
The test suite is created with ID 1082.
```
{
  "total_count": 1,
  "data": [
    {
      "type": "test_suite",
      "id": "1082"
    }
  ],
  "exceeds_total_count": false
}
```
Add tests to the test suite.

Access a resource collection called test_suite_link_to_tests to link the existing manual test (1079) and Gherkin test (1074) using two POST operations.
1. Link the manual test:
  
  POST /api/shared_spaces/<space_id>/workspaces/<workspace_id>/test_suite_link_to_tests
  
  Payload:
```
{
 "data":[
   {
      "test_suite":{"type":"test","id":"1082"},
      "test":{"type":"test","id":"1079"}
   }
 ]
} 
```
2. Link the Gherkin test:
  
  POST /api/shared_spaces/<space_id>/workspaces/<workspace_id>/test_suite_link_to_tests
  
  Payload:
```
{
 "data":[
   {
      "test_suite":{"type":"test","id":"1082"},
      "test":{"type":"test","id":"1074"}
   }
 ]
}  
```

See the tests in the test suite.

Use a basic GET operation to list all the links between test suites and their tests in the workspace:

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/test_suite_link_to_tests

Build the query_clause to find the manual and Gherkin tests that are associated with a specific test suite.

Use the reference field test_suite to filter the test suites by ID. This lists any manual or Gherkin tests that are linked to the test suite whose ID is 1082.

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/test_suite_link_to_tests?query="test_suite EQ {id EQ 1082}"

Note the syntax for reference fields.

Standard request syntax	Syntax for reference fields
Equal sign (=)	EQ operator
Quotation marks (")	Carots (^)

The response shows the two tests that you added to the test suite:

{
  "total_count": 2,
  "data": [
    {
      "type": "test_suite_link_to_test",
      "creation_time": "2017-04-20T06:59:17Z",
      "test_suite": {
        "type": "test_suite",
        "id": "1082"
      },
      "test": {
        "type": "test_manual",
        "id": "1079"
      },
      "version_stamp": 1,
      "author": {
        "type": "workspace_user",
        "id": "1024"
      },
      "id": "1014",
      "last_modified": "2017-04-20T06:59:17Z"
    },
    {
      "type": "test_suite_link_to_test",
      "creation_time": "2017-04-20T07:04:31Z",
      "test_suite": {
        "type": "test_suite",
        "id": "1082"
      },
      "test": {
        "type": "gherkin_test",
        "id": "1074"
      },
      "version_stamp": 1,
      "author": {
        "type": "workspace_user",
        "id": "1024"
      },
      "id": "1015",
      "last_modified": "2017-04-20T07:04:31Z"
    }
  ],
  "exceeds_total_count": false
}