Get a list of planned runs for manual tests, Gherkin tests, and test suites

The following flow demonstrates how to get a list of planned runs for manual tests, Gherkin tests, and tests suites.

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 and Runs 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, Test Suites This aggregate resource collection represents types of tests, including manual, Gherkin, test suites, and automated. subtype
Tests Runs

Manual and Gherkin tests can be run.

Test suites can also be run. A suite run is a combination of other test runs.

Tip: run is not one of the fields returned by default when performing GET operations. To see the value of the run field from the tests entity, use the fields clause: 

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/tests?fields=run

run
Manual Tests, Gherkin Tests, Test Suites Tests

Manual tests, Gherkin tests, and test suites are subtypes of the tests aggregate resource collection.

  • The manual test can also be accessed in the manual_tests resource collection.

  • The Gherkin test can also be accessed in the gherkin_tests resource collection.

  • Test suites can also be accessed in the test_suites resource collection.

There is no field that relates back to the aggregate resource collection, tests.

 None
Runs Tests

This aggregate resource collection represents types of runs, including manual, Gherkin, and test suites.

Each run is associated with one test, or the tests in a test suite.

test
Manual Runs Runs

Manual runs (which include manual Gherkin test runs), and suite runs are subtypes of the runs aggregate resource collection.

Manual test runs, including manual Gherkin test runs, can also be accessed in the manual_runs resource collection.

There is no field that relates back to the aggregate resource collection, runs.

 None
Suite Runs Runs

Suite runs are subtypes of the runs aggregate resource collection.

Suite runs can also be accessed in the suite_run resource collection.

There is no field that relates back to the aggregate resource collection, runs.

 None
Suite Runs Manual runs Suite runs refer to the manual runs resource collection. runs_in_suite

Back to top

Flow

Let's create the REST API call step-by-step.

  1. We request all runs in the workspace using the runs reference field.

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

  2. Let's now start building our query_clause.

    This query has two sets of criteria: The test type, and the status. We separate each set with a semi-colon (;), which represents the And operator.

    In this step, we are only interested in the runs for manual tests and Gherkin tests that have the planned status. This is an example of using a list node, using the logical_name field to check for a match.

    GET ../api/shared_spaces/<space_id>/workspaces/<workspace_id>/runs?query="status EQ {logical_name EQ 'list_node.run_status.planned'}"

  3. We want to access only the planned runs that are manual (manual tests, Gherkin tests, and test suites). We use the || to indicate an OR condition.

    GET ../api/shared_spaces/<space_id>/workspaces/<workspace_id>/runs?query="status EQ {logical_name EQ 'list_node.run_status.planned'};test EQ {subtype EQ 'test_manual'||subtype EQ 'gherkin_test' || subtype EQ 'test_suite'}"

    Note: This query might produce duplicates. Both the planned suite runs, and the planned manual and Gherkin runs inside the suite runs are displayed.

The complete REST API call for this flow is: 

GET ../api/shared_spaces/<space_id>/workspaces/<workspace_id>/runs?query="status EQ {logical_name EQ 'list_node.run_status.planned'};test EQ {subtype EQ 'test_manual'||subtype EQ 'gherkin_test' || subtype EQ 'test_suite'}"

Back to top

Javascript example

/**
 * Flow: Get a list of *planned* manual, suite, manual Gherkin runs based on a certain filter (runs related to a specific release)
 * @param requestor
 */
function getPlannedManualTests(requestor) {
  requestor.get('/runs?query="status EQ {logical_name EQ ^list_node.run_status.planned^};' +
		'test EQ {subtype EQ ^test_manual^ || subtype EQ ^gherkin_test^ || subtype EQ ^test_suite^}"', function(error, message, runs) {
    console.info(runs);
  });
}

exports.getPlannedManualTests = getPlannedManualTests;

Back to top

See also: