From 047c95f56c86c0d1da18226cf14131131cfd90d8 Mon Sep 17 00:00:00 2001 From: Ali Al Dallal Date: Mon, 17 Aug 2026 22:00:10 -0400 Subject: [PATCH] docs(rules): e2e server-isolation decided at spec-writing time; UI changes ship with a reviewed screenshot Both rules from the same day's failure classes: cohabitation/order dependence bit twice (atlas session bleed, guardrail file-order history), and two pipeline-green visual defects were caught only by eyes (selection invisibility, sticky ring). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01FW5GkkAG8du7tNdYLk2zSd --- .claude/rules/testing.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/.claude/rules/testing.md b/.claude/rules/testing.md index e4faaf31..6f1a8ab7 100644 --- a/.claude/rules/testing.md +++ b/.claude/rules/testing.md @@ -242,3 +242,30 @@ folklore in agent-brief prose. The standing rules: code-coverage collection (heavy, low signal over per-test assertions); octocov-style coverage actions (a 15-line floor script suffices; no new CI dependency). + +## Shared-pool vs dedicated e2e servers — declare it up front + +A spec whose assertions read GLOBAL app state that other tests can +write — queue/filter contents, review history, session state, exact +counts over seeded collections — runs on a DEDICATED server pair +(the guardrail-authoring/guardrail-review pattern: per-test spawn, +own port constants in fixtures/server.ts with a reasoning comment). +The shared worker pool is for specs whose assertions are scoped to +entities they create and delete themselves. This is decided when the +spec is WRITTEN, named in its header comment — not discovered as a +CI-only cohabitation flake later (the class that bit twice on +2026-08-17: atlas session bleed, then guardrail's filter dropdown +depending on file-order history). Corollary: no test may depend on +state left by an EARLIER test, same file included — a test that +needs history seeds it inline. + +## UI changes ship with a reviewed screenshot + +Every UI-touching change gets a screenshot of the changed state +(the builder takes it; server-mode + Playwright is enough) reviewed +against the design contract BEFORE the PR opens — assertions prove +elements exist, the screenshot is where "green but visually wrong" +gets caught (the selection-invisibility and sticky-ring classes: +both pipeline-green, both caught by eyes). This extends the +existing "restate the task, not the elements" rule with a concrete +artifact; it replaces nothing.