Skip to content

Testing ​

The suite is split into three layers on purpose (SPEC §7): unit tests exercise the invoker-commands polyfill path in jsdom (fast, broad coverage of every command/event/attribute combination); e2e tests exercise the native browser path in real Chromium plus focused WebKit coverage for pd-nav/pd-drawer, along with everything jsdom structurally can't emulate (hover timing, focus traps, real animations, real scroll). Both halves of the polyfill-vs-native split are covered — a bug that only shows up under one or the other still gets caught.

How this repo tests ​

Unit — Vitest + jsdom + the polyfill ​

vitest.config.ts runs tests/**/*.test.ts in a jsdom environment with tests/setup.ts as a global setup file — one glob, so a single vitest run covers both this Unit layer and the A11y layer below (they're conceptually separate, not separately configured). That file imports invokers-polyfill unconditionally — jsdom has no native CommandEvent, so every unit test exercises the same polyfilled invoker path a non-supporting browser gets — and extends Vitest's expect with vitest-axe's matchers for the a11y layer below.

tests/helpers.ts gives every test file four building blocks:

  • mount(html) — appends markup into a fresh <div> and awaits one macrotask, long enough for a component's whenParsed()-deferred initial sync (and any afterAnimations resolution) to run.
  • tick(ms) — a raw setTimeout promise for anything that needs more time.
  • press(target, key) — dispatches a real bubbling, cancelable KeyboardEvent, so keyboard-map tests exercise the actual keydown listeners rather than calling internal methods directly.
  • invoke(button) — calls .click() on a real invoker button; the polyfill turns that into a CommandEvent, so command wiring is tested through the same path an author's markup uses, never through a private method.

Per module (tests/unit/<module>.test.ts), the baseline coverage required by SPEC §7 is: idempotent define(); command wiring via real invoker buttons; components created before their children parse (append markup after connect, not before — catches upgrade-ordering bugs); ARIA syncing including author-supplied id preservation and the no-aria-controls rule; the complete keyboard map; every event including canceling pd:open/pd:close; attribute configuration (defaults, overrides, runtime changes); focus management (Escape return, drill/back, drawer restore where jsdom allows); disconnect cleanup (no ghost listeners after .remove()); and malformed markup (missing dialog/invoker/list) producing a console warning, never a thrown error.

A11y — vitest-axe ​

tests/a11y/<module>.a11y.test.ts mounts a realistic fixture — not a minimal one; nav.a11y.test.ts for example mounts a full two-item mega menu with real link/button markup, matching what a theme would actually render — and runs axe() against it in both a closed and an open state, each required to return zero violations. Opening is done through the component's own public API (panel.show(), or invoke() on a real trigger) rather than by waiting on an animation, since afterAnimations already resolves synchronously in jsdom (see the caveats below).

E2E — Playwright + Chromium/WebKit ​

playwright.config.ts runs the full suite in Chromium and repeats the pd-nav/pd-drawer interaction suites in WebKit, served by Vite at http://localhost:4173 (npm run dev, i.e. vite.demo.config.ts) with webServer configured to boot that dev server automatically. Fixtures live in e2e/fixtures/ as plain HTML pages that import /src/define.ts directly. Chromium therefore exercises its native Invoker Commands API, the other half of the coverage split from jsdom; WebKit exercises the entry point's conditional invokers-polyfill import in a real browser while supplying an independent focus/modality implementation. Page-level Tab-order cases that depend on the host macOS Full Keyboard Access preference are explicitly skipped there, while Enter/Space, arrows, Escape layering, modal containment, and focus restoration still run.

This is also where everything jsdom can't emulate gets asserted: hover intent driven by real page.mouse.move() timing (not fake timers); the drawer's native focus trap and focus restore; Escape flows; synchronous inert → exit-animation → hidden/dialog.close() sequencing against real CSS animations (getAnimations() genuinely runs here, unlike the jsdom no-op); pd-header show/hide on real scroll events with real layout; drilldown focus journeys; and @axe-core/playwright scans of every fixture in both open and closed states.

jsdom caveats (SPEC §7) ​

These are structural jsdom limitations, not bugs — know them before "fixing" a unit test that looks wrong:

  • getAnimations is absent. afterAnimations() (src/internal/animation.ts) falls back to resolving synchronously when el.getAnimations is undefined. Unit tests can assert the sequence an exit follows (data-state="closed" + component-owned inert synchronously, then hidden/native dialog close and pd:closed) but never real animation timing. Unit coverage also verifies rapid reopen removes only managed inertness and author-supplied inert survives; real transition timing belongs to the e2e exit-animation-sequencing coverage.
  • :focus-visible is unsupported. isFocusVisible() (src/internal/focus.ts) wraps el.matches(':focus-visible') in a try/catch and returns false in jsdom. Any unit test that needs to exercise open-on-focus must vi.mock the focus module and stub isFocusVisible to return true (see the top of tests/unit/nav.test.ts) — otherwise every focus-driven open silently no-ops and the test would pass for the wrong reason.
  • Native <dialog> focus trap isn't emulated. The jsdom version pinned in this repo doesn't implement HTMLDialogElement.prototype.showModal/close at all. tests/unit/drawer.test.ts and tests/a11y/drawer.a11y.test.ts install a minimal shim that toggles the open attribute (mirroring the real methods' visible effect) purely so pd-drawer's try { dialog.showModal() } / if (dialog.open) dialog.close() guards have something to call. That shim does not reproduce top-layer stacking, background inertness, or the native Tab-cycle focus trap — those assertions live in e2e only.
  • Hover-intent timing. Unit tests use vi.useFakeTimers() + vi.advanceTimersByTimeAsync() to assert hover-open-delay/hover-close-delay behavior deterministically and instantly; e2e uses real timers driven by actual pointer movement to prove the same behavior holds under real pointerover/pointerout timing.

Smoke-testing your theme integration ​

The library's own suite proves the components are correct. It cannot see the markup, Liquid loops, or copy your theme wraps around them (see the Shopify integration guide) — that's your integration's job to verify, not this one's. A minimal smoke test for a consuming theme:

  1. Axe scan. After vendoring the bundle, run an automated scan — the axe DevTools browser extension for a manual pass, or @axe-core/playwright in the theme's own CI — against every template that renders a pd-* component, in both a closed and a representative open state: mega menu open, cart drawer open, mobile drilldown two levels deep, brand index filtered. Zero violations is the bar this library holds itself to in tests/a11y/*; what a scan here actually catches is missing labels, bad contrast, and landmark structure — the parts the library structurally cannot verify for you (see the Accessibility guide).
  2. Keyboard walk. Tab from the top of the page through every top-level nav stop. Open a mega menu panel with Enter or ArrowDown and confirm focus lands inside it; ArrowRight/ArrowLeft across top-level stops without leaving a panel open behind you; Escape closes and returns focus to the trigger. Open the mobile drawer, confirm Tab cycles only inside it and Escape closes and restores focus to the opener. Drill into a drilldown panel and back out, confirming focus returns to the exact button that drilled in. Tab through an A–Z filter and confirm empty letters are genuinely skipped (disabled, not merely styled to look inactive).
  3. Wire it into CI. A lightweight Playwright spec per template, using @axe-core/playwright, mirrors this repo's own e2e/*.spec.ts pattern — just point it at the theme's preview URL instead of e2e/fixtures. It doesn't replace this library's test suite; it validates the Liquid loops and markup the theme wrote on top of it, which is outside this suite's reach by construction.