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>"
],
"test_case_ids": [
"<string>"
],
"branch": "<string>",
"concurrency": {
"group": "<string>"
},
"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>"],
"test_case_ids": ["<string>"],
"branch": "<string>",
"concurrency": { "group": "<string>" },
"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>'],
test_case_ids: ['<string>'],
branch: '<string>',
concurrency: {group: '<string>'},
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>'
],
'test_case_ids' => [
'<string>'
],
'branch' => '<string>',
'concurrency' => [
'group' => '<string>'
],
'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 \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"concurrency\": {\n \"group\": \"<string>\"\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 \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"concurrency\": {\n \"group\": \"<string>\"\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 \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"concurrency\": {\n \"group\": \"<string>\"\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": "resolved",
"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>"
}
}Test Runs
Trigger a test run
Triggers a new end-to-end test run for the scoped project against the given 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>"
],
"test_case_ids": [
"<string>"
],
"branch": "<string>",
"concurrency": {
"group": "<string>"
},
"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>"],
"test_case_ids": ["<string>"],
"branch": "<string>",
"concurrency": { "group": "<string>" },
"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>'],
test_case_ids: ['<string>'],
branch: '<string>',
concurrency: {group: '<string>'},
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>'
],
'test_case_ids' => [
'<string>'
],
'branch' => '<string>',
'concurrency' => [
'group' => '<string>'
],
'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 \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"concurrency\": {\n \"group\": \"<string>\"\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 \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"concurrency\": {\n \"group\": \"<string>\"\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 \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"concurrency\": {\n \"group\": \"<string>\"\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": "resolved",
"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
The environment slug to run tests against (e.g., production, staging).
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.
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
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?