Testifly logo Testifly logo

Test Execution API Workflow

This guide shows the full flow for starting a new test execution, checking the job that was created, and then loading the final test run report.

  • You can use our swagger interface to send requests and explore the API.
  • You can also use any API client like Postman or Insomnia, or write your own scripts to automate the execution and reporting.

1. Start a new test execution

  1. Send a request to POST /api/testExecution/{projId}.
  2. Include your project API key in the x-api-key header.
  3. Pass action: "executeTests" and add the filters that describe what should run.
  4. If you have remote agents connected, you can also pass agentName to route the job to a specific runner.
  5. Save the returned jobId, because you will use it to track the execution job.

The request body below starts a run for a feature. You can swap featureId for testSuiteId, testId, or tests depending on what you want to execute.

{
  "action": "executeTests",
  "featureId": "67f8cb3fe236b8d41b7700ac",
  "agentName": "my-agent"
}

The API response tells you whether the job was accepted and gives you the job identifier.

{
  "success": true,
  "scheduleStatus": "Success",
  "jobId": "6804f1d1d2d4e0a1c1a0d123"
}

What the request fields mean

  • featureId runs every test that belongs to one feature.
  • testSuiteId runs every test in one test suite.
  • testId runs one test.
  • tests runs a custom list of test ids.
  • agentName routes the job to a specific agent when you want to target one runner.

If the API returns AlreadyExists, the same execution job is already queued, so you should reuse the existing jobId instead of creating a duplicate run.

2. Monitor the job status

  1. Send a request to POST /api/jobs/{projId}.
  2. Pass the jobIds you want to inspect.
  3. Poll this endpoint until the job reaches a terminal state.
  4. Use the returned testRunId to open the final run report.

The request body below checks one job. You can include more job ids in the same array if you want to poll several executions at once. You can also omit the jobIds field to get a list of all active jobs for the project from the last month, but that is not recommended for regular polling because the response will be larger and less efficient to process.

{
  "jobIds": ["6804f1d1d2d4e0a1c1a0d123"]
}

A typical status response contains the current job state, the last update time, and the linked test run id when it becomes available.

{
  "success": true,
  "jobs": [
    {
      "jobId": "6804f1d1d2d4e0a1c1a0d123",
      "status": "InProgress",
      "updatedAt": "2026-04-20T10:15:30.000Z",
      "testRunId": "6804f1e2d2d4e0a1c1a0d456"
    }
  ],
  "missingJobIds": []
}

How to read the job status

  • Pending means the job has been created and is waiting to start.
  • PendingAgentConnection means the job is waiting for an agent to connect.
  • InProgress means execution has started.
  • Success or Failed means the job is finished.
  • updatedAt tells you when the backend last changed the job record.
  • testRunId appears when the execution has produced a test run record.
  • missingJobIds lists ids that were invalid, missing, or did not belong to the project.

3. Monitor the test run status and result

  1. Wait until the job response includes a testRunId.
  2. Send a request to GET /api/testRun/{projId}/{runId}.
  3. Read the overall run summary first, then inspect each test result.
  4. Use the per-test status, timeline, and video link to understand what happened during execution.

The run report response gives you the full result set for the execution.

{
  "runId": "6804f1e2d2d4e0a1c1a0d456",
  "projectId": "67f8cb3fe236b8d41b7700ac",
  "status": "Completed",
  "startTime": "2026-04-20T10:15:31.000Z",
  "testsInProjectCount": 24,
  "title": "Regression run",
  "statuses": [
    {
      "label": "Passed",
      "count": 18
    },
    {
      "label": "Failed",
      "count": 2
    },
    {
      "label": "Skipped",
      "count": 4
    }
  ],
  "tests": [
    {
      "_id": "6804f1f1d2d4e0a1c1a0d789",
      "title": "Login works for valid users",
      "status": "Passed",
      "duration": 1240,
      "hasVideo": true,
      "videoLink": "https://example.com/videos/run-1",
      "startTime": "2026-04-20T10:15:40.000Z",
      "timeline": []
    }
  ]
}

What to look for in the run report

  • status shows the overall run state.
  • statuses gives the summary counts for passed, failed, skipped, running, and scheduled tests.
  • tests contains the individual test results.
  • duration shows how long each test took.
  • timeline helps you inspect the execution steps for a specific test.
  • videoLink points to the recorded run when a video is available.
  • error explains why a test failed when the execution did not succeed.

4. Suggested polling flow

  1. Create the execution job.
  2. Poll /api/jobs/{projId} until the job status becomes InProgress or Success and a testRunId is present.
  3. Load /api/testRun/{projId}/{runId} with that testRunId.
  4. Keep refreshing the run report if you want to watch live progress while the job is still running.

5. Authentication and access

All documented endpoints expect the project API key in the x-api-key header.

x-api-key: your_project_api_key

If the key is missing or invalid, the API rejects the request before it reaches the execution or status logic.

6. Quick reference

  • POST /api/testExecution/{projId} starts a new execution.
  • POST /api/jobs/{projId} checks execution job status.
  • GET /api/testRun/{projId}/{runId} loads the final run report.

Use the job response to find the run id, then use the run report to inspect the final result details.