Execute suites and retrieve results via CI/CD and other external systems.
List all suites in your account.
GET https://api.reflect.run/v1/suites
{
"suites": {
"data": [
{
"name": "Regression Tests",
"suiteId": "regression-tests",
"created": 1638416940
}
]
}
}
List recent executions for a given suite.
GET https://api.reflect.run/v1/suites/<suite-id>/executions
{
"suiteId": "regression-tests",
"executions": {
"data": [
{
"executionId": 47,
"url": "https://app.reflect.run/suites/regression-tests/executions/47",
"isFinished": false,
"status": "pending"
}
]
}
}
Triggers an execution of the specified suite.
The suite-id
value for your suite should match the ID value
displayed on the Suite Detail page, including casing.
(See Integrating via API.)
Reflect identifies certain properties of a scheduled execution as “reserved”. These reserved fields can be overridden with values provided by the API request:
hostnames
: Allows you to specify a replacement hostname value for a given target hostname.parameters
: Allows you to specify a URL parameter key/value pair that will be included (or overwritten) on the test’s initial URL.cookies
: Allows you to specify cookies that will be set when loading the test’s initial URL. A cookie consists of the following fields:
name
(required string): The name of the cookie to be set.value
(required string): The cookie’s value.domain
(optional string): Host to which the cookie will be sent. Defaults to the host of the test’s initial URL.expires
(optional number): Epoch timestamp (in milliseconds) indicating when the cookie should be deleted. If unspecified, the cookie becomes a session cookie.httpOnly
(optional boolean): Indicates the cookie should be inaccessible to JavaScript on the page and only sent to the server.maxAge
(optional number): Number of milliseconds until the cookie expires. If both expires
and maxAge
are set, maxAge
has precedence.path
(optional string): A URL path that must exist in a request URL in order to include the cookie in a request.secure
(optional boolean): Indicates that the cookie should only be sent to the server when a request is made with https:
.headers
: Allows you to specify headers that will be sent when loading the test’s initial URL.
name
(required string): The name of the header.value
(required string): The header value.persist
(optional boolean): Specifies whether this header should only be set in the initial request or for every subsequent HTTP request (ex: when overriding the Accept-Language header). If set to true
, the Authorization
header is only set for requests that match the hostname of the test’s original URL. Defaults to false
.localStorage
and sessionStorage
: Allows you to specify local and
session storage values to be set on the test’s initial URL.The variables
field allows you to specify a definition for a variable used in the tests.
Finally, if your Reflect account has OAuthed with GitHub, you can specify a repository, its owner, and a commit SHA in the request to have Reflect automatically post a commit status to GitHub as the suite’s execution progresses.
POST https://api.reflect.run/v1/suites/<suite-id>/executions
{
"overrides": {
"hostnames": [{
"original": "prod.myapp.com",
"replacement": "staging.myapp.com"
}],
"parameters": [{
"key": "token",
"value": "abcdef"
}],
"cookies": [{
"name": "my-favorite-cookie",
"value": "chocolate-chip",
"domain": "myapp.com",
"expires": 123456789,
"httpOnly": false,
"maxAge": 123,
"path": "/",
"secure": true
}],
"headers": [{
"name": "X-Custom-Header",
"value": "custom-value",
"persist": false
}],
"localStorage": [{
"key": "my-local-key",
"value": "local-value"
}],
"sessionStorage": [{
"key": "my-session-key",
"value": "session-value"
}]
},
"variables": {
"username1": "user+${alpha(8)}@example.com",
"password": "acompletelyunguessablepassword"
},
"gitHub": {
"owner": "repository-owner",
"repo": "my-repository-name",
"sha": "0f4212320f2cb6734583ebef3a4928d78d4f3fde"
}
}
{
"suiteId": "regression-tests",
"executionId": 3878,
"overrides": {
"hostnames": [
{
"original": "prod.myapp.com",
"replacement": "staging.myapp.com"
}
],
"parameters": [
{
"key": "token",
"value": "abcdef"
}
]
},
"gitHub": {
"owner": "repository-owner",
"repo": "my-repository-name",
"sha": "0f4212320f2cb6734583ebef3a4928d78d4f3fde"
},
"url": "https://app.reflect.run/suites/regression-tests/executions/3878",
"isFinished": false,
"status": "pending",
"tests": {
"data": [],
"bookmark": ""
}
}
Returns the completion status of the specified suite.
GET https://api.reflect.run/v1/suites/<suite-id>/executions/<execution-id>
{
"suiteId": "regression-tests",
"executionId": 36,
"overrides": {
"hostnames": [
{
"original": "prod.myapp.com",
"replacement": "staging.myapp.com"
}
],
"parameters": [
{
"key": "token",
"value": "abcdef"
}
]
},
"gitHub": {
"owner": "repository-owner",
"repo": "my-repository-name",
"sha": "0f4212320f2cb6734583ebef3a4928d78d4f3fde"
},
"url": "https://app.reflect.run/suites/regression-tests/executions/36",
"isFinished": true,
"status": "passed",
"tests": {
"data": [
{
"instanceId": 0,
"testId": 683,
"startingUrl": "https://staging.myapp.com/test-one",
"status": "passed",
"runs": [
{
"runId": 2641,
"browser": "Chrome",
"status": "passed",
"variables": {},
"startTime": 1643734963077,
"endTime": 1643734979203,
"runTime": 16126,
"timestamp": 1643734979647,
"videoUrl": "https://reflect-videos.s3.amazonaws.com/2641_969e.mp4"
}
]
},
{
"instanceId": 1,
"testId": 686,
"startingUrl": "https://staging.myapp.com/test-two",
"status": "passed",
"runs": [
{
"runId": 2642,
"browser": "Chrome",
"status": "passed",
"variables": {},
"startTime": 1643734994863,
"endTime": 1643735012070,
"runTime": 17207,
"timestamp": 1643735012534,
"videoUrl": "https://reflect-videos.s3.amazonaws.com/2641_89f7.mp4"
}
]
}
],
"bookmark": ""
}
}
Attempts to cancel the specified suite execution.
PATCH https://api.reflect.run/v1/suites/<suite-id>/executions/<execution-id>/cancel
{
"suiteId": "regression-tests",
"executionId": 3878,
"success": true
}
Thanks! Your message has been submitted successfully.
Sorry! Something Went Wrong.