@crvouga/atlas 0.9.0 → 0.10.0

package/dist/server/src/app.js

@@ -25,6 +25,7 @@ import { reportStatus } from '../../reports/src/report-status.js';
 import { ReportIndex } from '../../reports/src/report-index.js';
 import { listRunSummaries, readRunFile } from '../../reports/src/run-bundle.js';
 import { latestSpecSet, readSpecBody } from '../../reports/src/spec-set.js';
+import { catalogMarkdown, catalogModel, historyMarkdown, parseTestQuery, runDetail, runList, runMarkdown, runsMarkdown, testCatalog, testHistory } from '../../reports/src/test-catalog.js';
 import { llmsTxt } from './llms.js';
 import { openApiDocument } from './openapi.js';
 import { asProblem, problemResponse } from './problem.js';
@@ -132,8 +133,9 @@ function createProjectApplication(options) {
     });
     const outline = async () => {
         const found = await specs();
+        // Without a published spec set, the report is laid over the specs its layers recorded, as the CLI does.
         if (!found)
-            return { specs: [], sha: null, changedFiles: [], readSpec: async () => null };
+            return { specs: [...index.history.specs.entries()], sha: null, changedFiles: [], readSpec: async () => null };
         const entries = found.set.files.map(({ path: file, domain, kind, title, fingerprint }) => ({ path: file, domain, kind, title, fingerprint }));
         return { specs: entries, sha: found.set.sha, changedFiles: [], readSpec: async (file) => {
                 const entry = found.set.files.find(item => item.path === file);
@@ -251,7 +253,7 @@ function createProjectApplication(options) {
             name: 'atlas', version: options.version ?? null, role: identity?.role ?? 'read', open: auth.open,
             write: options.write, ready: index.ready, viewers: events.count, time: now(),
             backends: snapshot.backends.map(({ id, label, available }) => ({ id, label, available, write: id === options.write })),
-            ...(({ backends: _unused, ...rest }) => rest)(index.stats()), capabilities: { events: true, ingest: true, store: true, checks: true, status: true, effective: true, live: true }
+            ...(({ backends: _unused, ...rest }) => rest)(index.stats()), capabilities: { events: true, ingest: true, store: true, checks: true, status: true, effective: true, live: true, tests: true }
         });
     });
     app.get('/api/live', async (c) => c.json({ runs: await live.list() }, 200, { 'cache-control': 'no-store' }));
@@ -354,6 +356,81 @@ function createProjectApplication(options) {
             return body(c, delta.text, 'application/json', headers);
         return body(c, text, 'application/json', headers, `effective|${version}`);
     });
