test-style

name

test-style

description

Conventions for writing tests in silkdown so they double as documentation and produce explicit, easy-to-pinpoint failure messages. Auto-trigger when creating or editing any file matching packages/*/test/**/*.test.{ts,tsx} or e2e/**/*.spec.ts, when adding new vitest or Playwright tests, when reviewing existing tests for clarity, or when triaging a failing assertion that "doesn't tell you which thing broke". Also fires on phrases like "name this test", "test description", "split this test", "expect message", "assertion message", "expect.soft", "tests as documentation", "explicit failure", "vitest assert", "playwright test name", "what's a good test name".

Test style — silkdown

Tests in this repo are read at least as often as they are run. They serve as the executable specification for the public API: a contributor (or AI agent) should be able to grep for the behaviour they're about to change, read the matching test names, and understand both what the system promises and why. When a test fails in CI, the message must point at the specific behaviour that broke — not at "expected true to be false".

Layered on top of tdd (which covers the loop) and react-best-practices (component testing rules). When in doubt, prefer integration / "social unit" tests that mount the real EditorView over isolated mocks.

Principles

1. Test names describe behaviour, in full sentences — <does X> when <Y>. Read-aloud check: a contributor with no context can predict the assertions from the title alone. → references/naming.md
2. One behaviour per test — split compound names ("wraps and unwraps") into two tests. The cost is 5 lines; the gain is that CI tells you which half broke. → references/naming.md