ns-e2e-tests

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