Skip to content

Data Sources Commands

The opentf-ctl tool provides a command to manage data sources. You can query for data sources of a workflow: test cases, execution environment tags, or workflow jobs.

get datasource {workflow_id} --kind {kind}

This command queries for the specified workflow data sources.

opentf-ctl get datasource a13f0572-b23b-40bc-a6eb-a12429f0143c --kind=testcases
opentf-ctl get datasource a13 -k testcases
NAME                                         TECHNOLOGY      OUTCOME   EXECUTION TIME
Successful Test 1#Sample Successful Test 1   cypress         SUCCESS  44
Successful Test 2#Sample Successful Test 2   cypress         SUCCESS  18
Failing Test 1#Sample Failing Test 1         cypress         FAILURE  1
Failing Test 2#Sample Failing Test 2         cypress         FAILURE  1

You can specify a partial workflow ID, as long as it is unique (if it is not, a message is displayed listing the available workflows).

The --kind (or -k) parameter is mandatory. It defines the data source to query. Currently, three kinds are available: testcases, jobs, and tags.

The testcases data source

The get datasource {workflow_id} --kind testcases command default output for the testcases data source contains the test cases list, displaying, for each test case, its name, technology, outcome, and execution time.

It is also possible to display, in addition, execution environment (or runs-on) tags and job name using --output=wide option. If you want to display the complete data source, use --output=json|yaml option.

The jobs data source

The get datasource {workflow_id} --kind jobs command default output for the jobs data source contains the job list, displaying, for each job, its name, successful, failed and total test cases count.

opentf-ctl get datasource a13 -k jobs
NAME                               SUCCESS  FAILURE  TOTAL
cucumber-execute-test              3        2        5
cypress-junit-execute-test         3        6        9
postman-robot-soapui-execute-test  10       3        13

It is also possible to display, in addition, counts for tests in error and skipped tests, and execution environment (or runs-on) tags using --output=wide option. If you want to display the complete data source, use --output=json|yaml option.

The tags data source

The get datasource {workflow_id} --kind tags command default output for the tags data source contains the execution environment tags list, displaying, for each tag, its name, successful, failed and total test cases count.

opentf-ctl get datasource a13 -k tags
NAME            SUCCESS  FAILURE  TOTAL
linux           16       11       27
cucumber        3        2        5
cypress         3        6        9
junit           3        6        9
postman         10       3        13

It is also possible to display, in addition, counts for tests in error and skipped tests using --output=wide option. If you want to display the complete data source, use --output=json|yaml option.

Optional parameters

The get datasource {workflow_id} command allows for additional optional parameters, in no specific order, but they must follow the command if used:

--output=wide or -o wide                          # show additional information
--output=custom-columns= or -o custom-columns=    # show specified information
--output=json or -o json                          # show information in JSON format
--output=yaml or -o yaml                          # show information in YAML format
--field-selector={selector}                       # filter query on field selector
--timeout={x}                                     # set query timeout in seconds

Custom view

If this optional parameter is specified, you can choose what is displayed for each known execution environment.

The columns definition format is as follows: name:value[,name:value]*. name is the column name in the output (OUTCOME or DETAILS in the example above). value is the path to the information in the data source schema.

The following values are supported:

1) Shared paths:

  • .metadata.name
  • .metadata.namespace
  • .metadata.workflow_id

2) testcases:

  • .metadata.id
  • .metadata.job_id
  • .metadata.execution_id
  • .metadata.creationTimestamp
  • .test.runs-on
  • .test.uses
  • .test.technology
  • .test.managed
  • .test.job
  • .test.test
  • .test.suiteName
  • .test.testCaseName
  • .test.outcome
  • .execution.startTime
  • .execution.endTime
  • .execution.duration
  • .execution.errorsList
  • .execution.(failure|warning|error)Details
  • .execution.(failure|warning|error)Details.(message|type|text)

failureDetails, errorDetails, and warningDetails paths are specific to the failed test cases. errorsList path is available for Robot Framework executions only, in case there are general execution errors.

3) jobs:

  • .metadata.id
  • .metadata.creationTimestamp
  • .spec.runs-on
  • .spec.variables
  • .status.phase
  • .status.requestTime
  • .status.startTime
  • .status.endTime
  • .status.duration
  • .status.testCaseCount
  • .status.testCaseCountStatusSummary.(success|failure|error|skipped|cancelled)

4) tags:

  • .status.jobCount
  • .status.testCaseCount
  • .status.testCaseCountStatusSummary.(success|failure|error|skipped|cancelled)

The following command will output three columns with test case name, outcome and details on failure type if relevant:

opentf-ctl get datasource a13 -k testcases -o \
   custom-columns=NAME:.metadata.name,OUTCOME:.test.outcome,DETAILS:.execution.failureDetails.type
NAME                                               OUTCOME  DETAILS
Successful Test 1#Sample Successful Test 1         SUCCESS  <none>
Successful Test 2#Sample Successful Test 2         SUCCESS  <none>
Successful Test 3#Sample Successful Test 3         SUCCESS  <none>
Failing Test 1#Sample Failing Test 1               FAILURE  AssertionError
Failing Test 2#Sample Failing Test 2               FAILURE  AssertionError
Failing Test 3#Sample Failing Test 3               FAILURE  AssertionError

Using field selectors

By default the get datasource {workflow_id} command lists all data source items.

The command output may be restricted by using the --field-selector option. For example, you may restrict command output to show only failed test cases.

opentf-ctl get datasource a13 --kind testcases --field-selector=test.outcome==failure
NAME                                      TECHNOLOGY  OUTCOME  EXECUTION TIME
Failing Test 1#Sample Failing Test 1      cypress     FAILURE  1
Failing Test 2#Sample Failing Test 2      cypress     FAILURE  1
Failing Test 3#Sample Failing Test 3      cypress     FAILURE  1

You can combine selectors with output format.

For more information on selectors, see “selectors.”

Timeout

All data sources are cached. For large workflows containing thousands of test cases, cache creation may take some time, so your request may time out. Default request timeout is 8 seconds: if you need to raise it, you can use the --timeout= option to set your own timeout in seconds.

opentf-ctl get datasource a13 --kind testcases --timeout 300

Info

When the --field-selector option is used, a new data source cache is created for each field selector. It may influence request times.