Tests API

Execute tests and get the status of individual test runs.

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": [
        "regression-tests"
      ]
    }
  ]
}

RESPONSE FIELDS

tests object: A list of test descriptions, including the test's id, name and folders.

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.

Note

Your account must have access to the requested browser - requesting an unsupported browser will return a 400 error code.

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.

  • agent: Allows you to select a specific Tunnel to run the test through by specifying the agent’s name.

  • 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": {
    "agent": {
      "name": "agent-name"
    },
  
     "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

overrides optional object: Overrides to apply to properties of the test being executed.

  • agent (object, optional)

    • name (string, required) — The name of the Tunnel/Agent to use for this execution.

variables optional object: Collection of ('name', 'definition') variable overrides to apply to this scheduled execution.

emailFailures optional boolean: Controls whether email notifications should be sent for a failed test run. The default is true.

RESPONSE

{
  "executionId": 8939
}

RESPONSE FIELDS

executionId number: An identifier for the scheduled execution created by the request.

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

executionId number: An identifier for the scheduled execution.

browser string: The browser that the tests in the scheduled execution are configured to run on.

tests object: List of test results, including the testId and status.

tests.testId number: An identifier for the test.

tests.status string: One of: queued, running, succeeded, or failed. Summarizes the outcome of the test instance from its runs.

tests.run object: The test run from this execution.

tests.run.runId number: An identifier for the test run.

tests.run.status string: The outcome of the test run. Either passed or failed.

tests.run.variables object: The variables that were used or created by the test run.

tests.run.startTime number: Timestamp of when the test run started.

tests.run.endTime number: Timestamp of when the test run stopped.

tests.run.runTime number: Total time that the test run spent running (endTime - startTime).

tests.run.videoUrl string: The URL of a video recording of the test run.

Get Test Detail

Returns the full step-by-step definition of a single test, including any segments it references.

Request

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

Path parameters

  • test-id (integer) The Test ID (visible in the Reflect app URL when viewing the test).

    Steps that reference a Reflect Segment appear with "type": "segment" and include the segment's id and name. To get the steps inside a referenced segment, call GET https://api.reflect.run/v1/segments and look it up by ID.

Response

{
    "id": 98765,
    "name": "End-to-end checkout",
    "description": "Full purchase flow against staging",
    "steps": [
      {
        "type": "segment",
        "id": 12345,
        "name": "Login flow"
      },
      {
        "type": "direct-navigation",
        "url": "https://staging.example.com/products/42"
      },
      {
        "type": "click",
        "description": "Add to cart",
        "selector": "[data-test='add-to-cart']"
      },
      {
        "type": "prompt",
        "description": "Validate that one item is in the shopping cart"
      },
      {
        "type": "api",
        "httpMethod": "POST",
        "url": "https://api.example.com/coupons/redeem",
        "requestBody": "{\"code\":\"WELCOME10\"}"
      },
      {
        "type": "visual-validation",
        "selector": ".order-confirmation"
      }
    ],
    "parameters": [
      { "name": "checkout_amount", "value": "49.99" }
    ]
  }

Create a test

Creates a new test

Note: SmartBear MCP server also supports this functionality with a corresponding create-test tool call such that AI Agents like Claude can build or import existing tests built on open source frameworks (Selenium, Cypress, Playwright) or in other SmartBear products (TestComplete, BearQ)

Request

POST https://api.reflect.run//v1/tests
Web Test example request body

{ 
    "name": "Comprehensive Web Test (docs)",  
    "type": "web",  
    "description": "A web test exercising every supported step type with all applicable fields.",  
    "deviceProfile": "desktop",  
    "steps": [    
        { "type": "browser-navigate", "description": "Go to the home page", "url": "https://example.com", "title": "Example Home" },    
        { "type": "segment", "id": 12345 },    
        { "type": "click", "description": "Click the login button", "selector": "#login", "tag": "button", "expectedText": "Log in" },    
        { "type": "visual-validation", "description": "Visually validate the hero section", "selector": ".hero", "tag": "section", "expectedText": "Welcome" },    
        { "type": "text-validation", "description": "Validate the status message text", "selector": ".msg", "tag": "span", "expectedText": "Success" },    
        { "type": "input", "description": "Enter the username", "selector": "#user", "tag": "input", "inputText": "alice", "expectedText": "Username" },    
        { "type": "rich-text-input", "description": "Enter the rich-text body", "selector": "#body", "tag": "div", "inputText": "hello world", "expectedText": "Body" },    
        { "type": "submit", "description": "Submit the form", "selector": "#form", "tag": "form", "expectedText": "Submit" },    
        { "type": "file-upload", "description": "Upload a file", "selector": "#file", "tag": "input", "expectedText": "Choose file" },    
        { "type": "scroll", "description": "Scroll the results list", "selector": ".list", "tag": "ul", "expectedText": "Results" },    
        { "type": "keyboard-shortcut", "description": "Send a keyboard shortcut", "selector": "body", "tag": "body", "inputText": "Ctrl+Shift+a", "expectedText": "Focused" },    
        { "type": "focus", "description": "Focus the email field", "selector": "#email", "tag": "input", "expectedText": "Email" },    
        { "type": "hover", "description": "Hover the menu", "selector": "#menu", "tag": "nav", "expectedText": "Menu" },    
        { "type": "alert", "description": "Accept the browser alert" },    
        { "type": "drag-and-drop", "description": "Drag an item", "selector": "#item", "tag": "li", "expectedText": "Item" },    
        { "type": "text-highlight", "description": "Highlight a paragraph", "selector": "#para", "tag": "p", "expectedText": "Paragraph" },    
        { "type": "browser-url-changed", "description": "Follow a link", "url": "https://example.com/page3", "title": "Page 3" },    
        { "type": "browser-back", "description": "Navigate back", "title": "Example Home" },    
        { "type": "browser-forward", "description": "Navigate forward", "title": "Page 3" },    
        { "type": "browser-refresh", "description": "Refresh the page", "title": "Page 3" },    
        { "type": "api", "description": "Call an API", "url": "https://api.example.com/orders", "httpMethod": "POST", "requestBody": "{\"a\":1}", "requestHeaders": [ { "name": "Content-Type", "value": "application/json" }, { "name": "Authorization", "value": "Bearer ${var(token)}" } ], "followRedirects": false },    
        { "type": "javascript", "description": "Run a JavaScript snippet", "script": "return document.title;" },    
        { "type": "prompt", "description": "Verify the dashboard loaded", "promptType": "action" },    
        { "type": "prompt", "description": "Is the form valid?", "promptType": "assert", "expectedResponse": true },    
        { "type": "prompt", "description": "What is the order total?", "promptType": "query", "expectedResponse": "42" },    
        { "type": "file-download", "description": "Download the report" },    { "type": "update-parameters", "description": "Update run parameters" },    
        { "type": "wait", "description": "Wait for animations", "seconds": 5 },    
        { "type": "receive-email", "description": "Wait for the welcome email", "email": { "text": "Welcome", "filters": { "fromAddress": "noreply@example.com", "fromName": "Example", "subject": "Welcome", "toAddress": "alice@example.com" } } },    
        { "type": "receive-sms", "description": "Wait for the verification code", "sms": { "text": "Your code is 123456", "filters": { "fromNumber": "+15551230000", "toNumber": "+15559876543" } } }  ],  
    "parameters": [    
        { "name": "env", "value": "prod" },    
        { "name": "token", "value": "abc123" }  ]}

