Cypress

Automated End-to-End User Journey Tests with Cypress

BDD-driven end-to-end tests using Cypress + Cucumber / Gherkin.

This project allows a collaborative environment where anyone — technical or not — can describe user journeys as test scenarios, and the development team will make sure they are automated.

Why do we test user journeys?

The main objective is to cover as many real-world scenarios as possible by letting anyone on the team — technical or not — describe the journeys that matter most. Different perspectives catch cases that the development team alone might overlook, and a shared, plain-English format means everyone speaks the same language when it comes to expected behavior.

How it works

Test scenarios are written in Gherkin, a plain-text format that reads like a step-by-step recipe. Each scenario lives in a .feature file and is executed automatically by Cypress. You don't need to write code — just describe what should happen, and the development team will wire up the how.

Here's a quick taste:

Feature: User Registration
  As a new user I want to register on the website so that I can access exclusive content

  @loginAsBCeID
  Scenario: Successful user registration
    Given I am on the registration page
    When I fill in the registration form with valid information
    And I click the "Register" button
    Then I should see a success message

To learn more about Cucumber, Gherkin, and BDD in general, you can enrol in a free course from Cucumber School.

Quick start

# Install dependencies
npm ci

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

# Headless mode against localhost
npm run cy:run:local

# Headless mode with mochawesome JSON output (for markdown summary)
npm run cy:run:md:local

Note

You need a .env file with login credentials before running the tests. See the Developer Guide for details.

Getting started

Pick the guide that matches your role:

Guide	Audience	Description
Writing Test Scenarios	Everyone	How to create features, scenarios, submit tests via GitHub Issues, and use authentication annotations
Step Reference	Everyone	Full list of ready-to-use step instructions — use them as-is in your scenarios
Developer Guide	Developers	Environment setup, project structure, running tests, writing step definitions, and CI configuration
UX/UI Guide	UX/UI Designers	Best practices for writing user-friendly scenarios, common pitfalls to avoid, and how to collaborate with developers
UX/UI Guide for Developers	Developers	Technical implementation details of the UI/UX quality check system
Test Rationales	Everyone	Why each test category exists — the reasoning behind navigation, accessibility, performance, and UI/UX checks

Submitting a test without coding

You can submit test scenarios directly through GitHub Issues — no coding required:

1. Go to Issues and click New issue.
2. Select the User provided automated test-case template.
3. Fill out the form following the provided instructions.

The issue will be automatically converted to a .feature file used for testing.

Test coverage

Current feature files and what they cover:

Feature file	Scenarios	What it tests
search.feature	7	Search page: basic text search, district/sampling/status filters, clear filters, advanced search with date ranges
logouts.feature	1	BCeID user logout flow (profile settings → log out)
reporting_unit_details.feature	11	RU details page: direct navigation and via search, tombstone panel (client name, number, status, district, sampling option), legacy data tag, not-found fallback
sample.feature	10	Template and examples: keyboard navigation, axe accessibility, Lighthouse thresholds, UI/UX style and token checks, contrast validation

Pages/workflows without e2e coverage: Client creation, client editing, waste submission flows, reporting unit creation, grade management, user role management, and the full logout/login cycle for IDIR users.