Tests API

List all tests

Returns a list of test descriptions containing the test’s id, name, created timestamp and folders.

Request

GET https://api.reflect.run/v1/tests

Response

{
  "tests": [
    {
      "id": 3072323,
      "name": "Registration Flow",
      "created": 1570546969108,
      "folders": [
        "all",
        "regression-tests"
      ]
    }
  ]
}

Response Fields

Run a test

Immediately schedules a test.

The browser field allows you to specify the browser to run the test with. Supported values are: Chrome, Edge, Firefox, and Safari - if no value is specified Chrome is used.

Reflect identifies certain properties of the 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. You can also optionally specify a new port by including it in the replacement (see below for an example). If your override specifies a port, note the following behavior:
  • If original includes a port value, it will only be applied on URLs of the test that also use that same port. For example, an original value of example.com:1234 would have no effect on https://example.com or https://example.com:5678.
  • If original does not include a port value, it will match every URL of the test that uses the same hostname, regardless of port. For example, an original value of example.com would match both https://example.com and https://example.com:1234.
  • If a port was specified in the URL of the test, it will be preserved unless a new value is specified in replacement or original included the port and replacement did not - in that case no port would be included in the resulting URL.
• 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 test.

Request

POST https://api.reflect.run/v1/tests/<test-id>/executions

{
  "browser": "Chrome",
  "overrides": {
    "hostnames": [{
      "original": "prod.myapp.com",
      "replacement": "staging.myapp.com:1234"
    }],
    "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"
    }],
    "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"
  },
  "emailFailures": true
}

Request Fields

Response

{
  "executionId": 8939
}

Response Fields

Get execution status

Returns a list of test result objects. The test result object includes the test’s id and a status field describing whether the test is “queued”, “running”, “succeeded”, or “failed”. Additionally, it contains a run object describing the properties of the test run such as its starting and ending time, and its video URL.

Request

GET https://api.reflect.run/v1/executions/<execution-id>

Response

{
  "executionId": 17671,
  "browser": "Edge",
  "tests": [
    {
      "testId": 1690,
      "status": "succeeded",
      "run": {
        "runId": 690,
        "status": "passed",
        "variables": {},
        "startTime": 1654632014295,
        "endTime": 1654632027297,
        "runTime": 13002,
        "videoUrl": "https://reflect-videos.s3.amazonaws.com/690_89f4.mp4"
      }
    }
  ]
}

Response Fields