API Documentation

Signing Requests

To access the Reflect API, you must sign all requests using your API key. API keys are associated with your account, not your user, which means that all users of your account will share the same API key.

For every API request, an X-API-KEY request header must be populated with your API key.

To view your API key, navigate to Settings > Account Information.

List all tests

Returns a list of test descriptions. Each description contains the test’s id, name, created timestamp and associated tags. The tags values are in the “slug” format that you can use to execute that tag’s tests with the “Run tests associated with a tag” endpoint (below).

Request

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

Response

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

Response Fields

Run a test

Immediately schedules a test. 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.
• 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

{
  "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

Run a Data-Driven test

Schedules multiple runs of the same test using different values for the variables in the test. This endpoint accepts a CSV file where the first row is the header row and each subsequent row is a list of comma-separated values. The header row specifies the names of the variables that the test uses and will be replaced by specific values in each data row that follows. Reflect will schedule and execute 1 test for each data row in the CSV file, overwriting the test’s defined variable value with the specified value from the input. Any variables that are not overwritten by the input will be computed normally, and any variable specified in the input that is not used by the test will be ignored.

Request

POST https://api.reflect.run/v1/tests/<test-id>/multiples
Content-Type: multipart/form-data

name,age,location
Bob,29,Philadelphia
Mary,89,Sacramento

Request Fields

Response

{}

Run tests associated with a tag

Immediately schedules all tests associated with the given tag. The tag-slug value for your tag should match the slug value on the test tags page, including text casing. By default, the tests will execute sequentially by test creation date. To execute a maximum of N tests in parallel, set the parallelism value to N. To execute all tests simultaneously, set the parallelism value to 0.

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.
• 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.

If you do not want Reflect to send email notifications for tests that fail during the execution, set the emailFailures parameter to false.

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 tests complete execution.

Request

POST https://api.reflect.run/v1/tags/<tag-slug>/executions

{
  "parallelism": 1,
  "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"
    }],
    "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,
  "gitHub": {
    "owner": "repository-owner",
    "repo": "my-repository-name",
    "sha": "0f4212320f2cb6734583ebef3a4928d78d4f3fde"
  }
}

Request Fields

Response

{
  "executionId": 8939,
  "nTestsQueued": 5
}

Response Fields

Get execution status

Returns a list of test result objects. The test result object includes the test’s id, timestamps and a status field describing whether the test is “queued”, “running”, “succeeded”, or “failed”.

Request

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

Response

{
  "executionId": 17671,
  "tests": [
    {
      "testId": 1690,
      "status": "running",
      "started": 1590984798187
    },
    {
      "testId": 1691,
      "status": "succeeded",
      "started": 1590984798187,
      "completed": 1590984998187
    }
  ]
}

Response Fields