ns-e2e-tests — Claude Code skill: E2E testing, setup
The ns-e2e-tests skill structures Cypress end-to-end work across devices and keeps tests in a separate project. Use it when adding or refactoring specs.
Apache-2.0 151 installs updated 2026-10-24
npx skills add nextstage-brasil/skills --skill ns-e2e-tests -a claude-codeWhat ns-e2e-tests does
ns-e2e-tests manages Cypress E2E implementation in a standalone tests-e2e/ project at the repository root. It first searches for an existing cypress.config.ts; when none is found, it creates the project with its own package.json, configuration, and cypress:open and cypress:run scripts. The config reads baseUrl from CYPRESS_BASE_URL and targets cypress/e2e/**/*.cy.ts.
Commands are split into shared/, pages/, and device/, then registered from cypress/support/e2e.ts. Specs are grouped under desktop, tablet, and mobile, with viewports of 1280×720, 768×1024, and 375×812. Discovery comes first: the skill checks the app, existing commands, and Cypress environment before writing feature code. It will not move on until {e2e_root} is confirmed and cypress.config.ts can be read. Fixed cy.wait(N) calls are disallowed, while third-party HTTP/API traffic is stubbed with intercepts or fixtures by default.
What it helps with
- bootstrap Cypress in a separate
tests-e2e/project - organize commands by shared, page, and device behavior
- write E2E flows for desktop, tablet, and mobile
- move DOM logic out of Cypress specs
- stub third-party HTTP/API requests by default
Example prompts for the agent
- Create Cypress E2E coverage for this user flow, and inspect the existing
cypress.config.tsbefore writing specs. - Refactor this spec with the
ns-e2e-testsstructure: move DOM logic into commands and place the flow under the right device folder. - Set up
tests-e2e/if Cypress is missing, then add desktop and mobile scenarios for this feature.
How to install ns-e2e-tests
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-e2e-tests -a claude-code2Manually: put the files in place
~/.claude/skills/ns-e2e-tests/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ns-e2e-tests/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-e2e-tests -a codex2Manually: put the files in place
.agents/skills/ns-e2e-tests/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-e2e-tests -a cursor2Manually: put the files in place
.cursor/skills/ns-e2e-tests/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install nextstage-brasil/skills skills/ns-e2e-tests2Manually: put the files in place
.github/skills/ns-e2e-tests/SKILL.md1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-e2e-tests -a gemini-cli2Platform CLI
gemini skills install https://github.com/nextstage-brasil/skills --path skills/ns-e2e-testsManually: put the files in place
.devin/skills/ns-e2e-tests/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-e2e-tests -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ns-e2e-tests
How do I install ns-e2e-tests in Claude Code?
Run npx skills add nextstage-brasil/skills --skill ns-e2e-tests -a claude-code, then check ~/.claude/skills/ns-e2e-tests/SKILL.md.
What does ns-e2e-tests do?
It guides Cypress E2E implementation by locating or bootstrapping the test root, separating command layers, and organizing specs by device.
Which platforms support ns-e2e-tests?
The skill supports Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode.
Source text
SKILL.md · Apache-2.0
---
name: ns-e2e-tests
description: "(NS) Cypress E2E in independent tests-e2e/ at repo root (bootstrap when missing). DRY device-aware commands (shared/pages/device). Use when writing/refactoring Cypress specs, custom commands, scaffolding E2E, or implementing E2E tasks — not when planning E2E task markdown (ns-spec-driven references/e2e-test-task-generator.md). Mandatory discovery before specs."
license: Apache-2.0
metadata:
author: nextstage-brasil
version: "1.1"
---
# Create E2E Tests
Execution-phase Cypress implementation. Planning-phase: `ns-spec-driven/references/e2e-test-task-generator.md`.
## Session boot
Load `.nextstage-harness/rules/e2e-tests-rules.mdc` when present. See `references/e2e-architecture.md` for layout and bootstrap summary.
## Phase 0 — Resolve or bootstrap Cypress root
**Before any spec or command code**, locate the Cypress project or create it.
### 0.1 — Detect existing E2E (brownfield)
Search the repo in this order:
1. `tests-e2e/cypress.config.ts`
2. `testes-cypress/cypress.config.ts` (legacy name)
3. `frontend/cypress.config.ts` (legacy co-located)
Record the directory that contains `cypress.config.ts` as **`{e2e_root}`**. All paths below are relative to `{e2e_root}` unless noted.
### 0.2 — Bootstrap when nothing exists (greenfield)
If no match in 0.1, create **`tests-e2e/`** as a **standalone Node project**:
| Rule | Detail |
| ---- | ------ |
| Location | `tests-e2e/` only |
| `package.json` | **Here** — never add Cypress to `frontend/package.json` |
| Tree | Per `references/e2e-architecture.md` (config + empty `device/` folders + support imports) |
| `cypress.config.ts` | `baseUrl` from `CYPRESS_BASE_URL`; `specPattern` `cypress/e2e/**/*.cy.ts` |
| Scripts | `cypress:open`, `cypress:run` in `tests-e2e/package.json` |
Then set `{e2e_root} = tests-e2e/`.
**Forbidden on greenfield:** scaffolding under `frontend/cypress/`, copying deps into the frontend lockfile, or assuming Cypress is already installed in the app package.
### 0.3 — Post-bootstrap documentation
When `docs/context/stack-confirmed.md` or `architecture-rules.md` exists, add or update the E2E row: location `tests-e2e/`, run command `cd tests-e2e && npm run cypress:run` (or project docker equivalent).
Do not proceed to Phase 1 until `{e2e_root}` is confirmed and `cypress.config.ts` is readable.
## Phase 1 — Discovery (before feature code)
1. **App under test** — routes, forms, API usage, existing `data-testid` (read `frontend/`, not write Cypress there)
2. **Existing commands** — read all `{e2e_root}/cypress/support/commands/`; never duplicate
3. **Config** — `{e2e_root}/cypress.config.ts` baseUrl, env vars (`CYPRESS_BASE_URL`, `CYPRESS_API_URL`)
## Phase 2 — Command architecture first
```
{e2e_root}/cypress/support/commands/
shared/[feature].commands.ts # business actions — all devices
pages/[feature].commands.ts # page structure
device/mobile|tablet|desktop.commands.ts
```
| Behavior | Location |
| ------------------- | --------- |
| Same on all devices | `shared/` |
| Device-exclusive | `device/` |
| Page DOM structure | `pages/` |
Register new command files in `{e2e_root}/cypress/support/e2e.ts`.
Specs: `describe`/`it`, `cy.visit()`, commands, assertions — **no DOM logic in specs**.
## Phase 3 — Spec layout
```
{e2e_root}/cypress/e2e/device/
desktop/[feature]/[feature]-successful-flows.cy.ts
tablet/...
mobile/...
```
Viewports in `beforeEach`:
- Desktop: 1280×720
- Tablet: 768×1024
- Mobile: 375×812
Forbidden: specs directly under `cypress/e2e/` without `device/` prefix.
## Phase 4 — Implement
- Use `data-testid` from frontend task contract — do not invent
- No fixed `cy.wait(N)` — intercepts or assertion timeouts
- Third-party HTTP/API calls **stubbed by default** (intercepts/fixtures). Real third-party flows → opt-in project/tag (live tier); exclude from default `cypress:run` / CI unless human asks
- RBAC: menu hidden + direct URL denial
- Auth: login via UI or support session; tenant-aware fixtures
## Phase 5 — Run and report
From `{e2e_root}`: `npm run cypress:run` (or docker equivalent documented for the product). Report failures with `ns-investigator` if needed.
**SDD version execution:** when called under `execution-handoff.md` /
`run-implementation`, **write or refactor specs only** — do **not** run the E2E
suite. The human runs E2E at version end.
## References
| File | When |
| -------------------------------- | --------------------------------- |
| `references/e2e-architecture.md` | Root layout, bootstrap tree, rules |
| `../ns-spec-driven/references/e2e-test-task-generator.md` | Task contract source |
## Related skills
- `ns-spec-driven` `references/e2e-test-task-generator.md` — planning tasks with testid contract
- `ns-investigator` — failing E2E debugging
- `ns-gitlab-ci-generator` — CI `cd tests-e2e` and change paths
© nextstage-brasil · Apache-2.0 · nextstage-brasil/skills