Cypress Step Reference

Cypress Step Reference

This page lists every pre-defined step instruction available for writing Gherkin test scenarios in the project. Steps are grouped by category for clarity. Use these steps as-is (case sensitive, except for variable placeholders in quotes).

Variables

A variable is a piece of information passed into a step. Always wrap variables in double quotes (").

Type	Purpose	Examples
Input	The actual data you want to select or insert	"James", "/landing"
Field name	Identifies a field in the form by its label	"First name", "Client type"

Field name variables must match the exact name and casing shown on the form.

Note: Steps can be used with any Gherkin keyword: Given, When, Then, And, or But.

---

Step Categories

Navigation

Step	Variables	Description	Example
I visit {input}	input — the URL path	Navigate to a specific URL path	I visit "/landing"

Assertions

Step	Variables	Description	Example
I can read {input}	input — text on the screen	Assert that a specific text is visible on the screen	I can read "Create new client"
I cannot see {input}	input — content that should be absent	Assert that a specific text or component is not on the screen	I cannot see "Error"
I wait for the text {input} to appear	input — text to wait for	Wait for a specific text to become visible	I wait for the text "Success" to appear
I wait for the text {input} to appear after {input}	input — text to wait for, input — intercepted request name	Wait for a request to complete, then wait for text to appear	I wait for the text "Success" to appear after "submit"

Buttons

Step	Variables	Description	Example
I click on the {field name} button	field name — text/name of the button	Find and click a button	I click on the "Next" button
I search	—	Click the search button and wait for results to load	I search

Button resolution: The findButton helper tries these selectors in order: [data-testid="X"], button[aria-label="X"], button:contains("X"), input[type="submit"][value="X"], a:contains("X"), a[aria-label="X"]. If none match, it checks for Carbon icon-only buttons via .cds--tooltip-content and aria-labelledby. As a last resort, it falls back to @testing-library findByRole("button") or findByRole("link"). If the element hasn't rendered yet, it retries up to 3 times with 100ms delays.

Inputs

Step	Variables	Description	Example
I type {input} into the {field name} input	input — data to insert, field name — based on label	Insert data into an input text field	I type "James" into the "First name" input
I clear the {field name} input	field name — based on label	Clear the content of an input text field	I clear the "First name" input
I select {input} from the {field name} dropdown	input — option to select, field name — based on label	Select an option from a filterable dropdown	I select "Individual" from the "Client type" dropdown
I type {input} into the {field name} autocomplete	input — data to type, field name — based on label	Type into an autocomplete field, wait for API results, and select the matching option	I type "Smith" into the "Contact name" autocomplete

Accessibility & Keyboard Navigation

Step	Variables	Description	Example
the page should have no accessibility violations	—	Run axe accessibility scan against the whole page and fail if any violations are found	the page should have no accessibility violations
the {input} region should have no accessibility violations	input — region selector/name	Run axe accessibility scan against a specific region (for example main, CSS selector, aria-label)	the "main" region should have no accessibility violations
I press {input} {input} times	input — key, input — number of presses	Press a keyboard key repeatedly using real keyboard events	I press "Tab" 3 times
the {input} input should be focused	input — label/text for the target input	Assert that a specific input is currently focused	the "Facility Name" input should be focused
the page should have at least one ARIA live region	—	Assert that at least one live announcement region exists (aria-live, role=status, role=alert, etc.)	the page should have at least one ARIA live region
the {input} live region should announce {input}	input — region name/selector, input — expected announcement text	Assert that a specific live region contains text that will be announced by screen readers	the "status" live region should announce "Search completed"
the screen reader announcement should include {input}	input — expected announcement text	Assert that any live region announcement includes the expected text	the screen reader announcement should include "Application saved"
the page should announce itself on load as {input}	input — expected page announcement text	Assert page identity is exposed on load (using title, main heading, or landmark label)	the page should announce itself on load as "Waste Plus"
the {input} region should have a valid heading hierarchy	input — region selector/name	Assert headings in the region do not skip levels (for example h2 → h4 is invalid)	the "main" region should have a valid heading hierarchy
the focus order should be {input}	input — comma-separated expected focus names	Assert keyboard Tab order matches the expected sequence	the focus order should be "Facility Name, Client type, Next"
the {input} input should be announced as {input}	input — input identifier, input — expected accessible label	Assert an input's accessible name matches expected spoken label	the "firstName" input should be announced as "First name"
the error message {input} should be announced	input — expected error text	Assert errors are present in announced regions (role=alert, aria-live, etc.)	the error message "First name is required" should be announced

Region names: The resolveRegionSelector helper maps friendly names to CSS selectors. Valid short names: main (resolves to .layout-grid), header, footer, navigation or nav, form. You can also pass a CSS selector, aria-label value, data-testid, or role=region with aria-label. If the helper cannot find a matching element, the step throws an error.

Live region lookup: The findLiveRegion helper resolves regions by role, aria-label, or data-testid. It also accepts CSS selectors (starting with ., #, or [). As a fallback, it searches all live regions for matching text content.

Focusable element lookup: The findInputElement helper resolves inputs by id, name, data-testid, placeholder, aria-label, or associated <label>. For focus order checks, findFocusableElement searches labels, aria-labelledby, and visible text content.

Lighthouse and Perceived Performance

Note: All Lighthouse and Perceived Performance steps are only available when running tests in Chrome or Chromium. Tag scenarios with @chromeOnly as needed.

Step	Variables	Description	Example
the lighthouse score should be at least:	Data table with category and minimum value	Run Lighthouse and assert category minimum thresholds from a data table	the lighthouse score should be at least: (performance=80, accessibility=90)
the lighthouse {input} score should be above {input}	input — category name, input — threshold (integer)	Assert a Lighthouse category score is above a threshold	the lighthouse "performance" score should be above 80
the lighthouse {input} score should be at least {input}	input — metric/category name, input — minimum value (integer)	Assert a Lighthouse metric or category is at or above a threshold	the lighthouse "seo" score should be at least 80
the lighthouse {input} should be at most {input}	input — metric name, input — maximum value (integer)	Assert a Lighthouse metric is at or below a threshold	the lighthouse "largest-contentful-paint" should be at most 2500
the lighthouse metric {input} should be at least {input}	input — metric name, input — minimum value (string)	Assert a Lighthouse metric/category is at or above a threshold	the lighthouse metric "performance" should be at least "85"
the lighthouse metric {input} should be at most {input}	input — metric name, input — maximum value (string)	Assert a Lighthouse metric is at or below a threshold (useful for timings like LCP/TTFB/CLS)	the lighthouse metric "lcp" should be at most "2500"
the lighthouse metrics should be at least:	Data table with metric and minimum value	Assert multiple Lighthouse metrics are at or above thresholds from a data table	the lighthouse metrics should be at least: (performance=80, seo=75)
the lighthouse metrics should be at most:	Data table with metric and maximum value	Assert multiple Lighthouse metrics are at or below thresholds from a data table	the lighthouse metrics should be at most: (lcp=2500, cls=0.1)
the page should load quickly	—	Run Lighthouse and assert quick-load targets (performance, TTFB, LCP, CLS thresholds)	the page should load quickly
the page should be mobile friendly	—	Run Lighthouse and assert mobile-focused thresholds (accessibility, SEO, performance, CLS)	the page should be mobile friendly
the page should follow best practices	—	Assert Lighthouse best-practices score meets minimum threshold	the page should follow best practices
the page should be accessible to most users	—	Assert Lighthouse accessibility score meets minimum threshold	the page should be accessible to most users
the UX quality score should be acceptable	—	Assert combined UX thresholds (performance, accessibility, best practices, SEO + key metrics)	the UX quality score should be acceptable

UI/UX Style Checks

Step	Variables	Description	Example
the {input} {input} should have {input} as {input}	input — element text, input — element type (button, heading, link, etc.), input — CSS property, input — expected value	Assert an element's computed CSS property matches the expected value	the "Login" button should have "color" as "rgb(255, 255, 255)"
the {input} {input} should use the {input} class	input — element text, input — element type, input — CSS class name	Assert an element has a specific CSS class	the "Login" button should use the "cds--btn--primary" class

Design Tokens

Step	Variables	Description	Example
the {input} {input} should have {input} {input}	input — element text, input — element type, input — token name, input — CSS property	Assert an element's CSS property matches the value from a design token	the "Login" button should have "$button-primary" "background-color"
the {input} {input} should have the following table values	input — element text, input — element type, Data table with token and property columns	Assert multiple token/property pairs on an element	the "Login" button should have the following table values:
the {input} {input} should use the {input} token	input — element text, input — element type, input — token name	Assert an element's styles match all definitions from a design token	the "Login" button should use the "$button-primary" token
the {input} {input} should meet {input} standard for contrast	input — element text, input — element type, input — WCAG level (AAA, AA, or A)	Assert that the element's text-to-background contrast ratio meets the WCAG standard	the "Login" button should meet "AA" standard for contrast
the {input} {input} should have {input} typography	input — element text, input — element type, input — token name	Assert the element's typography properties (font-size, weight, line-height, etc.) match the token	the "Welcome" heading should have "$heading-01" typography

---

Hooks

Hooks are special functions that run before or after scenarios to set up or tear down test state. They are not steps you write in your feature files, but they affect how tests run.

Browser Hooks

Tag	Description
@chromeOnly	Skips the scenario unless running in Chrome. Useful for browser-specific or Lighthouse tests.

Example usage:

@chromeOnly
Scenario: Run Lighthouse audit in Chrome only
  When the page should load quickly
  Then the Lighthouse score should be at least:
    | performance    | 80 |
    | accessibility  | 90 |

Login/Session Hooks

Some scenarios require a user to be logged in. The test suite uses hooks to handle login automatically using Cypress sessions. You do not need to write login steps in your feature files—just ensure the environment variables for credentials are set.

How it works:

• The login hook runs before scenarios tagged with @loginAsIDIR or @loginAsBCeID.
• Credentials are read from environment variables (idir_username, idir_password, bceid_username, bceid_password). The hook throws if credentials are missing.
• The hook uses cy.session() to cache the login. The session key includes the username, so login happens once per user type per run.
• The hook visits /, clicks the appropriate login button, fills in the external IDIR/BCeID form at logontest7.gov.bc.ca, and submits.
• After login, the hook validates the session by making a cy.request() to the after-login URL, then navigates there.
• Both @loginAsIDIR and @loginAsBCeID land on /search and wait for the .cds--header__name element to be visible.

Landing page: All authenticated scenarios start on the /search page. If you need a scenario on a different page, navigate there in your first step (e.g., Given I visit "/reporting-units/36828").

How to use:

• You do not need to add any step to your feature file for login. The hook will run automatically if your scenario or background requires authentication.
• Make sure to set the appropriate environment variables before running tests.

Example usage:

@loginAsIDIR
Scenario: Authenticated user can access dashboard
  Given I visit "/dashboard"
  Then I can read "Welcome, user!"

The login/session hook will ensure the user is logged in before the scenario runs. No explicit login step is needed.

---

If you need a new step or hook, check the cypress/cypress/support/step_definitions/ folder for examples, or ask the team to add it for you.

See also

• Writing Test Scenarios — how to create features and scenarios.
• Developer Guide — environment setup and implementation details.