Cypress Rationals

Test Rationales

This page explains the reasoning behind each test category in the Cypress user flow test suite. Understanding why we test each area helps the team prioritize and maintain test quality.

Basic Tests — Navigation and Text Assertion

What we check: Page navigation works, content renders correctly, and the right text appears in the right places.

Why it matters:

Navigation and content rendering are the foundation of any web application. If a user can't reach a page or can't read what's on it, nothing else matters. These tests verify the most fundamental contract between the application and its users — that the application responds to requests and presents the expected content.

• Navigation ensures routing, redirects, and page transitions work as expected
• Text assertions catch broken layouts, missing content, failed API responses, and rendering issues
• Buttons and inputs verify that user interactions produce the expected results

These tests are intentionally simple and broad. They act as the first line of defence, catching regressions before more specialized checks even run.

Perceived Performance — Lighthouse

What we check: Page load speed, Time to First Byte (TTFB), Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS), SEO readiness, and overall best practices.

Why it matters:

Performance is not just a technical metric — it directly affects user satisfaction, conversion rates, and accessibility. Slow pages frustrate users, waste bandwidth, and hurt search rankings.

We use Lighthouse to run automated audits that simulate real-world conditions. By setting minimum thresholds for key metrics, we ensure the application stays fast and responsive as new features are added.

• Performance scores catch regressions like unoptimised images, blocking scripts, or excessive DOM size
• TTFB/LCP thresholds ensure the application feels responsive to users — even on slower connections
• CLS limits prevent layout shifts that confuse users or cause mis-clicks
• SEO and best-practices scores ensure the application follows web standards

Running these checks on every pull request means performance regressions are caught early, before they reach production.

Accessibility — Axe and Keyboard Navigation

What we check: WCAG compliance, screen reader compatibility, keyboard navigation, focus order, ARIA live regions, heading hierarchy, and accessible names.

Why it matters:

Accessibility is a legal requirement in British Columbia and a core principle of inclusive design. An inaccessible application excludes users with visual, motor, cognitive, or situational impairments — and that is not acceptable for a government service.

We use two complementary approaches:

• axe-core runs automated WCAG compliance scans against the DOM, catching issues like missing labels, insufficient contrast, and invalid ARIA attributes
• Keyboard and screen reader assertions verify that the application is operable without a mouse. Focus order, live region announcements, heading hierarchy, and accessible names are checked programmatically

Together, these checks ensure:

• Users who rely on screen readers receive meaningful announcements
• Keyboard-only users can navigate the application in a logical order
• Error messages are announced to assistive technologies
• Page structure follows semantic HTML and ARIA best practices

Automated accessibility testing does not replace manual review, but it catches the most common violations consistently and at scale.

UI/UX Quality — Design Tokens and Style Checks

What we check: Visual consistency with the design system, correct use of design tokens for typography, colour, spacing, borders, WCAG contrast ratios, and adherence to the Carbon Design System.

Why it matters:

A consistent user interface builds trust, reduces cognitive load, and reinforces brand identity. When elements drift from the design system — even slightly — the user experience degrades over time. Manual visual review is time-consuming and impossible to repeat on every change.

Automated UI/UX checks act as a robotic designer that reviews every screen on every pull request:

• Design token validation ensures components use the correct token values (font sizes, colours, spacing), preventing hard-coded values from creeping in
• Style checks verify computed CSS properties match expectations, catching unintended overrides or missing styles
• Contrast validation ensures text-to-background colour ratios meet WCAG AA or AAA standards
• Typography checks verify font families, sizes, weights, and line heights match the design token specifications

These checks protect the investment made in the design system by enforcing it automatically. Violations are categorised by taxonomy (typography, colour, spacing, border) and severity (critical, major, minor), giving designers actionable feedback without manual effort.

See also

• Step Reference — full list of available step instructions.
• UX/UI Guide — overview of UI/UX quality checks for designers.
• UX/UI Guide for Developers — technical implementation details.