+    // Tests, their history and the runs that recorded them: the report as a person or an agent explores it.
+    let model = null;
+    const catalog = async () => {
+        const snapshot = index.snapshot();
+        const set = await specs();
+        const key = `${snapshot.version}|${index.history.rev}|${set?.set.id ?? ''}`;
+        if (model?.key !== key) {
+            const entries = set?.set.files.map(({ path: file, domain, kind, title }) => ({ path: file, domain, kind, title }));
+            model = { key, value: catalogModel(snapshot.layers, { history: index.history, version: createHash('sha256').update(key).digest('hex').slice(0, 20), now: now(), ...(entries ? { specs: entries } : {}) }) };
+        }
+        return model.value;
+    };
+    const wantsMarkdown = (c) => {
+        const format = c.req.query('format');
+        return format === 'markdown' || format === 'md' || (format === undefined && /\btext\/markdown\b/.test(c.req.header('accept') ?? ''));
+    };
+    const notReady = (c) => c.json({ error: 'Atlas is still reading its backends; try again in a moment.' }, 503, { 'retry-after': '1' });
+    // What was written for a version and a question is written once, however many viewers poll for it.
+    const rendered = new Map();
+    const answer = async (c, version, document, markdown, cacheKey) => {
+        const key = `${version}|${cacheKey}`;
+        const etag = `"${version}-${createHash('sha256').update(cacheKey).digest('hex').slice(0, 12)}"`;
+        const headers = { etag, 'cache-control': 'no-cache' };
+        if (c.req.header('if-none-match') === etag)
+            return new Response(null, { status: 304, headers });
+        const asMarkdown = wantsMarkdown(c);
+        let text = rendered.get(key);
+        if (text === undefined) {
+            text = asMarkdown ? markdown() : JSON.stringify(document());
+            if (rendered.size >= 32)
+                rendered.delete(rendered.keys().next().value);
+            rendered.set(key, text);
+        }
+        return body(c, text, asMarkdown ? 'text/markdown; charset=utf-8' : 'application/json', headers, key);
+    };
+    app.get('/api/reports/tests', async (c) => {
+        if (!index.ready)
+            return notReady(c);
+        const found = await catalog();
+        const query = parseTestQuery(new URL(c.req.url).searchParams);
+        const document = () => testCatalog(found, query);
+        return answer(c, found.version, document, () => catalogMarkdown(document()), `tests|${new URL(c.req.url).search}|${wantsMarkdown(c)}`);
+    });
+    app.get('/api/reports/tests/history', async (c) => {
+        if (!index.ready)
+            return notReady(c);
+        const key = c.req.query('key');
+        if (!key)
+            return problemResponse(400, 'Name the test with ?key=, a key from GET /api/reports/tests.');
+        const found = await catalog();
+        const document = testHistory(found, key);
+        if (!document)
+            return problemResponse(404, 'No test in the report has that key.');
+        return answer(c, found.version, () => document, () => historyMarkdown(document), `history|${key}|${wantsMarkdown(c)}`);
+    });
+    app.get('/api/reports/runs', async (c) => {
+        if (!index.ready)
+            return notReady(c);
+        const found = await catalog();
+        const limit = /^\d+$/.test(c.req.query('limit') ?? '') ? Number(c.req.query('limit')) : 100;
+        const document = () => runList(index.history, found.version, limit);
+        return answer(c, found.version, document, () => runsMarkdown(document()), `runs|${limit}|${wantsMarkdown(c)}`);
+    });
+    app.get('/api/reports/runs/detail', async (c) => {
+        if (!index.ready)
+            return notReady(c);
+        const key = c.req.query('key');
+        if (!key)
+            return problemResponse(400, 'Name the run with ?key=, a key from GET /api/reports/runs.');
+        const found = await catalog();
+        const document = runDetail(index.history, found.version, key);
+        if (!document)
+            return problemResponse(404, 'No run has that key.');
+        return answer(c, found.version, () => document, () => runMarkdown(document), `run|${key}|${wantsMarkdown(c)}`);
+    });
     app.route('/api/reports', layers);
     // Upload: the store protocol, and a simple JSON way in for anything that can make a request.
     app.route('/api/store', storeApi({
@@ -410,7 +487,7 @@ function createProjectApplication(options) {
         const snapshot = index.snapshot();
         const found = await outline();
         // The gate is a function of the report and the specs, so it is worked out once for each pair, however often CI asks.
-        const asked = `${snapshot.version}|${(await specs())?.set.id ?? ''}|${[...branches].sort().join(',')}|${ignoreModified}|${required.join(',')}|${requireAllSpecs}`;
+        const asked = `${snapshot.version}|${(await specs())?.set.id ?? `recorded:${index.history.specs.size}`}|${[...branches].sort().join(',')}|${ignoreModified}|${required.join(',')}|${requireAllSpecs}`;
         if (!verdicts.has(asked)) {
             if (verdicts.size >= 16)
                 verdicts.delete(verdicts.keys().next().value);
@@ -426,7 +503,8 @@ function createProjectApplication(options) {
                     if (!filtered.has(key)) {
                         if (filtered.size >= 8)
                             filtered.delete(filtered.keys().next().value);
-                        filtered.set(key, combineBackends(backends, { outline: found, include: layer => (options.include?.(layer) ?? true) && (!branches.length || (layer.branch !== null && branches.includes(layer.branch))) && (!ignoreModified || layer.freshness === undefined) }));
+                        const specSet = await specs();
+                        filtered.set(key, combineBackends(backends, { ...(specSet ? { outline: found } : {}), include: layer => (options.include?.(layer) ?? true) && (!branches.length || (layer.branch !== null && branches.includes(layer.branch))) && (!ignoreModified || layer.freshness === undefined) }));
                     }
                     report = await filtered.get(key);
                 }

package/dist/server/src/llms.js

@@ -60,6 +60,20 @@ bunx atlas report status --format json --branch main --ignore-modified   # exit
 curl ${context.open ? '' : '-H "authorization: Bearer $ATLAS_TOKEN" '}"${url}/api/status?project=$ATLAS_PROJECT"    # the same verdict; header X-Atlas-Ok: true|false
 \`\`\`
 
+## Read the tests, their history and the runs
+
+Every endpoint below answers JSON, or Markdown with \`format=markdown\`. Prefix it with \`/api/projects/<slug>\` (or add \`?project=<slug>\`) for a project; \`GET ${url}/api/projects\` lists them.
+
+\`\`\`sh
+curl "${url}/api/projects/$ATLAS_PROJECT/reports/tests?format=markdown&limit=50"                 # summary, environments, domains, failing, flaky, slowest, then the tests
+curl "${url}/api/projects/$ATLAS_PROJECT/reports/tests?status=failed,flaky&environment=desktop-web" # filter: q, status, environment, producer, domain, spec, tag, run; sort, offset, limit
+curl "${url}/api/projects/$ATLAS_PROJECT/reports/tests/history?key=<url-encoded test key>"         # one test: every recorded result, durations, branches, CI runs
+curl "${url}/api/projects/$ATLAS_PROJECT/reports/runs?format=markdown"                             # CI runs, newest first, with their results by status
+curl "${url}/api/projects/$ATLAS_PROJECT/reports/runs/detail?key=<url-encoded run key>"            # every test one run recorded
+\`\`\`
+
+A test's \`key\` is \`JSON.stringify([specPath, id])\`; its \`outcomes\` are its current results per environment and \`stats\` its pass rate, flips, flakiness and durations. The evidence of one result (attachments, steps, retries) is at \`/api/reports/evidence/detail/<backend>/<layer>?check=<id>\`, its files at \`/api/reports/layers/<layer>/blobs/<bundleKey>\`.
+
 ## Rules worth knowing
 
 - **Layered, never partitioned.** A check is identified by its \`id\` (keep it stable across runs) plus producer, kind, spec, environment and parameters. A layer that re-ran one check leaves every other check as the last layer that ran it.

package/dist/server/src/openapi.d.ts

@@ -1,5 +1,5 @@
 /** The version of the API described, `major.minor.patch`: the minor grows when an operation or field is added, the major never within `/api`. */
-export declare const API_VERSION = "1.3.0";
+export declare const API_VERSION = "1.4.0";
 /** Who may call an operation: `none` (anyone), or the least role that may (`read` < `publish` < `admin`). */
 export type Role = 'none' | 'read' | 'publish' | 'admin';
 type JsonSchema = Record<string, unknown>;

package/dist/server/src/openapi.js

@@ -14,10 +14,10 @@
  */
 import { z } from 'zod/v4';
 import { ProjectsSchema } from '../../schema/src/project.js';
-import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema } from '../../schema/src/api.js';
+import { EffectiveDeltaSchema, EffectiveEvidenceSchema, EvidencePageSchema, HealthSchema, LayerRowsSchema, CheckDetailSchema, OutlineSchema, ProblemSchema, ReadySchema, ServerInfoSchema, StoreListingSchema, StoreWriteResultSchema, ChecksResultSchema, HelloEventSchema, ReportEventSchema, PingEventSchema, TestCatalogSchema, TestHistorySchema, RunListSchema, RunDetailSchema } from '../../schema/src/api.js';
 import { LiveRunSchema, LiveRunStartSchema, LiveRunUpdateSchema, ServerEditableSettingsSchema, ServerSettingsSnapshotSchema, AtlasChangeSchema, PublishChecksSchema, ReportSourcesSchema, ReportStatusSchema, RunsIndexSchema, SpecIndexSchema } from '../../schema/src/index.js';
 /** The version of the API described, `major.minor.patch`: the minor grows when an operation or field is added, the major never within `/api`. */
-export const API_VERSION = '1.3.0';
+export const API_VERSION = '1.4.0';
 /** The JSON Schema of a Zod schema, as OpenAPI 3.1 embeds it. `output` for what the server sends, `input` for what it accepts. */
 function schemaOf(schema, io = 'output') {
     const { $schema: _dialect, ...json } = z.toJSONSchema(schema, { target: 'draft-2020-12', unrepresentable: 'any', io });
@@ -35,6 +35,7 @@ const COMPONENTS = {
     PublishChecks: [PublishChecksSchema.partial({ recordedAtMs: true }), 'input'], ChecksResult: [ChecksResultSchema, 'output'],
     StoreListing: [StoreListingSchema, 'output'], StoreWriteResult: [StoreWriteResultSchema, 'output'],
     Outline: [OutlineSchema, 'output'], EvidencePage: [EvidencePageSchema, 'output'], LayerRows: [LayerRowsSchema, 'output'], CheckDetail: [CheckDetailSchema, 'output'],
+    TestCatalog: [TestCatalogSchema, 'output'], TestHistory: [TestHistorySchema, 'output'], RunList: [RunListSchema, 'output'], RunDetail: [RunDetailSchema, 'output'],
     SpecIndex: [SpecIndexSchema, 'output'], ReportSources: [ReportSourcesSchema, 'output'], RunsIndex: [RunsIndexSchema, 'output'],
     RunEvent: [LiveRunSchema, 'output'], HelloEvent: [HelloEventSchema, 'output'], ReportEvent: [ReportEventSchema, 'output'], AtlasChangeEvent: [AtlasChangeSchema, 'output'], PingEvent: [PingEventSchema, 'output']
 };
@@ -252,10 +253,66 @@ const BASE_OPERATIONS = [
         parameters: [KEY],
         responses: { '204': { description: 'Removed (or it was not there).' }, '401': UNAUTHORIZED, '403': problem('Not a scratch object, or the token may not.') }
     },
+    {
+        route: 'GET /api/reports/tests', path: '/api/reports/tests', operationId: 'getTests', tag: 'Report', role: 'read',
+        summary: 'Every test, with insights, facets and history statistics',
+        description: [
+            'The report as a list of tests, for exploring it or for an agent to read in one request. A test is a check identity (its spec path and id) across producers and environments; `outcomes` holds its current result on each environment, and `stats` how it went over its recorded history (pass rate, flips, flaky, durations avg/p50/p95, runs, branches).',
+            '',
+            '`summary` and `facets` cover every test (counts by status, by environment, by producer and by domain, the slowest, flakiest and failing tests); `tests` is the page the query matched. Without a published spec set, specs come from the `specs[]` the layers recorded.',
+            '',
+            'Send `format=markdown` (or `Accept: text/markdown`) for the same as a Markdown report. The current status of a test is always the report\'s winner; history never changes it.'
+        ].join('\n'),
+        parameters: [
+            { name: 'q', in: 'query', description: 'Words that must all appear in the title, id, spec, domain, tags, labels, environments or producers. Case does not matter.', schema: str, example: 'checkout card' },
+            { name: 'status', in: 'query', description: 'Current status, or `flaky`. Repeatable or comma-separated.', schema: str, example: 'failed,flaky' },
+            { name: 'environment', in: 'query', description: 'Only tests with a result on this environment. Repeatable or comma-separated.', schema: str, example: 'desktop-web' },
+            { name: 'producer', in: 'query', description: 'Only tests from this producer. Repeatable or comma-separated.', schema: str },
+            { name: 'domain', in: 'query', description: 'Only tests whose spec is in this domain (`(no spec)` for none). Repeatable or comma-separated.', schema: str },
+            { name: 'spec', in: 'query', description: 'Only tests of this spec path. Repeatable or comma-separated.', schema: str, example: 'specs/checkout/pay.feature' },
+            { name: 'tag', in: 'query', description: 'Only tests with this tag. Repeatable or comma-separated.', schema: str },
+            { name: 'run', in: 'query', description: 'Only tests recorded in this run (a `key` from `/api/reports/runs`).', schema: str },
+            { name: 'sort', in: 'query', description: 'The order: `spec` (default: domain, spec, title), `title`, `recent`, `slowest`, `failures`, `flaky` or `runs`.', schema: { type: 'string', enum: ['spec', 'title', 'recent', 'slowest', 'failures', 'flaky', 'runs'] } },
+            { name: 'offset', in: 'query', description: 'Skip this many matching tests.', schema: { type: 'integer', minimum: 0 } },
+            { name: 'limit', in: 'query', description: 'At most this many tests (default 500, at most 20000).', schema: { type: 'integer', minimum: 0, maximum: 20000 } },
+            { name: 'format', in: 'query', description: '`markdown` for a Markdown report instead of JSON.', schema: { type: 'string', enum: ['json', 'markdown'] } }
+        ],
+        responses: { '200': { ...json('The catalog.', 'TestCatalog'), headers: { ETag: { description: 'Changes with the report, its history and the query.', schema: str } } }, '304': { description: 'Unchanged since the `If-None-Match` ETag.' }, '401': UNAUTHORIZED, '503': NOT_READY }
+    },
+    {
+        route: 'GET /api/reports/tests/history', path: '/api/reports/tests/history', operationId: 'getTestHistory', tag: 'Report', role: 'read',
+        summary: 'One test and every result recorded for it',
+        description: 'The test (as `/api/reports/tests` lists it) and up to 100 recorded results, newest first: status, duration, environment, producer, branch, commit, CI run, layer and the first 500 characters of the detail. Open a result\'s evidence (attachments, steps, retries) with `/api/reports/evidence/detail/{backend}/{id}?check=<id>`. Send `format=markdown` for Markdown.',
+        parameters: [
+            { name: 'key', in: 'query', required: true, description: 'The test\'s `key` from `/api/reports/tests`: `JSON.stringify([specPath, id])`, URL-encoded.', schema: str, example: '["specs/checkout/pay.feature","Pay with a card"]' },
+            { name: 'format', in: 'query', description: '`markdown` for Markdown instead of JSON.', schema: { type: 'string', enum: ['json', 'markdown'] } }
+        ],
+        responses: { '200': json('The test and its history.', 'TestHistory'), '304': { description: 'Unchanged since the `If-None-Match` ETag.' }, '400': problem('No `key`.'), '401': UNAUTHORIZED, '404': problem('No test in the report has that key.'), '503': NOT_READY }
+    },
+    {
+        route: 'GET /api/reports/runs', path: '/api/reports/runs', operationId: 'getReportRuns', tag: 'Report', role: 'read',
+        summary: 'The runs that recorded the report',
+        description: 'Every run, newest first: layers grouped by their CI run URL (else branch and commit), with their environments, producers, how many tests they recorded, their results by status, the time they spanned and up to twenty failures. Send `format=markdown` for Markdown.',
+        parameters: [
+            { name: 'limit', in: 'query', description: 'At most this many runs (default 100).', schema: { type: 'integer', minimum: 0 } },
+            { name: 'format', in: 'query', description: '`markdown` for Markdown instead of JSON.', schema: { type: 'string', enum: ['json', 'markdown'] } }
+        ],
+        responses: { '200': json('The runs.', 'RunList'), '304': { description: 'Unchanged since the `If-None-Match` ETag.' }, '401': UNAUTHORIZED, '503': NOT_READY }
+    },
+    {
+        route: 'GET /api/reports/runs/detail', path: '/api/reports/runs/detail', operationId: 'getReportRun', tag: 'Report', role: 'read',
+        summary: 'Every test one run recorded',
+        description: 'One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.',
+        parameters: [
+            { name: 'key', in: 'query', required: true, description: 'The run\'s `key` from `/api/reports/runs`, URL-encoded.', schema: str },
+            { name: 'format', in: 'query', description: '`markdown` for Markdown instead of JSON.', schema: { type: 'string', enum: ['json', 'markdown'] } }
+        ],
+        responses: { '200': json('The run and its results.', 'RunDetail'), '304': { description: 'Unchanged since the `If-None-Match` ETag.' }, '400': problem('No `key`.'), '401': UNAUTHORIZED, '404': problem('No run has that key.'), '503': NOT_READY }
+    },
     {
         route: 'GET /api/reports/outline', path: '/api/reports/outline', operationId: 'getOutline', tag: 'Report', role: 'read',
         summary: 'The specs a report is laid over',
-        description: 'The specs of the newest committed spec set (of `main`, else the newest), so the report needs no checkout. A spec here with no result shows as having none.',
+        description: 'The specs of the newest committed spec set (of `main`, else the newest), so the report needs no checkout. Without a spec set, the specs the layers recorded (`specs[]`), newest per path. A spec here with no result shows as having none.',
         responses: { '200': json('The outline.', 'Outline'), '401': UNAUTHORIZED }
     },
     {

package/docs/agents.md

@@ -111,6 +111,7 @@ The complete public export map is generated from the package manifest (wildcards
 @crvouga/atlas/codecept
 @crvouga/atlas/jest
 @crvouga/atlas/node-test
+@crvouga/atlas/playwright-reporter
 ```
 <!-- /generated:public-exports -->
 

package/docs/integrating.md

@@ -221,6 +221,7 @@ bunx atlas report publish --producer e2e --junit out.xml --attach ci.log --attac
 Files are stored in the layer by content, shown by what they are (pictures, videos, page snapshots, text) and
 offered for download otherwise. [Evidence](extending.md) is the full model, and why a new kind of evidence never
 breaks anything.
+[Send rich evidence](rich-evidence.md) lists what to send and what the viewer does with it, and covers the Playwright Test reporter.
 
 ### Statecharts
 

package/docs/reference/http-api.md

@@ -450,11 +450,143 @@ Scoped to one project. The same project may be selected on the unprefixed API us
 
 Responses: `204` Removed (or it was not there).; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `403` Not a scratch object, or the token may not.
 
+### Every test, with insights, facets and history statistics
+
+`GET /api/reports/tests` · role: read
+
+The report as a list of tests, for exploring it or for an agent to read in one request. A test is a check identity (its spec path and id) across producers and environments; `outcomes` holds its current result on each environment, and `stats` how it went over its recorded history (pass rate, flips, flaky, durations avg/p50/p95, runs, branches).
+
+`summary` and `facets` cover every test (counts by status, by environment, by producer and by domain, the slowest, flakiest and failing tests); `tests` is the page the query matched. Without a published spec set, specs come from the `specs[]` the layers recorded.
+
+Send `format=markdown` (or `Accept: text/markdown`) for the same as a Markdown report. The current status of a test is always the report's winner; history never changes it.
+
+- `q` (query): Words that must all appear in the title, id, spec, domain, tags, labels, environments or producers. Case does not matter.
+- `status` (query): Current status, or `flaky`. Repeatable or comma-separated.
+- `environment` (query): Only tests with a result on this environment. Repeatable or comma-separated.
+- `producer` (query): Only tests from this producer. Repeatable or comma-separated.
+- `domain` (query): Only tests whose spec is in this domain (`(no spec)` for none). Repeatable or comma-separated.
+- `spec` (query): Only tests of this spec path. Repeatable or comma-separated.
+- `tag` (query): Only tests with this tag. Repeatable or comma-separated.
+- `run` (query): Only tests recorded in this run (a `key` from `/api/reports/runs`).
+- `sort` (query): The order: `spec` (default: domain, spec, title), `title`, `recent`, `slowest`, `failures`, `flaky` or `runs`.
+- `offset` (query): Skip this many matching tests.
+- `limit` (query): At most this many tests (default 500, at most 20000).
+- `format` (query): `markdown` for a Markdown report instead of JSON.
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The catalog.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### Every test, with insights, facets and history statistics
+
+`GET /api/projects/{project}/reports/tests` · role: read
+
+The report as a list of tests, for exploring it or for an agent to read in one request. A test is a check identity (its spec path and id) across producers and environments; `outcomes` holds its current result on each environment, and `stats` how it went over its recorded history (pass rate, flips, flaky, durations avg/p50/p95, runs, branches).
+
+`summary` and `facets` cover every test (counts by status, by environment, by producer and by domain, the slowest, flakiest and failing tests); `tests` is the page the query matched. Without a published spec set, specs come from the `specs[]` the layers recorded.
+
+Send `format=markdown` (or `Accept: text/markdown`) for the same as a Markdown report. The current status of a test is always the report's winner; history never changes it.
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+- `q` (query): Words that must all appear in the title, id, spec, domain, tags, labels, environments or producers. Case does not matter.
+- `status` (query): Current status, or `flaky`. Repeatable or comma-separated.
+- `environment` (query): Only tests with a result on this environment. Repeatable or comma-separated.
+- `producer` (query): Only tests from this producer. Repeatable or comma-separated.
+- `domain` (query): Only tests whose spec is in this domain (`(no spec)` for none). Repeatable or comma-separated.
+- `spec` (query): Only tests of this spec path. Repeatable or comma-separated.
+- `tag` (query): Only tests with this tag. Repeatable or comma-separated.
+- `run` (query): Only tests recorded in this run (a `key` from `/api/reports/runs`).
+- `sort` (query): The order: `spec` (default: domain, spec, title), `title`, `recent`, `slowest`, `failures`, `flaky` or `runs`.
+- `offset` (query): Skip this many matching tests.
+- `limit` (query): At most this many tests (default 500, at most 20000).
+- `format` (query): `markdown` for a Markdown report instead of JSON.
+
+Responses: `200` The catalog.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### One test and every result recorded for it
+
+`GET /api/reports/tests/history` · role: read
+
+The test (as `/api/reports/tests` lists it) and up to 100 recorded results, newest first: status, duration, environment, producer, branch, commit, CI run, layer and the first 500 characters of the detail. Open a result's evidence (attachments, steps, retries) with `/api/reports/evidence/detail/{backend}/{id}?check=<id>`. Send `format=markdown` for Markdown.
+
+- `key` (query, required): The test's `key` from `/api/reports/tests`: `JSON.stringify([specPath, id])`, URL-encoded.
+- `format` (query): `markdown` for Markdown instead of JSON.
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The test and its history.; `304` Unchanged since the `If-None-Match` ETag.; `400` No `key`.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `404` No test in the report has that key.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### One test and every result recorded for it
+
+`GET /api/projects/{project}/reports/tests/history` · role: read
+
+The test (as `/api/reports/tests` lists it) and up to 100 recorded results, newest first: status, duration, environment, producer, branch, commit, CI run, layer and the first 500 characters of the detail. Open a result's evidence (attachments, steps, retries) with `/api/reports/evidence/detail/{backend}/{id}?check=<id>`. Send `format=markdown` for Markdown.
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+- `key` (query, required): The test's `key` from `/api/reports/tests`: `JSON.stringify([specPath, id])`, URL-encoded.
+- `format` (query): `markdown` for Markdown instead of JSON.
+
+Responses: `200` The test and its history.; `304` Unchanged since the `If-None-Match` ETag.; `400` No `key`.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `404` No test in the report has that key.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### The runs that recorded the report
+
+`GET /api/reports/runs` · role: read
+
+Every run, newest first: layers grouped by their CI run URL (else branch and commit), with their environments, producers, how many tests they recorded, their results by status, the time they spanned and up to twenty failures. Send `format=markdown` for Markdown.
+
+- `limit` (query): At most this many runs (default 100).
+- `format` (query): `markdown` for Markdown instead of JSON.
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The runs.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### The runs that recorded the report
+
+`GET /api/projects/{project}/reports/runs` · role: read
+
+Every run, newest first: layers grouped by their CI run URL (else branch and commit), with their environments, producers, how many tests they recorded, their results by status, the time they spanned and up to twenty failures. Send `format=markdown` for Markdown.
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+- `limit` (query): At most this many runs (default 100).
+- `format` (query): `markdown` for Markdown instead of JSON.
+
+Responses: `200` The runs.; `304` Unchanged since the `If-None-Match` ETag.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### Every test one run recorded
+
+`GET /api/reports/runs/detail` · role: read
+
+One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.
+
+- `key` (query, required): The run's `key` from `/api/reports/runs`, URL-encoded.
+- `format` (query): `markdown` for Markdown instead of JSON.
+- `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+
+Responses: `200` The run and its results.; `304` Unchanged since the `If-None-Match` ETag.; `400` No `key`.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `404` No run has that key.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
+### Every test one run recorded
+
+`GET /api/projects/{project}/reports/runs/detail` · role: read
+
+One run and its last result for every test, environment and producer it recorded, failures first. Send `format=markdown` for Markdown.
+
+Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.
+
+- `project` (path, required): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
+- `key` (query, required): The run's `key` from `/api/reports/runs`, URL-encoded.
+- `format` (query): `markdown` for Markdown instead of JSON.
+
+Responses: `200` The run and its results.; `304` Unchanged since the `If-None-Match` ETag.; `400` No `key`.; `401` No token, or an unknown one. Send `Authorization: Bearer <token>`.; `404` No run has that key.; `503` The server is still reading its backends. Retry after the number of seconds in `Retry-After`.
+
 ### The specs a report is laid over
 
 `GET /api/reports/outline` · role: read
 
-The specs of the newest committed spec set (of `main`, else the newest), so the report needs no checkout. A spec here with no result shows as having none.
+The specs of the newest committed spec set (of `main`, else the newest), so the report needs no checkout. Without a spec set, the specs the layers recorded (`specs[]`), newest per path. A spec here with no result shows as having none.
 
 - `project` (query): Project slug. Alternatively send X-Atlas-Project or use the project-prefixed route. Omit for the default project. Conflicting selectors are refused.
 
@@ -464,7 +596,7 @@ Responses: `200` The outline.; `401` No token, or an unknown one. Send `Authoriz
 
 `GET /api/projects/{project}/reports/outline` · role: read
 
-The specs of the newest committed spec set (of `main`, else the newest), so the report needs no checkout. A spec here with no result shows as having none.
+The specs of the newest committed spec set (of `main`, else the newest), so the report needs no checkout. Without a spec set, the specs the layers recorded (`specs[]`), newest per path. A spec here with no result shows as having none.
 
 Scoped to one project. The same project may be selected on the unprefixed API using ?project= or X-Atlas-Project. Unknown projects return 404 on reads and are created by an authenticated upload.