Menu
Common patterns and best-practices for writing tests (unit tests & E2E tests)
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | write-tests |
| description | Common patterns and best-practices for writing tests (unit tests & E2E tests) |
T-1 (MUST) For a simple function, colocate unit tests in *.test.ts in same directory as source file. These tests are run via Vitest.
T-2 (MUST) For any E2E or integration tests involving browser interaction, use *.spec.ts. These tests are run via Playwright and typically reside in packages/arcade/e2e.
T-3 (MUST) ALWAYS separate pure-logic unit tests from integration tests.
T-4 (SHOULD) Prefer integration tests over heavy mocking.
T-5 (SHOULD) Unit-test complex algorithms thoroughly.
T-6 (SHOULD) Test the entire structure in one assertion if possible
T-7 (MUST) Canvas-game E2E tests assert GameState through window.__bruffTestApi in ?test=1 mode by default. Use gotoTestMode(page) from packages/arcade/e2e/base-fixtures.ts and drive gameplay with dispatchInput() plus stepFrames().
T-8 (MUST) Treat rendered frames and logical ticks separately. stepFrames(n) may render and advance manual clock time; it increments frameIndex and moves enemies only when queued input creates a logical tick.
T-9 (MUST) Screenshot assertions are narrow and self-validating: static DOM regions, or canvas after a deterministic replay checkpoint followed by freezeForSnapshot(). Use await expect(locator).toHaveScreenshot("name.png"); do not call locator.screenshot() unless the test also makes an explicit assertion on the returned bytes. Update Arcade E2E screenshot baselines with pnpm run --filter @bruff/arcade test:e2e:update-snapshots.
T-10 (MUST) Replay tests use JSON fixtures in packages/game/tests/fixtures/ and committed final-state snapshots in packages/game/tests/snapshots/; fixture parsing returns typed Result values, never throws.
T-11 (MUST) Do not leave dangling locators in tests. Every locator created in a test must be used in an assertion such as toBeVisible(), toHaveText(), toHaveScreenshot(), or an equivalent explicit expectation.
T-12 (MUST) Browser integration tests synchronize on observable UI state, not fixed sleeps. Prefer waitForElement, MutationObserver, or Playwright locator assertions that wait for the exact DOM node, text, disabled state, download side effect, or alert being asserted.
T-13 (MUST) When testing async races, checkpoint each intended state before releasing delayed work. Example: wait for the newer rendered row before resolving an older promise, then assert the stale completion did not replace it.
T-14 (MUST) Focus-preservation tests assert around the event that could steal focus. Focus the control, assert it is active, dispatch the synchronous input/change event, then assert it is still active immediately. Only await after the event when the product behavior itself is async, and then await a specific observable state.
T-15 (SHOULD) Put sophisticated browser waits in shared test helpers so callers cannot accidentally reintroduce timer-based flake patterns.
expect(result).toBe([value]); // Good
expect(result).toHaveLength(1); // Bad
expect(result[0]).toBe(value); // Bad
Write cutting-edge and modern native CSS. Apply this skill whenever writing, reviewing, or refactoring CSS for components, layouts, design systems, or theming, even if the user doesn't say "modern CSS" explicitly. Covers a self-contained design-token scale (color, size, shadow, ease, type), cascade layers (@layer), @scope for component isolation (donut scopes, :scope specificity, scoping proximity), container queries, :has(), OKLCH/color-mix, native nesting, subgrid, fluid typography via clamp(), scroll-driven animations, logical properties, and concrete native replacements for SCSS mixins, maps, and variables.
Apply this skill whenever the task involves web security: writing or auditing HTTP security headers, configuring CSP, CORS, HSTS, or Permissions-Policy, sanitising untrusted HTML (Sanitizer API / DOMPurify), implementing Trusted Types to prevent DOM-XSS, setting up the Reporting API to capture CSP/COEP/deprecation violations, hardening cookies (SameSite, HttpOnly, Secure, Partitioned), implementing WebAuthn / Credential Management, using Web Crypto for client-side cryptography, or auditing code for XSS, CSRF, clickjacking, MIME-sniffing, mixed content, or cross-origin data leakage. Triggers on keywords: XSS, CSRF, CSP, CORS, HSTS, SameSite, innerHTML, eval, Trusted Types, Sanitizer, ReportingObserver, WebAuthn, cross-origin, clickjacking, Content-Security-Policy, Referrer-Policy, Permissions-Policy, subresource integrity, cookie security, secure context, same-origin, mixed content.
Patterns for invoking the GitHub CLI (gh) from agents. Covers structured output, pagination, repo targeting, search vs list, gh api fallback.
Audit and update durable architecture guidance after a cross-layer implementation, file move, package boundary change, coverage config change, or SDTE feature. Use when agent needs to reconcile AGENTS.md, package AGENTS.md files, local .agents/skills, older specs, dynamic imports, and test or coverage configuration with the architecture that was actually implemented.
Run the Spec → Design → Tasks → Execution workflow for non-trivial work — produces /specs/<feature>/{spec,design,tasks}.md, drives atomic per-task execution, and ends with a Review phase. Invoke when starting a new package, new game system, GameState shape change, or any change touching > 3 files or crossing a layer boundary.
Best practices for building scalable plain Web Components without turning custom elements into “god objects”. Provides patterns that keep Web Components modular, reusable, maintainable, and focused on UI concerns.