mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-06 10:59:59 +00:00
kevinveenbirkenbachandClaude Opus 4.8
f08d71534a
Add the i8* terminal aliases (make install-alias) and ai8* agent conversation shortcuts (docs/.../agents/alias.md), move skill distribution to the external INFINITO_SKILLS_REPOSITORY (make install-skills), and add make cheat, make alias and make onboard. Introduce custom.env operator overrides (win over defaults and handlers) and pin INFINITO_ALIAS_MD / INFINITO_ALIAS_REPOSITORY / INFINITO_SKILLS_REPOSITORY in default.env. Drop the in-repo skills-lock.json and its update-skills CI job. AGENTS.md instructs agents to suggest the matching cli/prompt alias when an operator writes something an alias covers. Lints enforce alias sorting, i8/ai8 prefixes, no consonant clusters, full make-target coverage, and terminal/agent shortcut non-overlap. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
73 lines
6.7 KiB
Markdown
73 lines
6.7 KiB
Markdown
# Playwright Spec Loop
|
|
|
|
This page defines the inner loop for iterating on a role-local `files/playwright/playwright.spec.js` against an already-running app stack, without redeploying between edits.
|
|
|
|
## When to use
|
|
|
|
- Use this loop when writing, debugging, or fixing a role's `files/playwright/playwright.spec.js` against an already-running stack, without redeploying between edits.
|
|
- For the role deploy that establishes the running stack use the [Compose Loop](compose.md) or [Swarm Loop](swarm.md).
|
|
|
|
## Definitions
|
|
|
|
- **Inner loop**: the edit-rerun cycle on `roles/<role>/files/playwright/playwright.spec.js` driven by `make compose-playwright role=<role>`, without a redeploy. On the act-swarm test cluster the equivalent is `make swarm-playwright role=<role>`, which first copies the working-tree's modified files into the node's frozen bootstrap copy (swarm nodes are not bind-mounted like compose).
|
|
- If any `make swarm-*` target aborts at **Set up job** with `mkdirat var/run...` on a recent Docker engine, point act at a fixed runner image per [Workflow Loop](workflow.md#act-fails-at-set-up-job-on-recent-docker).
|
|
- **Staging dir**: `TEST_E2E_PLAYWRIGHT_STAGE_BASE_DIR/<role>` (default `/tmp/test-e2e-playwright/<role>`). Contains the rendered `.env` and the Playwright project from the last deploy.
|
|
- **Baseline deploy**: a successful `make compose-deploy mode=reinstall apps=<role> full_cycle=true` run as defined in [Compose Loop](compose.md).
|
|
- **Pass**: `make compose-playwright role=<role>` exits `0` AND every MUST in [Contributing `playwright.spec.js`](../../../contributing/artefact/files/role/playwright.specs.js.md) holds for the resulting run.
|
|
|
|
## Preconditions
|
|
|
|
You MUST NOT enter the inner loop unless all of the following hold:
|
|
|
|
1. A baseline deploy for `<role>` completed successfully in the current environment.
|
|
2. The app stack for `<role>` is still running.
|
|
3. The staging dir exists and contains a non-empty `.env`.
|
|
4. `roles/<role>/files/playwright/playwright.spec.js` exists.
|
|
|
|
If any precondition fails, you MUST return to [Compose Loop](compose.md) and re-establish the baseline before continuing.
|
|
|
|
## Required reading
|
|
|
|
You MUST load the following pages before editing any file, in this order:
|
|
|
|
1. [Contributing `playwright.spec.js`](../../../contributing/artefact/files/role/playwright.specs.js.md): authoritative MUSTs for the spec content. Every MUST there is an acceptance criterion for this loop.
|
|
2. [Agent `playwright.spec.js` procedure](../../files/role/playwright.spec.js.md): how to generate or update the spec.
|
|
3. [Agent `playwright.env.j2` procedure](../../files/role/playwright.env.j2.md): rendered test input contract; required whenever the spec reads a new variable.
|
|
4. [Playwright Tests](../../../contributing/actions/testing/playwright.md): framework SPOT for runner, image pin, and recording tools.
|
|
5. [Compose Loop](compose.md): baseline deploy, Certificate Authority trust, Inspect-before-redeploy.
|
|
|
|
## Procedure
|
|
|
|
1. Verify every item in [Preconditions](#preconditions). If any fails, exit this page and follow [Compose Loop](compose.md).
|
|
2. Edit `roles/<role>/files/playwright/playwright.spec.js`. You MUST NOT hand-edit the staged copy under `TEST_E2E_PLAYWRIGHT_STAGE_BASE_DIR/<role>/tests/`; the rerunner overwrites it from the repo on each run.
|
|
3. Run `make compose-playwright role=<role> keep=true`. You MAY pass `pw="--grep <pattern>"` (or any other `npx playwright test` argument). Set `keep=true` on every inner-loop run regardless of the previous result; omit only when the user has explicitly opted out. For the full propagation chain see [Playwright Tests](../../../contributing/actions/testing/playwright.md#artefact-retention-).
|
|
4. Inspect the run output before deciding pass / fail; a green Playwright exit only proves no `expect(...)` threw, not that the contract is satisfied:
|
|
- You MUST read the per-test logs for every run: the `list` reporter output, `playwright-report/index.html`, and `test-results/<test>/error-context.md` for any failed test.
|
|
- You MUST verify schema conformance per [Contributing `playwright.spec.js`](../../../contributing/artefact/files/role/playwright.specs.js.md): persona names match `<persona>: <flow>`, every skip routes through `PERSONA_<X>_BLOCKED=true` or `<NAME>_SERVICE_ENABLED=false` (never runtime detection), and every persona reaches an authenticated surface and drives a role-specific interaction.
|
|
- With `INFINITO_PLAYWRIGHT_KEEP=true` you MUST open the trace / video of at least one passing persona per run, to confirm the journey actually fired.
|
|
5. If the script exits `0` AND the inspection passed, go to [Exit](#exit).
|
|
6. If the script exits non-zero OR the inspection surfaced a schema violation:
|
|
1. If the failure needs a change **outside** `files/playwright/playwright.spec.js` (role tasks, templates, vars, config, `javascript.js`, `style.css`, or any other role asset the deploy materializes), go to [Escape](#escape).
|
|
2. Otherwise, adjust the spec and return to step 2.
|
|
|
|
## Debugging in the nested docker daemon
|
|
|
|
To validate a hypothesis without redeploying — e.g. rerun the Playwright image with a patched env or grep — use `make compose-inner-run` (see `make help target=compose-inner-run` for `IMAGE` / `cmd` / `INFINITO_RUN_FLAGS`). You MAY hand-edit `/tmp/test-e2e-playwright/<role>/.env` for the diagnosis run only, but you MUST mirror any fix back into `roles/<role>/templates/playwright.env.j2` before the next deploy.
|
|
|
|
## Exit
|
|
|
|
You MUST NOT report the task complete until all of the following hold:
|
|
|
|
1. `make compose-playwright role=<role>` (or `make swarm-playwright role=<role>` against the swarm cluster) exited `0` on its last invocation, run WITHOUT any `pw="--grep …"` narrowing, so the entire spec (every test and every persona) ran and ALL passed. Redeploying while only a grepped subset is green and other tests are red or unrun is FORBIDDEN: the full suite MUST be green in the container first.
|
|
2. Every MUST in [Contributing `playwright.spec.js`](../../../contributing/artefact/files/role/playwright.specs.js.md) holds, including the live-application assertion and the logged-out final state.
|
|
3. A final `make compose-deploy mode=reinstall apps=<role> full_cycle=true` run has completed with the spec passing against the freshly provisioned stack. Inner-loop passes alone do NOT satisfy this gate.
|
|
|
|
## Escape
|
|
|
|
When the failure requires a change outside `files/playwright/playwright.spec.js`:
|
|
|
|
1. You MUST stop the inner loop. Inner-loop runs do NOT pick up role changes.
|
|
2. You SHOULD run `make compose-deploy mode=update apps=<role>` for the redeploy.
|
|
3. You MUST NOT fall back to `make compose-deploy mode=reinstall apps=<role> full_cycle=true` unless the reuse path has concrete evidence of a broken inventory or host stack, per [Compose Loop](compose.md).
|
|
4. After the redeploy succeeds, return to [Procedure](#procedure) step 1.
|