heliohq/ship / skills/e2e
e2e
VerifiedAdd durable end-to-end tests for user/API-visible behavior. Detect or scaffold the E2E framework, write tests, run the app, and store evidence. Use for E2E, Playwright/Cypress, regression tests, or quality gates. Not exploratory QA.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.0 KB |
| references/authoring.md | markdown | 3.3 KB |
| references/frameworks.md | markdown | 5.6 KB |
| references/scaffolding.md | markdown | 5.3 KB |
references/authoring.md
View on GitHub# Writing E2E Tests — Ship Calibration
This file calibrates E2E authoring to ship's conventions. Generic E2E
wisdom (selector hierarchy, auto-wait, test independence, API-arrange +
UI-act, parallelization) is assumed — this file captures only the
opinionated rules that keep multiple runs converging on the same style
and the same scope.
## The one rule
Assert on what a user or external caller observes. Not the DOM tree, not
internal state, not the count of API calls. A test is a specification of
externally visible behavior — anything else fights future refactors.
## Scope (the discipline that matters most)
For each change, cover exactly these three things:
1. **Every acceptance criterion from the spec** — one test per criterion,
or one `describe` with 2-3 cases if the criterion has meaningful
variations (logged-in vs guest, admin vs user). Not 10 cases.
2. **Regression sentinels for flows the diff clearly touched** —
modified checkout? A checkout happy-path test must exist after this
phase. Modified an API endpoint? That endpoint needs a test.
3. **One negative test per new feature** — a predictable error path
(bad input, missing auth). Just one — proves error handling isn't
silently broken, without polluting the suite.
**Do NOT cover:**
- Edge cases that belong in unit tests (algorithm branches, validation
rules, boundary conditions)
- Styling details (unless visual regression is already set up)
- Third-party service internals (stub at the boundary)
- Flows the diff didn't touch
If you're writing more than ~5 tests for a single spec, stop — you're
drifting into unit-test territory, which is cheaper and faster there.
## Selectors — quick reference
Order of preference: **role + accessible name** → **`data-testid`** →
**label / text** → **CSS / XPath** (last resort, isolate in a
page-object). Add `data-testid` to the component if it's missing rather
than resorting to CSS.
## Flake policy (non-negotiable)
- **A test that only passes on retry is NOT passing.** Fix the root
cause. "It's just flaky" is never the verdict.
- **Never use fixed `sleep` / `waitForTimeout` to stabilize an
assertion.** Use framework auto-wait or wait on a user-visible signal
(toast, heading, role appearing). Fixed waits are bug bait — too short
fails under load, too long wastes CI.
- **After one failed retry, decide within seconds**:
- *Real assertion mismatch* → report FAIL, do NOT weaken the assertion
to make it green. The e2e_fix loop exists for exactly this case.
- *Selector/timing issue* → fix the test, rerun up to 3 times, then
stop. A test that needs 4 retries to pass is not a test.
## Assertions — calibration
Prefer **a few strong assertions** over many weak ones. "Order
confirmation shows order ID and total" is one strong test. Asserting on
every piece of text on the page is brittle noise. Avoid whole-page
snapshots — they're always regret in 3 months.
## File placement
Match the repo's existing convention if one exists. Otherwise:
| Framework | Default dir |
|---|---|
| Playwright, pytest-playwright | `tests/e2e/` |
| Cypress | `cypress/e2e/` |
| Capybara (RSpec) | `spec/system/` |
Keep fixtures and page-objects light — only extract when you'd otherwise
repeat the same 5-line block in 3+ tests. Premature abstraction hurts
here as much as in production code.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |