step reference

---

title: "Cypress Step Reference" type: reference domain: testing framework: cypress-cucumber tags: [cypress, gherkin, step-definitions, a11y, lighthouse, design-tokens] created: 2026-07-14

Cypress Step Reference

Complete list of Gherkin step definitions available for writing test scenarios.

Variables

Variables are wrapped in double quotes. Two types exist:

• Input — the data to insert or select ("James", "/landing")
• Field name — identifies a form field by its label ("First name", "Client type")

Field name variables must match the exact label text on screen, including casing.

Navigation

Step	Variables	Description
I visit {input}	input — URL path	Navigate to a path. Intercepts search API calls when visiting /search.

Assertions

Step	Variables	Description
I can read {input}	input — visible text	Assert text is visible on screen
I cannot see {input}	input — absent text	Assert text does not exist in DOM
I wait for the text {input} to appear	input — text to wait for	Wait for text to become visible
I wait for the text {input} to appear after {input}	text, intercepted request alias	Wait for a cy.intercept alias to resolve, then assert text

Buttons

Step	Variables	Description
I click on the {field name} button	field name — button text or label	Find and click a button
I search	—	Click the Search button and wait for the /api/search/ response

Button resolution order

The findButton helper tries selectors in this order:

1. [data-testid="X"]
2. button[aria-label="X"]
3. button:contains("X")
4. input[type="submit"][value="X"]
5. a:contains("X")
6. a[aria-label="X"]
7. Carbon icon-only buttons via .cds--tooltip-content + aria-labelledby
8. @testing-library findByRole("button") or findByRole("link") as fallback

Retries up to 3 times with 100ms delay if the element hasn't rendered.

Inputs

Step	Variables	Description
I type {input} into the {field name} input	data, field label	Type into a text input
I clear the {field name} input	field label	Clear an input field
I select {input} from the {field name} dropdown	option, field label	Select from a Carbon filterable dropdown
I type {input} into the {field name} autocomplete	data, field label	Type into autocomplete, wait for API, select match

Input resolution

findInputByLabel resolves labels through:

1. <label for="id"> → <input id="id">
2. Carbon container (.cds--form-item, .cds--search) → nested input
3. Generic fallback: label text near an input

Autocomplete

The autocomplete step intercepts /api/search/reporting-units-users by default. If the API path changes, update the url parameter in selectFromAutocomplete.

Accessibility and Keyboard Navigation

Step	Variables	Description
the page should have no accessibility violations	—	Run axe scan on entire page
the {input} region should have no accessibility violations	region name or selector	Run axe scan on a specific region
I press {input} {input} times	key, count	Press a key using cypress-real-events
the {input} input should be focused	label	Assert input has focus
the page should have at least one ARIA live region	—	Assert live region exists
the {input} live region should announce {input}	region, text	Assert live region contains announced text
the screen reader announcement should include {input}	text	Search all live regions for text
the page should announce itself on load as {input}	text	Check title, h1, and landmark labels
the {input} region should have a valid heading hierarchy	region	Assert headings don't skip levels
the focus order should be {input}	comma-separated labels	Tab through and assert focus order
the {input} input should be announced as {input}	identifier, label	Assert accessible name matches
the error message {input} should be announced	text	Check role=alert, aria-live, aria-invalid, aria-errormessage

Region names

resolveRegionSelector maps short names to CSS selectors:

Name	Resolves to
main	.layout-grid
header	header
footer	footer
navigation / nav	nav
form	form

Also accepts CSS selectors, aria-label values, data-testid, or role=region with aria-label.

Live region lookup

findLiveRegion resolves by role, aria-label, or data-testid. Falls back to searching all live regions for matching text.

Focusable element lookup

findInputElement resolves by id, name, data-testid, placeholder, aria-label, or associated <label>. findFocusableElement additionally searches labels, aria-labelledby, and visible text.

Lighthouse and Performance

All Lighthouse steps require Chrome. Tag scenarios with @chromeOnly.

Step	Variables	Description
the lighthouse score should be at least:	data table	Assert category minimums from table
the lighthouse {input} score should be above {input}	category, threshold	Assert category above threshold
the lighthouse {input} score should be at least {input}	metric, minimum	Assert metric at or above minimum
the lighthouse {input} should be at most {input}	metric, maximum	Assert metric at or below maximum
the lighthouse metric {input} should be at least {input}	alias, minimum (string)	Assert metric at or above minimum
the lighthouse metric {input} should be at most {input}	alias, maximum (string)	Assert metric at or below maximum
the lighthouse metrics should be at least:	data table	Assert multiple metrics at or above
the lighthouse metrics should be at most:	data table	Assert multiple metrics at or below
the page should load quickly	—	Assert performance ≥85, TTFB ≤95ms, LCP ≤2000ms, CLS ≤0.1
the page should be mobile friendly	—	Assert accessibility, SEO, performance, CLS
the page should follow best practices	—	Assert best-practices ≥90
the page should be accessible to most users	—	Assert accessibility ≥90
the UX quality score should be acceptable	—	Assert all four categories + key metrics

Metric aliases

normalizeMetricKey maps short names: ttfb → server-response-time, lcp → largest-contentful-paint, fcp → first-contentful-paint, cls → cumulative-layout-shift, tbt → total-blocking-time.

UI/UX Style Checks

Step	Variables	Description
the {input} {input} should have {input} as {input}	text, type, property, value	Assert computed CSS property
the {input} {input} should use the {input} class	text, type, class	Assert element has CSS class

Design Tokens

Step	Variables	Description
the {input} {input} should have {input} {input}	text, type, token, property	Assert property matches token value
the {input} {input} should have the following table values	text, type, data table	Assert multiple token/property pairs
the {input} {input} should use the {input} token	text, type, token	Assert all properties from token
the {input} {input} should meet {input} standard for contrast	text, type, WCAG level	Assert contrast ratio (AAA/AA/A)
the {input} {input} should have {input} typography	text, type, token	Assert typography properties from token

Element types

resolveElementByTypeAndText supports: button, heading/headings, link, input/field, text/label, section, image/icon, div/card.

Hooks

Tag	Description
@chromeOnly	Skip scenario unless running in Chrome
@loginAsIDIR	Log in as IDIR user, land on /search
@loginAsBCeID	Log in as BCeID user, land on /search

Login hook behavior

• Uses cy.session() to cache login per user type
• Visits /, clicks login button, fills external IDIR/BCeID form at logontest7.gov.bc.ca
• Validates session with cy.request(), then navigates to /search
• Both hooks land on /search and wait for .cds--header__name
• Throws if credentials are missing from environment variables