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.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 or parameter 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"
}],
"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"
}
]
},
"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": ""
}
}
Similar to the execute a suite endpoint, this endpoint invokes a Reflect test suite with a set of optional overrides.
However, this endpoint has the additional capability of accepting a set of data-driven values in a CSV file. Those values are used to override the (test, parameters) pairs for a specific Run Tests action in the Suite. Multiple CSV files can be sent to override different Run Tests actions.
This endpoint requires sending data in a multipart request, consisting of:
application/json
part containing the fields described in Request JSON Fields.POST https://api.reflect.run/v1/suites/<suite-id>/executions/data-driven
Or via curl
through the following command:
curl \
-H 'X-API-KEY: <API-KEY>' \
-F 'config={"actionNameByFilename": {"one.csv": "run-tests-1", "two.csv": "run-tests-2"}};type=application/json' \
-F fileone=@one.csv \
-F filetwo=@two.csv \
https://api.reflect.run/v1/suites/<suite-id>/executions/data-driven
Each CSV file in the request should be in the following format:
Test Name or ID,Parameter One,Parameter Two,Parameter Three
1,value one,${var(one)},value three
1,,value two,${var(two)}
two,value one,value two,value three
The first column is the ID or name of a Test, all columns that follow are values for the parameter names specified in the header row of the CSV.
Note that any column whose value is left empty will not be overridden. For example, in the second data row ‘Parameter One’ is not overridden with any value.
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"
}
]
},
"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,
"actionName": "run-tests-1",
"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.