Reflect Docs

API Documentation

Learn how to integrate with Reflect via our API.

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.

Note: If you wish to revoke your API key and generate a new one, please email support@reflect.run.

To view your API key, navigate to Settings > Configuration.

Finding your API key

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

Note: Every test in the Reflect account is associated with the all tag.
Request
GET https://api.reflect.run/v1/tests
Response
{
  "tests": [
    {
      "id": 3072323,
      "name": "Registration Flow",
      "created": 1570546969108,
      "tags": [
        "all",
        "regression-tests"
      ]
    }
  ]
}
Response Fields
tests
object
A list of test descriptions, including the test's id, name and associated tags.

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. The hostnames field allows you to specify a replacement hostname value for a given target hostname. The parameters field allows you to specify a URL parameter key/value pair that will be included (or overwritten) 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"
    }],
    "parameters": [{
      "key": "token",
      "value": "abcdef"
    }]
  },
  "variables": {
    "username1": "user+${alpha(8)}@example.com",
    "password": "acompletelyunguessablepassword"
  }
}
Request Fields
overrides
optional object
Overrides to apply to properties of the test being executed.
variables
optional object
Collection of ('name', 'definition') variable overrides to apply to this scheduled execution.
Response
{
  "executionId": 8939
}
Response Fields
executionId
number
An identifier for the scheduled execution created by the request.

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
body
A CSV file with a header row and 1 or more data rows.
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. The hostnames field allows you to specify a replacement hostname value for a given target hostname. This supports the common use case of executing a set of Reflect tests against a different (e.g., temporary) environment during software development. The parameters field allows you to specify a URL parameter key/value pair that will be included (or overwritten) 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 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"
    }]
  },
  "variables": {
    "username1": "user+${alpha(8)}@example.com",
    "password": "acompletelyunguessablepassword"
  },
  "gitHub": {
    "repo": "my-repository-name",
    "sha": "0f4212320f2cb6734583ebef3a4928d78d4f3fde"
  }
}
Request Fields
parallelism
optional number
The maximum number of concurrently executing tests. Use 0 to run all tests in parallel. The default is 1.
overrides
optional object
Overrides to apply to properties of all tests executed in this scheduled execution.
variables
optional object
Collection of ('name', 'definition') variable overrides to apply to this scheduled execution.
gitHub
optional object
An object specifying the GitHub repository name and commit SHA to post the status of the execution.
Response
{
  "executionId": 8939,
  "nTestsQueued": 5
}
Response Fields
executionId
number
An identifier for the scheduled execution created by the request.
nTestsQueued
number
The number of tests that have been queued up to be executed as part of this action. This is equivalent to the number of tests associated with the given tag.

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
executionId
number
An identifier for the scheduled execution.
tests
object
List of test results, including the status and timestamps.
Copyright © 2020 Reflect Software LLC. All Rights Reserved.