developer guide

---

title: "Cypress Developer Guide" type: guide domain: testing framework: cypress tags: [cypress, cucumber, e2e, configuration, ci, lighthouse, reporting] created: 2026-07-14

Cypress Developer Guide

Environment setup, configuration, running tests, and extending the test suite.

Project structure

cypress/
├── cypress.config.ts              # Cypress configuration
├── package.json                   # Dependencies and npm scripts
├── tsconfig.json                  # TypeScript configuration
├── .env                           # Local credentials (git-ignored)
├── cypress/
│   ├── e2e/                       # Feature files (.feature)
│   ├── fixtures/                  # Static test data (empty)
│   ├── support/
│   │   ├── commands.ts            # Custom Cypress commands
│   │   ├── cypress.d.ts           # TypeScript declarations
│   │   ├── e2e.ts                 # Support entry point
│   │   ├── helpers/               # Helper modules (10 files)
│   │   └── step_definitions/
│   │       ├── hooks/             # Browser and login hooks
│   │       └── steps/             # Step definitions (8 files)
├── scripts/                       # Report generation (7 files)
└── reports/                       # Generated after run

Environment variables

Loaded via dotenv in cypress.config.ts, exposed through Cypress.env().

Variable	Description
idir_username	IDIR login username
idir_password	IDIR login password
bceid_username	BCeID login username
bceid_password	BCeID login password

Create a .env file in cypress/ (git-ignored):

idir_username=your_idir_username
idir_password=your_idir_password
bceid_username=your_bceid_username
bceid_password=your_bceid_password

In CI, use CYPRESS_ prefix with cypress-io/github-action:

env:
  CYPRESS_baseUrl: https://${{ vars.BASE_URL }}
  CYPRESS_idir_username: ${{ secrets.IDIR_USERNAME }}
  CYPRESS_idir_password: ${{ secrets.IDIR_PASSWORD }}
  CYPRESS_bceid_username: ${{ secrets.BCEID_USERNAME }}
  CYPRESS_bceid_password: ${{ secrets.BCEID_PASSWORD }}

Cypress configuration

Setting	Value	Effect
defaultCommandTimeout	10000ms	DOM element wait timeout
pageLoadTimeout	60000ms	Page load timeout
viewportWidth	1920	Screenshot and Lighthouse desktop viewport
viewportHeight	1080	Screenshot viewport
video	true	Record video per spec
trashAssetsBeforeRuns	true	Delete previous artifacts
chromeWebSecurity	false	Disable same-origin policy (required for login hooks)
includeShadowDom	false	Ignore shadow DOM elements
retries.runMode	1	Retry failed tests once in headless
retries.openMode	0	No retries in interactive mode

chromeWebSecurity: false allows visiting external domains like logontest7.gov.bc.ca during login.

Step definitions

Shared step definitions live in support/step_definitions/ with nonGlobalStepDefinitions: true in package.json. This means all step definitions are global across feature files. No need to create matching .ts files per .feature file.

File	Responsibility
steps/common.steps.ts	Navigation (I visit ...)
steps/text.steps.ts	Text assertions
steps/button.steps.ts	Button clicks
steps/input.steps.ts	Form inputs and selections
steps/a11y.steps.ts	Accessibility checks
steps/lighthouse.steps.ts	Lighthouse/performance
steps/uiux.steps.ts	UI/UX style checks
steps/designTokens.steps.ts	Design token validation
hooks/browser.hooks.ts	@chromeOnly tag guard
hooks/logins.hooks.ts	@loginAsIDIR, @loginAsBCeID session hooks

Running tests

# Interactive (Cypress UI) against localhost
npm run cy:open:local

# Headless against localhost
npm run cy:run:local

# Headless with JSON reports + summary
npm run cy:run:md:local

# Custom URL
npx cypress run --config "baseUrl=https://your-app.example.com"

Lighthouse configuration

Lighthouse runs in-process via the lighthouse npm package, connected to Chrome through the remote debugging port.

Form factor resolution

The system resolves mobile vs desktop via this fallback chain:

1. env.lighthouseFormFactor
2. env.formFactor
3. env.platform
4. env.targetPlatform
5. env.deviceType
6. Viewport width ≤ 768 → mobile, otherwise → desktop

Override via environment variables or cypress.config.ts:

env: {
  lighthouseFormFactor: "mobile",
}

Mobile emulation: 390×844 viewport, 2× device scale factor, formFactor: "mobile".

Desktop emulation: 1920×1080 viewport, 1× device scale factor, Lighthouse desktop config.

Reports are cached per URL + options within a single spec file.

Error handling and console behavior

cypress/cypress/support/e2e.ts configures two global handlers:

Uncaught exception handler: Catches all uncaught exceptions. Only ResizeObserver errors are suppressed (benign Carbon component noise). All other exceptions fail the test. To suppress a new non-critical error, add it to the filter in e2e.ts.

Console log forwarding: Intercepts console.log from the browser and forwards to the Cypress command log.

Report generation

During the test run, cy.task() calls accumulate results in Node.js arrays. The before:run hook clears stale files. The after:run hook writes JSON to reports/. Then npm run report:md runs parse-report.js to produce summary.md.

Artifact	Location	Content
Screenshots	cypress/screenshots/	Captured on failure
Videos	cypress/videos/	Recorded per spec
Mochawesome JSON	reports/mochawesome/	Test results
Accessibility JSON	reports/a11y/	axe violations
Lighthouse JSON	reports/lighthouse/	Audit scores and metrics
UI/UX JSON	reports/uiux/	Style and token violations
Summary	summary.md	Combined markdown report

Report modules

Module	Reads	Produces
mochawesomeModule.js	mochawesome JSON	Test result table, failed test list
accessibilityModule.js	a11y JSON	Violation count table, top violations
lighthouseModule.js	Lighthouse JSON	Per-URL tables with scores and failed thresholds
uiuxModule.js	UI/UX JSON	Per-scenario violation tables by taxonomy

CI integration

cat cypress/summary.md >> "$GITHUB_STEP_SUMMARY"

Test coverage

Feature file	Scenarios	Coverage
search.feature	7	Search page: text search, filters, clear, advanced search
logouts.feature	1	BCeID logout flow
reporting_unit_details.feature	11	RU details: direct nav, via search, tombstone, legacy data
sample.feature	10	Template: keyboard nav, a11y, Lighthouse, UI/UX

Uncovered: client creation/editing, waste submissions, RU creation, grade management, role management, IDIR logout.