Run folder and events

A run folder holds the result, events, logs and evidence from one run. Use it to investigate later or feed results into your own tools without opening a browser again.

$ npx retest inspect .retest/runs/<time>$ npx retest report .retest/runs/<time>

The first command prints the saved result; the second writes report.html. Both also work with incomplete runs when enough events remain to reconstruct a result. Debugging a failure walks through a test's timeline.

Files and folders #Link to Files and folders

The default folder is .retest/runs/<time>. Pass --output <dir> to choose another new or empty folder. Retest refuses to overwrite a folder that already holds files.

Log names include a slug and hash. A browser-only run uses logs/browser.log; configured targets use logs/browser-*.log, with extra instance suffixes for browser pools. App-server logs use logs/app-*.log. Read paths from records instead of reconstructing filenames.

The last-run selection record is outside this folder, at .retest/last-run.json. It feeds --last-failed. A programmatic host can change its path or disable it with lastRunFile: false.

Artefact paths and retention #Link to Artefact paths and retention

Session artefact folders use an attempt id and a shortened app name with a hash. The following patterns describe files in those folders. Formats depend on what captured or encoded the media.

Failure screenshots and diagnostics use slug-based paths, while other media uses the session folders above. Follow each path stored in an event or result instead of assuming a single layout.

Artefact references are relative to the run folder and use forward slashes, so you can move the folder. Retest's artefact reader refuses invalid references, symbolic links, hard links, special files and files beyond its size limit. Screenshots are pixels and are not text-redacted.

Logs, screenshots, frames, downloads, diagnostics and reports remain. With recording.keep: 'failures', recordings of passed attempts and their recording thumbnails are removed, except recordings used by AI checks. Unreferenced partial recording files may be removed after the media process closes. Removal events record each request and its result.

Saved states contain session cookies and are deleted at cleanup. SIGKILL can leave them behind because cleanup cannot run. Recordings and evidence describes capture policy and retention in more detail.

Event envelope and identity #Link to Event envelope and identity

Every event has the following envelope. Event-specific fields then describe what happened. Sequences increase within one run; elapsedMs uses the run's monotonic clock rather than wall-clock differences.

Auxiliary records use app where events use session. Observation ids start again within each attempt, so join records with the attempt and session identities too. Page and layout looks can have ids without their own observation event, so missing numbers do not imply missing records.

Run and collection events #Link to Run and collection events

Attempt and resource events #Link to Attempt and resource events

A skipped test has test.finished without test.started. Waiting for locks and resources happens before the test starts and does not consume its test budget. For programmatic runs, see Use Retest from code.

Steps, actions and checks #Link to Steps, actions and checks

navigation.cause is goto for explicit navigation methods, action for navigation attributed to dispatched input, or page otherwise. document is new or same. Navigation and action addresses omit queries and fragments; page assertions can retain the whole redacted address they compared.

Only step and assertion events originate in the test process. The parent rejudges passed locator and page assertions on its recorded look and marks them judgedBy: 'parent'. Value checks are judgedBy: 'child' because those values exist in the test process.

Evidence and media events #Link to Evidence and media events

Diagnostics artefact lines #Link to Diagnostics artefact lines

Diagnostics artefacts are separate JSON lines files. Their line types are not RetestEvent types. They begin with capture.started, end with capture.finished and contain the record types below. Their identities name the test, attempt, app and session.

Capture records include their scope and completeness. Retest records no network headers or bodies. See Console and network for engine coverage and Results and exit codes for capture states.

Read and validate a folder #Link to Read and validate a folder

readRunFolder validates saved results and events and returns { source, result, events, warnings }. It reconstructs a missing result from events and marks it incomplete. Invalid folders throw RunFolderReadError.

import { readRunFolder } from '@rehearsal-labs/retest/runner'const folder = readRunFolder('.retest/runs/saved-run')const failedActions = folder.events.filter(event => event.type === 'action.failed')console.log(folder.result.exitCode, failedActions.length)console.log(folder.warnings)

Replace the example path with your saved folder. If the last event line was cut off during writing, the reader leaves it out and adds a warning. Invalid earlier lines, mixed run ids or non-increasing sequences make the event log unreadable. With a valid result.json, a damaged event log becomes a warning and the result remains readable.

The protocol export supplies retestEventSchema, runResultSchema, eventSchemaUrl and resultSchemaUrl. Installed JSON Schemas are dist/schemas/event-v1.schema.json and dist/schemas/result-v1.schema.json. Use a reader at least as new as the Retest version that wrote the folder. Version 1 rejects unknown fields, so an older reader may refuse newer records.

A host running code it does not control should take authoritative results from runFiles and events from its reporter. The test process can write to the run folder, so those files are saved copies rather than a trust boundary. Use Retest from code describes host isolation and required checks.

Next steps #Link to Next steps

• Results and exit codesInterpret statuses, failures and completeness.
• Recordings and evidenceConfigure capture, pixel rules and retention.
• Use Retest from codeConsume live results and events in your own host.