API Test example request body

{  
    "name": "Comprehensive API Test (docs)",  
    "type": "api",  "description": "An API test exercising every supported step type with all applicable fields.",  
    "steps": [    
        { "type": "segment", "id": 12345 },    
        { "type": "api", "description": "Call an API", "url": "https://api.example.com/orders", "httpMethod": "POST", "requestBody": "{\"a\":1}", "requestHeaders": [ { "name": "Content-Type", "value": "application/json" }, { "name": "Authorization", "value": "Bearer ${var(token)}" } ], "followRedirects": false },    
        { "type": "javascript", "description": "Run a JavaScript snippet", "script": "return 1 + 1;" },    
        { "type": "wait", "description": "Wait between calls", "seconds": 3 },    
        { "type": "update-parameters", "description": "Update run parameters" },    
        { "type": "receive-email", "description": "Wait for a notification email", "email": { "text": "Order created", "filters": { "fromAddress": "noreply@example.com", "fromName": "Example", "subject": "Order", "toAddress": "alice@example.com" } } },    
        { "type": "receive-sms", "description": "Wait for an SMS notification", "sms": { "text": "Order 123 created", "filters": { "fromNumber": "+15551230000", "toNumber": "+15559876543" } } }  ],  
    "parameters": [    
        { "name": "env", "value": "prod" },    
        { "name": "token", "value": "abc123" }  ]}

Native mobile Test example request body

{  
    "name": "Comprehensive Mobile Test (docs)",  
    "type": "native-mobile",  
    "description": "A native-mobile test exercising every supported step type with all applicable fields.",  
    "steps": [    
        { "type": "segment", "id": 12345 },    
        { "type": "prompt", "description": "Tap the login button", "promptType": "action", "expectedResult": "The login screen is shown" },    
        { "type": "prompt", "description": "Is the user logged in?", "promptType": "assert", "expectedResponse": true, "expectedResult": "The home screen is shown" },    
        { "type": "prompt", "description": "What is the account balance?", "promptType": "query", "expectedResponse": "100.00", "expectedResult": "The balance is displayed" },    
        { "type": "text-validation", "description": "Validate the greeting text", "expectedText": "Welcome back" },    { "type": "rotate-device", "description": "Rotate the device" },    
        { "type": "set-device-location", "description": "Set the GPS location", "latitude": 37.7749, "longitude": -122.4194 },    
        { "type": "reset-device", "description": "Reset the app state" },    
        { "type": "deeplink", "description": "Open a deeplink", "url": "myapp://home" },    
        { "type": "appium", "description": "Run an Appium command", "command": "scroll", "argument": "{\"direction\":\"down\"}" },    
        { "type": "api", "description": "Call a backend API", "url": "https://api.example.com/orders", "httpMethod": "GET", "requestHeaders": [ { "name": "Accept", "value": "application/json" } ], "followRedirects": true },    
        { "type": "wait", "description": "Wait for the screen", "seconds": 2 },    
        { "type": "update-parameters", "description": "Update run parameters" },    
        { "type": "receive-email", "description": "Wait for the confirmation email", "email": { "text": "Confirmed", "filters": { "fromAddress": "noreply@example.com", "fromName": "Example", "subject": "Confirmation", "toAddress": "alice@example.com" } } },    
        { "type": "receive-sms", "description": "Wait for the verification code", "sms": { "text": "Your code is 123456", "filters": { "fromNumber": "+15551230000", "toNumber": "+15559876543" } } }  ],  
    "parameters": [    
        { "name": "env", "value": "prod" },    
        { "name": "token", "value": "abc123" }  ]}

Request Fields

name (string, required): Name of the test

description (string, optional): description of the test

type (string, required): Supported values: web, api, native-mobile

steps: an ordered list of test steps

parameters: an optional set of parameters associated with the test. Each parameter can optionally have a default value.

Response

{"id":10,"url":"https://app.reflect.run/tests/1234/definition?accountId=123"}
In this section:
© 2026
Publication date: