Running Tests via API

API Key Authentication

To run tests via the API, organizations must generate an API Key:

• API Keys can be created and managed under Settings > API Keys.
• The API Key must be included in the request headers as a Bearer token.
• Learn more at API Keys.

Triggering Test Runs via API

You can run tests via the API in two ways:

1. Run a Test Suite

Triggers all tests within a given Test Suite.

Endpoint:

POST https://verex.ai/api/apiRunners/runTestSuite/{suiteId}

Headers:

Authorization: Bearer {API_KEY}

Request Body:

{
  "url": "https://your-domain-to-test.com"
}

Required Parameters:

• suiteId (path) – The ID of the test suite to run.

Response Format:

{
  "testSuiteRun": {
    "id": "testSuiteRunId",
    "status": "PENDING",
    "startedAt": "2024-03-20T13:45:00.000Z",
    "completedAt": null
  },
  "testRuns": [
    {
      "id": "testRunId1",
      "status": "PENDING",
      "startedAt": "2024-03-20T13:45:00.000Z",
      "completedAt": null
    },
    {
      "id": "testRunId2",
      "status": "PENDING",
      "startedAt": "2024-03-20T13:45:00.000Z",
      "completedAt": null
    }
  ]
}

Note: A test suite run will only be marked as PASSED if all underlying test runs complete with the PASSED status. If any test run returns FAILED or STOPPED, the test suite run will be marked as FAILED.

2. Run an Individual Test

Triggers a single test from a suite.

Endpoint:

POST https://verex.ai/api/apiRunners/runTest/{testId}

Headers:

Authorization: Bearer {API_KEY}

Request Body:

{
  "url": "https://your-domain-to-test.com"
}

Required Parameters:

• testId (path) – The ID of the test to run.

Response Format:

{
  "testRun": {
    "id": "testRunId",
    "status": "PENDING"
  }
}

Note: Only enabled tests will be executed. When running a test suite, any disabled tests will be ignored. If you attempt to run a disabled individual test, the API will return a 403 Forbidden response.

Fetching Test Run Results

Once a test or test suite is executed, you can retrieve its results:

1. Get Test Suite Run Details

Retrieves details of a Test Suite Run, including test execution history.

Endpoint:

GET https://verex.ai/api/apiRunners/testSuiteRun/{testSuiteRunId}

Query Parameters:

• includeTestRuns (optional) – "true" or "false" (default: "false").

Required Parameters:

• testSuiteRunId (path) – The ID of the test suite run.

Response Format:

{
  "testSuiteRun": {
    "id": "testSuiteRunId",
    "status": "FAILED",
    "startedAt": "2024-03-20T13:45:00.000Z",
    "completedAt": "2024-03-20T13:46:30.000Z"
  },
  "testRuns": [
    {
      "id": "testRunId1",
      "status": "PASSED",
      "startedAt": "2024-03-20T13:45:00.000Z",
      "completedAt": "2024-03-20T13:46:00.000Z"
    },
    {
      "id": "testRunId2",
      "status": "FAILED",
      "startedAt": "2024-03-20T13:45:10.000Z",
      "completedAt": "2024-03-20T13:46:30.000Z"
    }
  ]
}

2. Get Individual Test Run Details

Fetches the result of a specific test execution.

Endpoint:

GET https://verex.ai/api/apiRunners/testRun/{testRunId}

Required Parameters:

• testRunId (path) – The ID of the test run.

Response Format:

{
  "id": "testRunId",
  "status": "STOPPED",
  "startedAt": "2024-03-20T13:45:00.000Z",
  "completedAt": "2024-03-20T13:45:25.000Z"
}

Note: All startedAt and completedAt timestamps are returned in ISO 8601 format (e.g., 2024-03-20T13:45:00.000Z).

Possible Test Statuses

The status field returned in API responses will always be in uppercase. Possible values include:

• PENDING – The test has been queued and is waiting to start.
• RUNNING – The test is currently in progress.
• PASSED – The test ran successfully and met all criteria.
• FAILED – The test ran but did not meet the criteria.
• STOPPED – The test was manually stopped (e.g., via the UI).

Stopping a Test Run

Currently, stopping a test run via the API is not supported. This feature will be added in a future update.

Next Steps

• API Keys
• Running Tests
• Integrations