Test Runs
Trigger a test run
Triggers a new end-to-end test run for the scoped project, optionally with a saved environment, resolving the branch/build and dispatching the run.
PUT
/
api
/
test-runs
Trigger a test run
curl --request PUT \
--url https://api.empirical.run/api/test-runs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"environment": "<string>",
"build": {
"branch": "<string>",
"commit": "<string>",
"repo": "<string>"
},
"metadata": {},
"environment_variables_overrides": [
{
"name": "<string>",
"value": "<string>"
}
],
"tags": [
"<string>"
],
"exclude_tags": [
"<string>"
],
"test_case_ids": [
"<string>"
],
"branch": "<string>",
"concurrency": {
"group": "<string>"
},
"reporters": [
{
"reporter_type": "slack_run_status",
"slack_channels": [
"<string>"
],
"slack_channel_ids": [
2
]
}
],
"rerun_source_id": 2,
"rerun_only_failed": true
}
'import requests
url = "https://api.empirical.run/api/test-runs"
payload = {
"environment": "<string>",
"build": {
"branch": "<string>",
"commit": "<string>",
"repo": "<string>"
},
"metadata": {},
"environment_variables_overrides": [
{
"name": "<string>",
"value": "<string>"
}
],
"tags": ["<string>"],
"exclude_tags": ["<string>"],
"test_case_ids": ["<string>"],
"branch": "<string>",
"concurrency": { "group": "<string>" },
"reporters": [
{
"reporter_type": "slack_run_status",
"slack_channels": ["<string>"],
"slack_channel_ids": [2]
}
],
"rerun_source_id": 2,
"rerun_only_failed": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
environment: '<string>',
build: {branch: '<string>', commit: '<string>', repo: '<string>'},
metadata: {},
environment_variables_overrides: [{name: '<string>', value: '<string>'}],
tags: ['<string>'],
exclude_tags: ['<string>'],
test_case_ids: ['<string>'],
branch: '<string>',
concurrency: {group: '<string>'},
reporters: [
{
reporter_type: 'slack_run_status',
slack_channels: ['<string>'],
slack_channel_ids: [2]
}
],
rerun_source_id: 2,
rerun_only_failed: true
})
};
fetch('https://api.empirical.run/api/test-runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.empirical.run/api/test-runs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'environment' => '<string>',
'build' => [
'branch' => '<string>',
'commit' => '<string>',
'repo' => '<string>'
],
'metadata' => [
],
'environment_variables_overrides' => [
[
'name' => '<string>',
'value' => '<string>'
]
],
'tags' => [
'<string>'
],
'exclude_tags' => [
'<string>'
],
'test_case_ids' => [
'<string>'
],
'branch' => '<string>',
'concurrency' => [
'group' => '<string>'
],
'reporters' => [
[
'reporter_type' => 'slack_run_status',
'slack_channels' => [
'<string>'
],
'slack_channel_ids' => [
2
]
]
],
'rerun_source_id' => 2,
'rerun_only_failed' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.empirical.run/api/test-runs"
payload := strings.NewReader("{\n \"environment\": \"<string>\",\n \"build\": {\n \"branch\": \"<string>\",\n \"commit\": \"<string>\",\n \"repo\": \"<string>\"\n },\n \"metadata\": {},\n \"environment_variables_overrides\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"exclude_tags\": [\n \"<string>\"\n ],\n \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"concurrency\": {\n \"group\": \"<string>\"\n },\n \"reporters\": [\n {\n \"reporter_type\": \"slack_run_status\",\n \"slack_channels\": [\n \"<string>\"\n ],\n \"slack_channel_ids\": [\n 2\n ]\n }\n ],\n \"rerun_source_id\": 2,\n \"rerun_only_failed\": true\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.empirical.run/api/test-runs")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"environment\": \"<string>\",\n \"build\": {\n \"branch\": \"<string>\",\n \"commit\": \"<string>\",\n \"repo\": \"<string>\"\n },\n \"metadata\": {},\n \"environment_variables_overrides\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"exclude_tags\": [\n \"<string>\"\n ],\n \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"concurrency\": {\n \"group\": \"<string>\"\n },\n \"reporters\": [\n {\n \"reporter_type\": \"slack_run_status\",\n \"slack_channels\": [\n \"<string>\"\n ],\n \"slack_channel_ids\": [\n 2\n ]\n }\n ],\n \"rerun_source_id\": 2,\n \"rerun_only_failed\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.empirical.run/api/test-runs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"environment\": \"<string>\",\n \"build\": {\n \"branch\": \"<string>\",\n \"commit\": \"<string>\",\n \"repo\": \"<string>\"\n },\n \"metadata\": {},\n \"environment_variables_overrides\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"exclude_tags\": [\n \"<string>\"\n ],\n \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"concurrency\": {\n \"group\": \"<string>\"\n },\n \"reporters\": [\n {\n \"reporter_type\": \"slack_run_status\",\n \"slack_channels\": [\n \"<string>\"\n ],\n \"slack_channel_ids\": [\n 2\n ]\n }\n ],\n \"rerun_source_id\": 2,\n \"rerun_only_failed\": true\n}"
response = http.request(request)
puts response.read_body{
"data": {
"trigger": {
"success": true
},
"test_run": {
"id": 123,
"state": "<string>",
"error_code": "<string>",
"test_run_branch": "<string>",
"created_at": "<string>",
"concurrency": {
"group": "<string>",
"on_conflict": "cancel"
},
"test_code": {
"requested": {
"branch": "<string>",
"source": "explicit",
"if_missing": "error"
},
"resolved": {
"branch": "<string>",
"sha": "<string>",
"fallback_reason": "requested_branch_missing"
},
"execution": {
"ref": "<string>",
"sha": "<string>",
"ref_kind": "branch"
},
"merge_base": {
"branch": "<string>",
"sha": "<string>"
},
"resolution_status": "pending",
"resolution_error_code": "<string>"
},
"trigger": {
"event": "pull_request",
"pull_request": {
"head": "<string>",
"base": "<string>",
"number": 2
}
}
}
}
}{
"data": "<unknown>",
"error": {
"message": "<string>"
}
}{
"data": "<unknown>",
"error": {
"message": "<string>"
}
}{
"data": "<unknown>",
"error": {
"message": "<string>"
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Slug of a saved environment to run with (e.g., production, staging). Optional: without it the run uses only the project's variables and the config sent on this request.
Build information to associate with the test run.
Show child attributes
Show child attributes
Custom key-value pairs to associate with the test run. Values must be strings or numbers.
Show child attributes
Show child attributes
Environment variables to override for this test run.
Show child attributes
Show child attributes
Tags to filter which tests to run (e.g., @smoke, @critical). Only tests matching these tags will be executed.
Tags whose tests are skipped (e.g., @slow). Applied after every other selection, so it can only remove tests: with tags it runs tests matching tags but not exclude_tags; alone it runs every test except the excluded ones.
Specific test case ids (Playwright per-project test.id) to run. Only these tests will be executed.
Existing test-repository branch to run. A missing explicit branch creates an errored run; Empirical never creates it. May be supplied alongside build, which describes the application code under test.
The application pull request under test, for pre-merge runs. The run uses the test-repository branch named pull_request.head, merged into the project default branch. If no such branch exists, it uses the default branch. An explicit branch takes precedence.
Show child attributes
Show child attributes
Concurrency group and policy for this run. Runs in the same group (within the project) are limited to one in progress; on_conflict says what this run does when the group already has an active run: cancel cancels it and starts now, wait queues behind it (a newer waiting run replaces an older one). Omit to use the project's legacy concurrency setting; null for no limit.
Show child attributes
Show child attributes
Reporters for this run, saved on the run when it is created; at most one entry per reporter_type. Omit to use the environment's reporter_config (a run without an environment then gets none). A list replaces those defaults: reporters not listed do not fire, and [] turns them all off. Without reporters, a run started by a person (dashboard, CLI or agent session) also gets slack_creator_dm; a list sends the DM only if it names slack_creator_dm. Invalid entries (unknown Slack channels, duplicate types) reject the request without creating a run.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
Show child attributes
Show child attributes
ID of the test run this run is a rerun of.
Required range:
x >= 1When rerunning, only re-execute the previously failed tests.
Response
The triggered test run.
Show child attributes
Show child attributes
Was this page helpful?
Trigger a test run
curl --request PUT \
--url https://api.empirical.run/api/test-runs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"environment": "<string>",
"build": {
"branch": "<string>",
"commit": "<string>",
"repo": "<string>"
},
"metadata": {},
"environment_variables_overrides": [
{
"name": "<string>",
"value": "<string>"
}
],
"tags": [
"<string>"
],
"exclude_tags": [
"<string>"
],
"test_case_ids": [
"<string>"
],
"branch": "<string>",
"concurrency": {
"group": "<string>"
},
"reporters": [
{
"reporter_type": "slack_run_status",
"slack_channels": [
"<string>"
],
"slack_channel_ids": [
2
]
}
],
"rerun_source_id": 2,
"rerun_only_failed": true
}
'import requests
url = "https://api.empirical.run/api/test-runs"
payload = {
"environment": "<string>",
"build": {
"branch": "<string>",
"commit": "<string>",
"repo": "<string>"
},
"metadata": {},
"environment_variables_overrides": [
{
"name": "<string>",
"value": "<string>"
}
],
"tags": ["<string>"],
"exclude_tags": ["<string>"],
"test_case_ids": ["<string>"],
"branch": "<string>",
"concurrency": { "group": "<string>" },
"reporters": [
{
"reporter_type": "slack_run_status",
"slack_channels": ["<string>"],
"slack_channel_ids": [2]
}
],
"rerun_source_id": 2,
"rerun_only_failed": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
environment: '<string>',
build: {branch: '<string>', commit: '<string>', repo: '<string>'},
metadata: {},
environment_variables_overrides: [{name: '<string>', value: '<string>'}],
tags: ['<string>'],
exclude_tags: ['<string>'],
test_case_ids: ['<string>'],
branch: '<string>',
concurrency: {group: '<string>'},
reporters: [
{
reporter_type: 'slack_run_status',
slack_channels: ['<string>'],
slack_channel_ids: [2]
}
],
rerun_source_id: 2,
rerun_only_failed: true
})
};
fetch('https://api.empirical.run/api/test-runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.empirical.run/api/test-runs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'environment' => '<string>',
'build' => [
'branch' => '<string>',
'commit' => '<string>',
'repo' => '<string>'
],
'metadata' => [
],
'environment_variables_overrides' => [
[
'name' => '<string>',
'value' => '<string>'
]
],
'tags' => [
'<string>'
],
'exclude_tags' => [
'<string>'
],
'test_case_ids' => [
'<string>'
],
'branch' => '<string>',
'concurrency' => [
'group' => '<string>'
],
'reporters' => [
[
'reporter_type' => 'slack_run_status',
'slack_channels' => [
'<string>'
],
'slack_channel_ids' => [
2
]
]
],
'rerun_source_id' => 2,
'rerun_only_failed' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.empirical.run/api/test-runs"
payload := strings.NewReader("{\n \"environment\": \"<string>\",\n \"build\": {\n \"branch\": \"<string>\",\n \"commit\": \"<string>\",\n \"repo\": \"<string>\"\n },\n \"metadata\": {},\n \"environment_variables_overrides\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"exclude_tags\": [\n \"<string>\"\n ],\n \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"concurrency\": {\n \"group\": \"<string>\"\n },\n \"reporters\": [\n {\n \"reporter_type\": \"slack_run_status\",\n \"slack_channels\": [\n \"<string>\"\n ],\n \"slack_channel_ids\": [\n 2\n ]\n }\n ],\n \"rerun_source_id\": 2,\n \"rerun_only_failed\": true\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.empirical.run/api/test-runs")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"environment\": \"<string>\",\n \"build\": {\n \"branch\": \"<string>\",\n \"commit\": \"<string>\",\n \"repo\": \"<string>\"\n },\n \"metadata\": {},\n \"environment_variables_overrides\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"exclude_tags\": [\n \"<string>\"\n ],\n \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"concurrency\": {\n \"group\": \"<string>\"\n },\n \"reporters\": [\n {\n \"reporter_type\": \"slack_run_status\",\n \"slack_channels\": [\n \"<string>\"\n ],\n \"slack_channel_ids\": [\n 2\n ]\n }\n ],\n \"rerun_source_id\": 2,\n \"rerun_only_failed\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.empirical.run/api/test-runs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"environment\": \"<string>\",\n \"build\": {\n \"branch\": \"<string>\",\n \"commit\": \"<string>\",\n \"repo\": \"<string>\"\n },\n \"metadata\": {},\n \"environment_variables_overrides\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"exclude_tags\": [\n \"<string>\"\n ],\n \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"concurrency\": {\n \"group\": \"<string>\"\n },\n \"reporters\": [\n {\n \"reporter_type\": \"slack_run_status\",\n \"slack_channels\": [\n \"<string>\"\n ],\n \"slack_channel_ids\": [\n 2\n ]\n }\n ],\n \"rerun_source_id\": 2,\n \"rerun_only_failed\": true\n}"
response = http.request(request)
puts response.read_body{
"data": {
"trigger": {
"success": true
},
"test_run": {
"id": 123,
"state": "<string>",
"error_code": "<string>",
"test_run_branch": "<string>",
"created_at": "<string>",
"concurrency": {
"group": "<string>",
"on_conflict": "cancel"
},
"test_code": {
"requested": {
"branch": "<string>",
"source": "explicit",
"if_missing": "error"
},
"resolved": {
"branch": "<string>",
"sha": "<string>",
"fallback_reason": "requested_branch_missing"
},
"execution": {
"ref": "<string>",
"sha": "<string>",
"ref_kind": "branch"
},
"merge_base": {
"branch": "<string>",
"sha": "<string>"
},
"resolution_status": "pending",
"resolution_error_code": "<string>"
},
"trigger": {
"event": "pull_request",
"pull_request": {
"head": "<string>",
"base": "<string>",
"number": 2
}
}
}
}
}{
"data": "<unknown>",
"error": {
"message": "<string>"
}
}{
"data": "<unknown>",
"error": {
"message": "<string>"
}
}{
"data": "<unknown>",
"error": {
"message": "<string>"
}
}