The automation/runs namespace provides API methods for automation runs and threads. You can use these methods to retrieve automation runs and threads for a project, create new runs and threads, submit test results (including custom fields, artifacts & links) and finally mark runs and threads as completed.
GET/projects/{project_id}/automation/runs
Returns all automation runs for a project.
This method uses so you might need to request additional pages to retrieve all automation runs.
Request
"page": {
"type": "integer",
"format": "int64",
"description": "Number of page (default: first page)."
},
"per_page": {
"type": "integer",
"format": "int64",
"enum": [
15,
25,
50,
100
],
"description": "Maximum number of items to return per page (default: 100)."
},
"sort": {
"type": "string",
"enum": [
"automation_runs:created_at"
],
"description": "Sort field for the list of automation runs."
},
"order": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order (ascending or descending)."
},
"config_id": {
"type": "string",
"description": "Comma-separated list of configurations to filter by."
},
"created_after": {
"type": "string",
"format": "date-time",
"description": "Limit result to automation runs created after (in ISO8601 format and UTC time zone)."
},
"created_before": {
"type": "string",
"format": "date-time",
"description": "Limit result to automation runs created before (in ISO8601 format and UTC time zone)."
},
"created_by": {
"type": "string",
"description": "Comma-separated list of users to filter by."
},
"milestone_id": {
"type": "string",
"description": "Comma-separated list of milestones to filter by."
},
"source_id": {
"type": "string",
"description": "Comma-separated list of automation sources to filter by."
},
"status": {
"type": "string",
"description": "Comma-separated list of statuses to filter by. Use: `2` for success, `3` for failure, `4` for running."
},
"tags": {
"type": "string",
"description": "Comma-separated list of tags to filter by."
},
"expands": {
"type": "string",
"description": "Comma-separated list of expands to return."
}
// Get latest 100 automation runs for project with ID 5
GET /api/v1/projects/5/automation/runs
// Get second result page (pagination)
GET /api/v1/projects/5/automation/runs?page=2
// Get latest 100 automation runs
GET /api/v1/projects/5/automation/runs
// Get latest 100 failed automation runs
GET /api/v1/projects/5/automation/runs?state=3
// Get latest automation runs created after a certain date & time
GET /api/v1/projects/5/automation/runs?created_after=2023-02-15T00:00:00.000Z
// Get automation runs and include expands
GET /api/v1/projects/5/automation/runs?expands=automation_sources,configs,users
Status codes
GET/automation/runs/{automation_run_id}
Returns a single automation run.
Request
"expands": {
"type": "string",
"description": "Comma-separated list of expands to return."
}
// Get the automation run with ID 5
GET /api/v1/automation/runs/5
// Get a automation run and include expands
GET /api/v1/automation/runs/1?expands=automation_sources,configs,users
Status codes
POST/projects/{project_id}/automation/runs
Creates a new automation run in a target project in preparation for adding threads and test results.
Request
"name": {
"type": "string",
"description": "Name of the new automation run."
},
"source": {
"type": "string",
"description": "Name of the source for the new automation run. If this source does not already exist in the target project, Testmo automatically creates a new one. It is recommended to keep source names short. Good examples are `backend`, `frontend` or `mobile-iphone`."
},
"config": {
"type": "string",
"description": "Name of the configuration for the new automation run."
},
"config_id": {
"type": "integer",
"format": "int64",
"description": "ID of the configuration for the new automation run. If both `config` and `config_id` are specified, `config_id` is given precedence."
},
"milestone": {
"type": "string",
"description": "Name of the milestone for the new automation run."
},
"milestone_id": {
"type": "integer",
"format": "int64",
"description": "ID of the milestone for the new automation run. If both `milestone` and `milestone_id` are specified, `milestone_id` is given precedence."
},
"tags": {
"type": "array",
"description": "List of tags for the new automation run. If a milestone in the same project has one or more matching automation tags, the new automation run is automatically linked to that milestone (unless `milestone` or `milestone_id` is also specified).",
"items": {
"type": "string"
}
},
"artifacts": {
"type": "array",
"description": "List of externally stored test artifacts to link to the new automation run (such as log files, screenshots or test data).",
"items": {
"type": "object",
"required": [
"name",
"url"
],
"properties": {
"name": {
"type": "string",
"description": "Name or file name of the test artifact."
},
"note": {
"type": "string",
"description": "Short note or summary of the test artifact with a maximum of 80 characters."
},
"url": {
"type": "string",
"description": "Link to an external resource to download the test artifact."
},
"mime_type": {
"type": "string",
"description": "MIME type of the test artifact (for example, `image/png`, `text/plain` or `application/octet-stream`)."
},
"size": {
"type": "integer",
"format": "int64",
"description": "File size of the test artifact in bytes."
}
}
}
},
"fields": {
"type": "array",
"description": "List of fields to attach to the new automation run (such as environment variables, errors or terminal output).",
"items": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "integer",
"format": "int8",
"enum": [
1,
2,
3,
4,
5
],
"description": "Type of the field. Use: `1` for regular strings, `2` for plain text, `3` for HTML text, `4` for text to display in a terminal/console frame (with a monospaced font), `5` for URLs."
},
"name": {
"type": "string",
"description": "Name of the field."
},
"value": {
"type": "string",
"description": "Value of the field (interpreted as defined by `type`)."
},
"meta": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Meta fields to attach to the field (to store extra information with a field)."
},
"is_highlight": {
"type": "boolean",
"description": "Defines if the field (or related meta fields) are highlighted in the user interface."
}
}
}
},
"links": {
"type": "array",
"description": "List of links to attach to the new automation run (such as a link back to the build in the CI tool that triggered the tests).",
"items": {
"type": "object",
"required": [
"name",
"url"
],
"properties": {
"name": {
"type": "string",
"description": "Name or file name of the link."
},
"note": {
"type": "string",
"description": "Short note or summary of the link with a maximum of 80 characters."
},
"url": {
"type": "string",
"description": "Link to an external resource or website."
}
}
}
}
Returns the ID of the created automation run on success:
201 Created
{
"id": 1
}
Status codes
POST/automation/runs/{automation_run_id}/append
Appends test artifacts, fields or links to an existing automation run.
Request
"artifacts": {
"type": "array",
"description": "List of externally stored test artifacts to link to the automation run (such as log files, screenshots or test data).",
"items": {
"type": "object",
"required": [
"name",
"url"
],
"properties": {
"name": {
"type": "string",
"description": "Name or file name of the test artifact."
},
"note": {
"type": "string",
"description": "Short note or summary of the test artifact with a maximum of 80 characters."
},
"url": {
"type": "string",
"description": "Link to an external resource to download the test artifact."
},
"mime_type": {
"type": "string",
"description": "MIME type of the test artifact (for example, `image/png`, `text/plain` or `application/octet-stream`)."
},
"size": {
"type": "integer",
"format": "int64",
"description": "File size of the test artifact in bytes."
}
}
}
},
"fields": {
"type": "array",
"description": "List of fields to attach to the automation run (such as environment variables, errors or terminal output).",
"items": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "integer",
"format": "int8",
"enum": [
1,
2,
3,
4,
5
],
"description": "Type of the field. Use: `1` for regular strings, `2` for plain text, `3` for HTML text, `4` for text to display in a terminal/console frame (with a monospaced font), `5` for URLs."
},
"name": {
"type": "string",
"description": "Name of the field."
},
"value": {
"type": "string",
"description": "Value of the field (interpreted as defined by `type`)."
},
"meta": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Meta fields to attach to the field (to store extra information with a field)."
},
"is_highlight": {
"type": "boolean",
"description": "Defines if the field (or related meta fields) are highlighted in the user interface."
}
}
}
},
"links": {
"type": "array",
"description": "List of links to attach to the automation run (such as a link back to the build in the CI tool that triggered the tests).",
"items": {
"type": "object",
"required": [
"name",
"url"
],
"properties": {
"name": {
"type": "string",
"description": "Name or file name of the link."
},
"note": {
"type": "string",
"description": "Short note or summary of the link with a maximum of 80 characters."
},
"url": {
"type": "string",
"description": "Link to an external resource or website."
}
}
}
}
Marks an automation run and its threads as completed and closes it for new threads and test results.
Request
"measure_elapsed": {
"type": "boolean",
"description": "Defines if the execution time of the automation run should automatically be set to the elapsed time between the creation and completion date of the run. This is useful in scenarios where the overall execution time of the run is independent from the execution times of its threads."
}
Example
POST /api/v1/automation/runs/1/complete
{
"measure_elapsed": true
}
204 No Content
Status codes
POST/automation/runs/{automation_run_id}/threads
Creates a new thread in an automation run in preparation for adding test results.
Request
"elapsed_observed": {
"type": "integer",
"format": "int64",
"description": "Observed overall elapsed (execution time) of the thread in microseconds."
},
"elapsed_computed": {
"type": "integer",
"format": "int64",
"description": "Computed overall elapsed (execution time) of the thread in microseconds. The _observed_ elapsed is usually derived from measuring the execution time of tests whereas the _computed_ elapsed is calculated from result log files."
},
"artifacts": {
"type": "array",
"description": "List of externally stored test artifacts to link to the new thread (such as log files, screenshots or test data).",
"items": {
"type": "object",
"required": [
"name",
"url"
],
"properties": {
"name": {
"type": "string",
"description": "Name or file name of the test artifact."
},
"note": {
"type": "string",
"description": "Short note or summary of the test artifact with a maximum of 80 characters."
},
"url": {
"type": "string",
"description": "Link to an external resource to download the test artifact."
},
"mime_type": {
"type": "string",
"description": "MIME type of the test artifact (for example, `image/png`, `text/plain` or `application/octet-stream`)."
},
"size": {
"type": "integer",
"format": "int64",
"description": "File size of the test artifact in bytes."
}
}
}
},
"fields": {
"type": "array",
"description": "List of fields to attach to the new thread (such as environment variables, errors or terminal output).",
"items": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "integer",
"format": "int8",
"enum": [
1,
2,
3,
4,
5
],
"description": "Type of the field. Use: `1` for regular strings, `2` for plain text, `3` for HTML text, `4` for text to display in a terminal/console frame (with a monospaced font), `5` for URLs."
},
"name": {
"type": "string",
"description": "Name of the field."
},
"value": {
"type": "string",
"description": "Value of the field (interpreted as defined by `type`)."
},
"meta": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Meta fields to attach to the field (to store extra information with a field)."
},
"is_highlight": {
"type": "boolean",
"description": "Defines if the field (or related meta fields) are highlighted in the user interface."
}
}
}
}
Appends test artifacts, fields or test results to an existing thread in an automation run.
Request
"elapsed_observed": {
"type": "integer",
"format": "int64",
"description": "Partial observed elapsed (execution time) in microseconds to add to the overall observed time of the thread."
},
"elapsed_computed": {
"type": "integer",
"format": "int64",
"description": "Partial computed elapsed (execution time) in microseconds to add to the overall computed time of the thread. The _observed_ elapsed is usually derived from measuring the execution time of tests whereas the _computed_ elapsed is calculated from result log files."
},
"artifacts": {
"type": "array",
"description": "List of externally stored test artifacts to link to the thread (such as log files, screenshots or test data).",
"items": {
"type": "object",
"required": [
"name",
"url"
],
"properties": {
"name": {
"type": "string",
"description": "Name or file name of the test artifact."
},
"note": {
"type": "string",
"description": "Short note or summary of the test artifact with a maximum of 80 characters."
},
"url": {
"type": "string",
"description": "Link to an external resource to download the test artifact."
},
"mime_type": {
"type": "string",
"description": "MIME type of the test artifact (for example, `image/png`, `text/plain` or `application/octet-stream`)."
},
"size": {
"type": "integer",
"format": "int64",
"description": "File size of the test artifact in bytes."
}
}
}
},
"fields": {
"type": "array",
"description": "List of fields to attach to the thread (such as environment variables, errors or terminal output).",
"items": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "integer",
"format": "int8",
"enum": [
1,
2,
3,
4,
5
],
"description": "Type of the field. Use: `1` for regular strings, `2` for plain text, `3` for HTML text, `4` for text to display in a terminal/console frame (with a monospaced font), `5` for URLs."
},
"name": {
"type": "string",
"description": "Name of the field."
},
"value": {
"type": "string",
"description": "Value of the field (interpreted as defined by `type`)."
},
"meta": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Meta fields to attach to the field (to store extra information with a field)."
},
"is_highlight": {
"type": "boolean",
"description": "Defines if the field (or related meta fields) are highlighted in the user interface."
}
}
}
},
"tests": {
"type": "array",
"description": "List of tests to add to the thread.",
"items": {
"type": "object",
"required": [
"key",
"name",
"status",
"folder"
],
"properties": {
"key": {
"type": "string",
"pattern": "^[a-z0-9_]{1,64}$",
"description": "Key used to identify tests across multiple automation runs (in the context of the same source). Limited to a maximum of 64 lowercase alphanumeric (a-z, 0-9) characters."
},
"name": {
"type": "string",
"description": "Name of the test."
},
"status": {
"type": "string",
"pattern": "^[a-z0-9_]+$",
"description": "Alias of the status for the result of the test (for example, `failed` or `passed`). The status aliases can be configured in Testmo's admin area."
},
"folder": {
"type": "string",
"description": "Fully qualified name of the target folder of the test. Folders can be used to group related tests and usually map to class or type names as defined in the test automation suite."
},
"elapsed": {
"type": "integer",
"format": "int64",
"description": "Overall execution time (observed or computed) of the test in microseconds."
},
"file": {
"type": "string",
"description": "Name of the file (with or without full path) the test is located in."
},
"line": {
"type": "integer",
"description": "Line number of the test in the given `file`."
},
"assertions": {
"type": "integer",
"description": "Number of assertions in the test."
},
"artifacts": {
"type": "array",
"description": "List of externally stored test artifacts to link to the test (such as log files, screenshots or test data).",
"items": {
"type": "object",
"required": [
"name",
"url"
],
"properties": {
"name": {
"type": "string",
"description": "Name or file name of the test artifact."
},
"note": {
"type": "string",
"description": "Short note or summary of the test artifact with a maximum of 80 characters."
},
"url": {
"type": "string",
"description": "Link to an external resource to download the test artifact."
},
"mime_type": {
"type": "string",
"description": "MIME type of the test artifact (for example, `image/png`, `text/plain` or `application/octet-stream`)."
},
"size": {
"type": "integer",
"format": "int64",
"description": "File size of the test artifact in bytes."
}
}
}
},
"fields": {
"type": "array",
"description": "List of fields to attach to the test (such as environment variables, errors or terminal output).",
"items": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "integer",
"format": "int8",
"enum": [
1,
2,
3,
4,
5
],
"description": "Type of the field. Use: `1` for regular strings, `2` for plain text, `3` for HTML text, `4` for text to display in a terminal/console frame (with a monospaced font), `5` for URLs."
},
"name": {
"type": "string",
"description": "Name of the field."
},
"value": {
"type": "string",
"description": "Value of the field (interpreted as defined by `type`)."
},
"meta": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Meta fields to attach to the field (to store extra information with a field)."
},
"is_highlight": {
"type": "boolean",
"description": "Defines if the field (or related meta fields) are highlighted in the user interface."
}
}
}
}
}
}
}
Marks an automation run thread as completed and closes it for new test results.
Request
"elapsed_observed": {
"type": "integer",
"format": "int64",
"description": "Observed overall elapsed (execution time) of the thread in microseconds."
},
"elapsed_computed": {
"type": "integer",
"format": "int64",
"description": "Computed overall elapsed (execution time) of the thread in microseconds. The _observed_ elapsed is usually derived from measuring the execution time of tests whereas the _computed_ elapsed is calculated from result log files."
}
Example
POST /api/v1/automation/runs/threads/1/complete
{
"elapsed_observed": 600000000
}
204 No Content
Status codes
project_ididrequired
ID of the project.
pageinteger
Number of page to return (default: first page)
per_pageinteger
Maximum number of automation runs to return (supported: 15, 25, 50, 100; default: 100)
sortstring
Sort field for the list of automation runs (supported: automation_runs:created_at; default: automation_runs:created_at)
orderstring
Sort order (ascending or descending) (supported: asc, desc; default: desc)
config_idstring
Comma-separated list of configurations to filter by.
created_afterstring
Limit result to automation runs created after (in ISO8601 format and UTC time zone).
created_beforestring
Limit result to automation runs created before (in ISO8601 format and UTC time zone).
created_bystring
Comma-separated list of users to filter by.
milestone_idstring
Comma-separated list of milestones to filter by.
source_idstring
Comma-separated list of automation sources to filter by.
statusstring
Comma-separated list of statuses to filter by. Use: 2 for success, 3 for failure, 4 for running.
tagsstring
Comma-separated list of tags to filter by.
expandsstring
Comma-separated list of expands to return.
This method supports the following so you can automatically include additional information for referenced objects:
200400401403422 ()
automation_run_ididrequired
ID of the automation run to return.
expandsstring
Comma-separated list of expands to return.
This method supports the following so you can automatically include additional information for referenced objects:
200400401403404422 ()
project_ididrequired
ID of the target project.
namestringrequired
Name of the new automation run.
sourcestringrequired
Name of the source for the new automation run. If this source does not already exist in the target project, Testmo automatically creates a new one. It is recommended to keep source names short. Good examples are backend, frontend or mobile-iphone.
configstring
Name of the configuration for the new automation run.
config_idid
ID of the configuration for the new automation run. If both config and config_id are specified, config_id is given precedence.
milestonestring
Name of the milestone for the new automation run.
milestone_idid
ID of the milestone for the new automation run. If both milestone and milestone_id are specified, milestone_id is given precedence.
tagsarray
List of tags for the new automation run. If a milestone in the same project has one or more matching automation tags, the new automation run is automatically linked to that milestone (unless milestone or milestone_id is also specified).
artifactsarray
List of externally stored test artifacts to link to the new automation run (such as log files, screenshots or test data). (see schema for details)
fieldsarray
List of fields to attach to the new automation run (such as environment variables, errors or terminal output). (see schema for details)
linksarray
List of links to attach to the new automation run (such as a link back to the build in the CI tool that triggered the tests). (see schema for details)
201400401403404422 ()
pathautomation_run_ididrequired
ID of the automation run.
artifactsarray
List of externally stored test artifacts to link to the automation run (such as log files, screenshots or test data). (see schema for details)
fieldsarray
List of fields to attach to the automation run (such as environment variables, errors or terminal output). (see schema for details)
linksarray
List of links to attach to the automation run (such as a link back to the build in the CI tool that triggered the tests). (see schema for details)
204400401403404422 ()
automation_run_ididrequired
ID of the automation run to complete.
measure_elapsedboolean Defines if the execution time of the automation run should automatically be set to the elapsed time between the creation and completion date of the run. This is useful in scenarios where the overall execution time of the run is independent from the execution times of its threads.
204400401403404422 ()
pathautomation_run_ididrequired
ID of the target automation run.
elapsed_observedinteger
Observed overall elapsed (execution time) of the thread in microseconds.
elapsed_computedinteger
Computed overall elapsed (execution time) of the thread in microseconds. The observed elapsed is usually derived from measuring the execution time of tests whereas the computed elapsed is calculated from result log files.
artifactsarray
List of externally stored test artifacts to link to the new thread (such as log files, screenshots or test data). (see schema for details)
fieldsarray
List of fields to attach to the new thread (such as environment variables, errors or terminal output). (see schema for details)
201400401403404422 ()
pathautomation_run_thread_ididrequired
ID of the automation run thread.
elapsed_observedinteger
Partial observed elapsed (execution time) in microseconds to add to the overall observed time of the thread.
elapsed_computedinteger
Partial computed elapsed (execution time) in microseconds to add to the overall computed time of the thread. The observed elapsed is usually derived from measuring the execution time of tests whereas the computed elapsed is calculated from result log files.
artifactsarray
List of externally stored test artifacts to link to the thread (such as log files, screenshots or test data). (see schema for details)
fieldsarray
List of fields to attach to the thread (such as environment variables, errors or terminal output). (see schema for details)
testsarray
List of tests to add to the thread. (see schema for details)
204400401403404422 ()
pathautomation_run_thread_ididrequired
ID of the automation run thread to complete.
elapsed_observedinteger
Observed overall elapsed (execution time) of the thread in microseconds.
elapsed_computedinteger
Computed overall elapsed (execution time) of the thread in microseconds. The observed elapsed is usually derived from measuring the execution time of tests whereas the computed elapsed is calculated from result log files.
