Cypress E2E Testing

Cypress End-to-End Testing & BDD Guide

This guide describes how to write and execute automated end-to-end (E2E) user journey tests using Cypress, Cucumber, and Gherkin BDD in cypress/.

---

Behavior-Driven Development (BDD) with Gherkin

Forest Client uses plain-text Gherkin scenarios so product owners, UX designers, and stakeholders can author verifiable user journeys that developers automate.

Example Feature File (.feature)

Feature: Individual Client Registration
  As an individual forestry applicant with a BC Services Card
  I want to submit my registration application
  So that I can obtain an official Forest Client number

  @loginAsBCSC
  Scenario: Successful submission with valid details
    Given I visit "/new-client-bcsc"
    When I fill the form as follows
      | Field name | Value                     | Type   |
      | First name | James                     | text   |
      | Last name  | Baxter                    | text   |
      | Birthdate  | 1985-05-15                | text   |
      | ID type    | Canadian driver's licence | select |
      | ID number  | 4417845                   | text   |
    And I click on the "Next" button
    Then I can read "Location & Address"

---

Community-Driven Test Cases via GitHub Issues

Anyone on the team or in the community can propose a test journey:

1. Open a new issue in GitHub Issues.
2. Select the "User provided automated test-case" template.
3. Fill out the Gherkin scenarios.
4. The issue-gherkin.yml GitHub Action automatically compiles the issue into an executable .feature file in cypress/e2e/.

---

Authentication Annotations

To simulate different user roles and identity providers without exposing secrets, prepend scenarios with role annotations:

Annotation	Description
@loginAsBCeID	Simulates an external corporate applicant logging in via BCeID Business.
@loginAsBCSC	Simulates an individual applicant logging in via BC Services Card.
@loginAsViewer	Simulates an internal staff user with read-only permissions (CLIENT_VIEWER).
@loginAsEditor	Simulates an internal staff user with edit permissions (CLIENT_EDITOR).
@loginAsAdmin	Simulates an internal staff administrator with approval authority (CLIENT_ADMIN).

---

Pre-Defined Step Reference

Step Pattern	Variables	Description	Example
I visit {input}	input: URL path	Navigates to a path	I visit "/landing"
I can read {input}	input: text	Asserts text exists on screen	I can read "Create new client"
I cannot see {input}	input: text	Asserts text is not present	I cannot see "Error"
I wait for the text {input} to appear	input: text	Waits for async element	I wait for the text "Success" to appear
I click on the {field name} button	field name: button label	Clicks named button	I click on the "Submit" button
I type {input} into the {field name} form input	input: string, field name: label	Fills text input	I type "Jane" into the "First name" form input
I select {input} from the {field name} form input	input: option, field name: label	Selects dropdown value	I select "Individual" from the "Client type" form input
I fill the form as follows	Data table (Field name, Value, Type)	Fills multiple fields	(See example above)

---

Running Cypress Tests

Navigate to cypress/:

cd cypress
npm install

# Run against local dev server (http://127.0.0.1:3000)
npm run cy:open:local    # Interactive Cypress GUI (headed)
npm run cy:run:local     # Headless test run

# Or provide a custom baseUrl
npm run cy:open -- --config baseUrl=http://localhost:3000
npm run cy:run -- --config baseUrl=http://localhost:3000