From feeb6a4fce60e76d49ce01c5e777b28019a88c26 Mon Sep 17 00:00:00 2001 From: garrytan Date: Sat, 31 Oct 2026 19:46:57 +0000 Subject: [PATCH] docs(pregate): Playwright missing-browsers exception and literals continuation rule Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- changelog.d/gsta-212-pregate-runners.md | 4 ++-- docs/pregate.md | 12 ++++++++---- docs/troubleshooting.md | 5 ++++- 3 files changed, 14 insertions(+), 7 deletions(-) diff --git a/changelog.d/gsta-212-pregate-runners.md b/changelog.d/gsta-212-pregate-runners.md index 3007ad7d4..ef15833d0 100644 --- a/changelog.d/gsta-212-pregate-runners.md +++ b/changelog.d/gsta-212-pregate-runners.md @@ -2,9 +2,9 @@ ### Fixed - **Missing pytest is the machine's gap.** Before planning `python3 -m pytest`, `lanes` asks that python3 whether it can import pytest (10 s probe, from the repo root). If it can't, the file is unclaimed and the lane is `PREGATE_ENVIRONMENT` (missing-binary, `pytest` or `python3`): "install pytest on this machine and rerun, or run the lane remotely; the diff is not at fault". -- **Playwright specs run under Playwright.** A JS/TS test file that imports `@playwright/test` at the start of a line runs as ` playwright test --reporter=list` from its nearest package. Other tests keep their runner. A declared `runner` still takes every file. Playwright's summary is read count line by count line: failed and interrupted count as failed, flaky and passed as passed, skipped as not run. A run where every test fails and Playwright says its browser is not installed is `PREGATE_ENVIRONMENT` naming `npx playwright install`. +- **Playwright specs run under Playwright.** A JS/TS test file that imports `@playwright/test` at the start of a line runs as ` playwright test --reporter=list` from its nearest package. Other tests keep their runner. A declared `runner` still takes every file. Playwright's summary is read count line by count line. Failed and interrupted count as failed, flaky and passed as passed, and skipped as not run. A run where every test fails and Playwright says its browser is not installed is `PREGATE_ENVIRONMENT` naming `npx playwright install`. - **Mixed-language root tests each get a runner.** A repo's bun, vitest or jest now claims only JS/TS files. When no one runner fits every root test, they are split by language and each part is detected on its own. So `.mjs` with `.py` runs `node --test` and pytest, and a `.py` test in a vitest repo gets pytest instead of vitest. `gstack-pregate init` drops its "a selection mixing these languages needs runner set" note. - **`literals` binds a one-character old value to its statement.** The value counts on a line that names the constant, or on up to three lines that continue that statement, never on a comment line. Version-history rows count as before. A lowercase call-site name (`attempts`, `limit`) also needs the changed module named in the file. Values of two or more characters are unchanged. ### Changed -- **docs/pregate.md** describes the new detection and the literals binding. **docs/state-root.md** lists `pregate/runs//`. +- **docs/pregate.md** describes the new detection and the literals binding. **docs/troubleshooting.md** names the Playwright missing-browsers case under `PREGATE_ENVIRONMENT`. **docs/state-root.md** lists `pregate/runs//`. diff --git a/docs/pregate.md b/docs/pregate.md index 0ddda5c06..a01d30163 100644 --- a/docs/pregate.md +++ b/docs/pregate.md @@ -195,8 +195,8 @@ Two stages with separate clocks, both printed: lines are not recognized as history rows. A one-character old value (`2`) counts only in a statement that names the constant: on the name's line, or on up to three lines that continue it (the - line before ends with `(`, `,`, `.`, `=` or another operator, or the line - starts with `.`, `)` or `]`), never on a comment line, plus the history rows + line before ends with `(`, `[`, `{`, `,`, `.`, `=` or another operator, or the + line starts with `.`, `)`, `]`, `}` or an operator), never on a comment line, plus the history rows above. A `$2` in a shell stub, a comment, or `export default 2` in a fixture elsewhere in the file is not a consumer. A call-site name such as `attempts` or `limit` is an ordinary word, so for it the file must also name the changed @@ -834,7 +834,7 @@ failure the branch caused carries `cause: "diff"` (`PREGATE_LANE_FAILED`, | Kind | Evidence | |---|---| -| `missing-binary` | exit 127, `command not found`, a spawn `ENOENT`, a runner tool `not on PATH` (dart, flutter, cargo, a package manager) | +| `missing-binary` | exit 127, `command not found`, a spawn `ENOENT`, a runner tool `not on PATH` (dart, flutter, cargo, a package manager, `python3`, or `pytest` when python3 cannot import it), Playwright's browsers not installed | | `network` | `ENOTFOUND`, `ECONNREFUSED`, `ECONNRESET`, `ETIMEDOUT`, `EAI_AGAIN`, `Could not resolve host`, `fetch failed`, a TLS handshake or certificate failure | | `quota` | `quota`, `429 Too Many Requests`, `rate limit`, `insufficient_quota` (a vCPU quota on the remote backend) | | `disk` | `ENOSPC`, `No space left on device`, `EDQUOT` | @@ -845,7 +845,11 @@ The classifier is conservative. A local lane that exited non-zero is read from its output **only when its runner reported no test summary** (nothing ran) and the runner was not seen starting a test file; a run whose summary counts `N ran, M failed` is the diff's failure whatever its log says, so a test that -failed on `ECONNREFUSED` is still a red test. A remote gate that exited +failed on `ECONNREFUSED` is still a red test. One exception: when every +failed run is a Playwright run in which every test failed and Playwright says +its browsers are not installed, the lane is `missing-binary` with `proof: +"output"` (a partial install, where some tests pass, stays the diff's +failure). A remote gate that exited without a `PREGATE_REMOTE:` line is read from its **preamble only** (its first 40 lines, before any test output could stream): a VM refused for quota or an unreachable API there never ran the tests, so it is environment and the diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 61886e363..97f958967 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -3555,7 +3555,10 @@ and the table prints `environment: — `. A test that failed an whose log also names a connection error is **not** this code: the runner's own summary counted a failure, so it is `PREGATE_LANE_FAILED` with `cause: "diff"`; nor is a runner, guard or gate script whose own binary is present but -exits 127. `proof: "launch"` is certain (the command could not start, its +exits 127. One exception: a Playwright lane where every test failed and +Playwright says its browsers are not installed is `missing-binary` with +`proof: "output"` (`npx playwright install`); a partial install stays the +diff's failure. `proof: "launch"` is certain (the command could not start, its binary is off PATH, the runtime or a gstack tool refused); `proof: "output"` means a rule matched the command's text before any test was counted, which the diff's own output could have written, so the line says `(inferred from output)`