Test Runs API: Query History, Results, and HTML Reports

The Test Runs API provides persistent, queryable access to every execution that QA Flow has performed. Each test run is stored as a TestRun record in the database, with a nested array of TestResult objects — one for every node that was executed. You can list recent runs globally, fetch all runs for a specific project, drill into a single run’s full results, or retrieve the generated HTML report for any completed run.

TestRun Object

string

UUID of the test run.

projectId

string

UUID of the project this run belongs to.

status

string

Lifecycle status of the run. One of: pending, running, completed, failed.

startedAt

string | null

ISO 8601 timestamp when execution began, or null if still pending.

completedAt

string | null

ISO 8601 timestamp when execution finished, or null if still running.

error

string | null

Top-level error message if the entire run failed; null otherwise.

totalTests

number

Total number of nodes executed in the run.

passedTests

number

Number of nodes that passed.

failedTests

number

Number of nodes that failed.

duration

number | null

Total execution time in milliseconds, or null if not yet complete.

createdAt

string

ISO 8601 timestamp when the TestRun record was created in the database.

results

TestResult[]

Array of per-node result records. Populated when fetching an individual run via GET /api/test-runs/:id.

Show TestResult fields

string

UUID of the result record.

testRunId

string

UUID of the parent test run.

nodeId

string

ID of the flow node that produced this result.

nodeType

string

Type of the node (e.g. navigate, click, assert, fill).

nodeLabel

string | null

Human-readable label of the node, if configured.

testName

string | null

Name of the Playwright test block the node belongs to.

success

boolean

Whether the node action passed (true) or failed (false).

message

string | null

Descriptive result message.

error

string | null

Error message if the node failed; null on success.

duration

number | null

Time in milliseconds the node action took to complete.

screenshot

string | null

Path or base64-encoded screenshot captured at the time of failure.

executedAt

string

ISO 8601 timestamp when this result was recorded.

GET /api/test-runs

List the most recent test runs across all projects. Results are ordered by creation date descending. Use the limit query parameter to control the number of records returned. Authentication required: No

Query Parameters

limit

number

Maximum number of test runs to return. Defaults to 20.

Response

An array of TestRun objects (without the nested results array for performance — use GET /api/test-runs/:id to fetch results).

curl 'http://localhost:3001/api/test-runs?limit=5'

GET /api/test-runs/:id

Retrieve a single test run with its complete array of TestResult records. Use this endpoint to display a full execution report with per-node pass/fail details. Authentication required: No

Path Parameters

string

required

The UUID of the test run to retrieve.

Response

A TestRun object with a populated results array. Returns 404 Not Found if the run does not exist.

curl http://localhost:3001/api/test-runs/run-aaa-111

GET /api/test-runs/project/:projectId

Retrieve the most recent test runs for a specific project, ordered by creation date descending. Useful for displaying a project’s run history in the UI. Authentication required: No

Path Parameters

projectId

string

required

The UUID of the project whose run history to retrieve.

Query Parameters

limit

number

Maximum number of test runs to return. Defaults to 10.

Response

An array of TestRun objects (without nested results).

curl 'http://localhost:3001/api/test-runs/project/proj-abc-123?limit=3'

GET /api/test-runs/:id/report

Retrieve the HTML report generated for a completed test run. The response format is determined by content negotiation using the Accept header. Authentication required: No

Path Parameters

string

required

The UUID of the test run whose report to retrieve.

Content Negotiation

HTML Response
JSON Response

When the request includes Accept: text/html, the server responds with the raw HTML report suitable for rendering directly in a browser iframe or a new tab.

curl http://localhost:3001/api/test-runs/run-aaa-111/report \
  -H 'Accept: text/html'

Response: Content-Type: text/html — full rendered HTML report.

When the request omits the Accept header or uses Accept: application/json, the server responds with the report metadata and HTML content in a JSON envelope.

curl http://localhost:3001/api/test-runs/run-aaa-111/report \
  -H 'Accept: application/json'

{
  "htmlContent": "<!DOCTYPE html><html>...</html>",
  "summary": {
    "totalTests": 8,
    "passedTests": 8,
    "failedTests": 0,
    "duration": 45320
  }
}

Returns 404 Not Found with { "error": "Reporte no encontrado" } if no report has been generated for the specified test run yet. Reports are created automatically when a run completes.

Overview

Endpoints

Test Runs API: Query History, Results, and HTML Reports

TestRun Object

GET /api/test-runs

Query Parameters

Response

GET /api/test-runs/:id

Path Parameters

Response

GET /api/test-runs/project/:projectId

Path Parameters

Query Parameters

Response

GET /api/test-runs/:id/report

Path Parameters

Content Negotiation

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​TestRun Object

​GET /api/test-runs

​Query Parameters

​Response

​GET /api/test-runs/:id

​Path Parameters

​Response

​GET /api/test-runs/project/:projectId

​Path Parameters

​Query Parameters

​Response

​GET /api/test-runs/:id/report

​Path Parameters

​Content Negotiation

Build docs developers (and LLMs) love

TestRun Object

GET /api/test-runs

Query Parameters

Response

GET /api/test-runs/:id

Path Parameters

Response

GET /api/test-runs/project/:projectId

Path Parameters

Query Parameters

Response

GET /api/test-runs/:id/report

Path Parameters

Content Negotiation