Skip to content

testing.md

Latest commit

 

History

History
128 lines (89 loc) · 4.65 KB

testing.md

File metadata and controls

128 lines (89 loc) · 4.65 KB
Raw

Testing

Overview

Tests live alongside the code they exercise. A Vitest projects configuration at the repo root discovers each app's vitest.config.ts, so tests for all apps run from a single command. The site app uses jsdom for component tests and plain Node for utility/config tests; the docs app uses plain Node for config tests.

apps/site/src/
  config/
    navigation.ts
    navigation.test.ts      <- data-driven config tests
  util/
    slugify.ts
    slugify.test.ts         <- pure unit tests
  components/
    layout/
      SearchInput.tsx
      SearchInput.test.tsx  <- React component tests

apps/docs/src/
  config/
    sidebar.ts
    sidebar.test.ts         <- sidebar structure tests

Running tests

# single run (all projects)
npm test

# watch mode
npm run test:watch

# browser UI
npm run test:ui

# single project only
npx vitest run --project @bdc/site
npx vitest run --project @bdc/docs

Test-Driven Development Workflow

Ensuring the UI stays predictable is key to its sustainability and success. To help increase the probability of producing a stable application, we adhere to a test-driven development workflow.

Workflow

The following steps should be followed when developing new features.

  1. Define the feature and any associated data or interface changes.

  2. Write tests that validate the desired behavior or data structure.

    Note: These tests will fail at first. That's the point.

  3. Implement the feature to make the tests pass.

  4. Refine: iterate on the implementation and tests until behavior is correct and edge cases are covered.

  5. Build UI support for any restructured data, if applicable.

  6. Validate: run the full test suite and confirm nothing else broke.

What to test

Not every file needs a test. Focus testing effort where it provides the most value:

Avoid testing framework internals, Astro's build pipeline, or third-party library behavior.

Conventions

  • Test files are co-located with the module they test: foo.ts → foo.test.ts.
  • Use describe / it blocks with human-readable descriptions.
  • Prefer @testing-library/react for component tests: query by role, label, or text, not implementation details.
  • Keep tests focused. One behavior per it block.

Accessibility Testing

Automated accessibility audits run in CI using Playwright and axe-core. Every page in the built site is tested against WCAG 2.0/2.1 Level AA to satisfy Section 508 requirements.

# audit specific pages against a running dev server
npm run a11y:page -w @bdc/site -- http://localhost:4321/about

# build & test key pages
npm run a11y:smoke -w @bdc/site

# build & test every page in the sitemap
npm run a11y:full -w @bdc/site

See apps/site/a11y/README.md for configuration details, compliance targets, and how to add exceptions.

Browser Markup Contract Tests

The site also uses Playwright for a small set of browser-level markup contract checks that are not accessibility tests.

These tests verify rendered HTML attributes that the analytics layer depends on, such as data-analytics-section on shared layout roots. They live under apps/site/e2e/ and use plain @playwright/test rather than the axe-based fixtures in apps/site/a11y/.

The current analytics-root coverage checks:

  • the homepage renders exactly one header analytics root
  • the homepage renders exactly one footer analytics root
  • multiple real pages that currently use InPageNav render the expected in_page_nav analytics root

Because the Playwright config for apps/site uses astro preview, these checks run against built output.

# build & run the focused analytics markup contract check
npm run test:analytics-sections -w @bdc/site

Keep these tests focused on browser-observable markup contracts. Logic-heavy analytics behavior should stay in the existing Vitest coverage.