# Results and evidence

## Run outcomes

| Status | Meaning |
| --- | --- |
| `passed` | Every assertion held |
| `failed` | The check ran and an assertion failed: the product did not behave as expected |
| `error` | The check could not complete: DNS, connection, timeout, a broken test or incomplete coverage |
| `missed` | A scheduled run or heartbeat did not happen in time |

After `failureThreshold` consecutive failures or errors (1 to 10, default 2) an incident opens and your alert channels are notified; the next pass resolves it. Manual runs do not enable the schedule. A test with no tests or only skipped tests cannot pass.

## Read a run

```sh
waitcher monitor get --id MONITOR_ID       # definition and recent results
waitcher run start --id MONITOR_ID --wait  # one manual run; does not enable the schedule
waitcher run status --id RUN_ID
waitcher run trace --id RUN_ID             # what the run did
waitcher run wait --id RUN_ID --timeout 60
```

`run status` returns the status, message, logs, the run's frozen definition and `artifacts` (the evidence paths available for download). A wait that times out (exit 5) does not cancel the run; check `run status` later.

```sh
waitcher artifact get --id RUN_ID --path PATH --file ./private/OUTPUT
```

Downloads verify size and SHA-256 and never overwrite a file. Browser runs keep screenshots, logs and Markdown traces.

## What the run did

The execution report in the web app and `waitcher run trace` show the same trace, per monitor type:

| Type | Trace |
| --- | --- |
| HTTP | Every hop, redirects included: method, URL, status, DNS / connect / TLS / first byte / total time, selected response headers and the first 2 KB of a text body |
| Certificate | Address, TLS protocol and cipher, verification result, hostname match, validity dates and the presented chain |
| Browser | Each test's steps with durations, the failed assertion (locator, expected, observed, script line), console and network lines the app logged, screenshots, and the framework trace page or video when the run kept one |
| API | Each test's result and failed assertion, and every `fetch` call the test made: method, URL, status and duration |

Query values in URLs are replaced with `…`. Cookies, credentials, request headers and request bodies are never kept; header values of authenticated requests and their bodies are not recorded either. A trace is evidence like the files above and expires with them. Runs from before traces existed show "No trace was recorded".

Output is what the check printed. Browser and API runs are often silent, because the framework reports through the trace rather than the console; the report then says "No output captured". Anything your test logs with `console.log` appears there.

## Read a monitor's definition

Open a monitor and choose **View definition** to see its effective configuration and, for browser and API monitors, the script. Monitors deployed from `waitcher.json` cannot be edited in the web app, but their definition is readable here, with the repository entry file (for example `tests/klondike.e2e.ts`) and the deploy that set it. Header values and request bodies are hidden; secrets appear by `CHECK_*` name only. From the CLI, `waitcher monitor get --id ID` returns the same definition, and its `source.entry` names the file.

Overviews: `waitcher report get [--days 1|7|14]` and `waitcher incident list`. Projects add `waitcher project report --id ID` and `waitcher project timeline --id ID`.

## Diagnose a failure

```sh
waitcher run diagnose --id RUN_ID [--json]
waitcher run reproduce --id RUN_ID --output ./private/repro
waitcher run local --file ./private/repro/monitor.json --output ./private/repro-run
```

`run diagnose` prints a readable packet: scenario phases, the last passing run with the same verification policy, which artifacts are available and whether the run can be reproduced. `run reproduce` writes the run's frozen configuration into a new folder without executing it; run it locally with the pinned runtime (`--runtime PROJECT` if it lives elsewhere). Reproduction is a fresh run and does not replace the original evidence.

Read the evidence before changing a test. Fix mistakes in the test; never remove an assertion just to get a pass.

## Local evidence

`waitcher run local` and `deploy plan --verify` write each run to a fresh directory under `.waitcher/runs/`. Read, in order:

1. `local-run.json`: the outcome and an inventory of files with SHA-256.
2. `.e2e/summary.md`: which test failed and why.
3. `.e2e/results/*/trace.md`: step-by-step trace of a failing test.
4. `execution.log`, `report.json` and screenshots; `--video` adds a WebM recording.

`waitcher run diagnose --directory .waitcher/runs/RUN_DIR` reads local evidence without an account. The `waitcher-*.mjs` files in a run directory are runtime support, not your test.

## Retention and privacy

Evidence is kept 1 to 7 days (default 7) and reports 1 to 14 days (default 14); see `waitcher account settings`. Evidence can contain page content and anything your test prints. Keep `.waitcher/`, `.e2e/` and downloaded artifacts out of Git.