E2E Test Conventions
An e2e test walks a user route, sits in its feature's spec file, and is named and tagged after its use case.
Why
What the spec says and what the tests verify should be easy to check against each other.
User Routes Only
- An e2e case walks a route the user can take:
- In an app, a sign-in or a search.
- In a game, a new game or a continue.
- A developer tool, such as a debug panel or a seed endpoint, may seed the state a case starts from. Its own routes (a jump, a scenario, a reset) are never the flow under test.
- A bug only a tool can reach belongs to the tool and gets a unit test of the tool.
File And Describe
- One spec file per feature. Happy and error variants are siblings in the same file.
- Every test sits in a
describe('<Feature Name>', ...)block, so the report heading reads as the feature ("User List", "Search User") instead of the file name. The describe names the feature, never the flow.
Title
The test title is the use-case name, as its spec's heading has it: no "happy path", no flow prefix, no ID prefix.
- Happy path is the use case as-is:
Create User,Edit User,User List. - Edge cases append
- <Variant>with a spaced dash:Create User - Invalid Email,Edit User - Error,Delete User - Cancel. - The per-feature overview is
<Feature> - Overview, one per feature spec (Per-Feature Overview Test). - The cross-feature application overview, one per application, is
<Application> - Overview, the same as a feature's. The describe block and its single test carry the same name.
Tags
@<use-case-id>- the stable ID from the feature's spec.md (@create-user-1), always present on per-flow tests (Feature Spec Template).@<feature-id>-overview- the per-feature overview, no use-case number.@<application-id>-overview- the application overview, with an optional variant suffix:@<application-id>-overview-<variant>.- Both overview tags also prefix the narrated demo reel's output filename. No separate ticket tag is needed.
@demo- on the per-feature overview and the application overview.@error- only on unhappy paths. Reports color the chip red. Happy is the absence of@error, so there is no@happy.- Modular features: once an application needs module folders (
features/users/,features/authentication/), the feature takes its module as a prefix,@users-create-user-1, renaming every id and tag of the feature at once. Flat until that earns its keep. - Pattern tags - only for a cross-feature, user-perceived category that filtering benefits from:
@list- collection or list view.@empty- empty state.@detail- single-entity detail view.@edge- edge-case behavior (off the happy path, unusual state, persisted-state quirk).- New patterns stay functional and user-perceived, never a tag for a feature name (the spec file is the feature), an implementation mechanic (redirects, pickers, layouts) or a single-test category.
- No application-name tag on per-flow tests. The test-runner project name already labels every test by application.
Helpers And Shared Data
- Spec-side helpers (URL builder, named timeouts, locator factories) live next to the specs they support.
- Tests that assert on seeded data import it from the application's testing lib (Realistic Test Data Variance). Never hardcode the seeded values.
Filtering
- Pre-push runs the full affected e2e set, no filter.
- Local exploration greps by tag (
--grep "@error",--grep "@list",--grep "@create-user-1").