Testing

Testing Radix NG Primitives

First pick the layer, then write the test. Most bugs in this library are caught by Vitest unit tests — but the suite runs in jsdom, which has no real layout (no box sizes, offsetHeight / scroll metrics, flexbox resolution, getComputedStyle geometry, or floating-ui positioning), and never opens an overlay the way a user does. Those gaps have their own layers. Match the change to the layer below before writing anything.

Decision matrix — what changed → which layer

The rule that bit us: a select restructure made rdxSelectList (inline flex:1) a direct flex child of the popup; its inline flex overrode the demo's fixed viewport height, so the viewport grew to fit all items, never overflowed, and both scroll buttons stayed [hidden]. Every unit test stayed green — jsdom has no flexbox. A layout / positioning / visibility / opens-without-error fix is not proven until a browser behavior.spec.ts covers it.

1. Unit — Vitest, zoneless (the default)

• Where: packages/primitives/<name>/__tests__/<name>-<role>.spec.ts
• Run: pnpm primitives:test · single file: nx run primitives:test --testFile packages/primitives/<name>/__tests__/<file>.spec.ts
• Stack: Vitest + AnalogJS Angular plugin + @testing-library/angular. Setup packages/primitives/test-setup.ts sets provideZonelessChangeDetection, loads @testing-library/jest-dom/vitest + the jest-axe matcher, and does not load zone.js — the suite is zone-free.
• Use Vitest APIs (vi.fn, vi.spyOn, vi.mock, vi.importActual), never Jest globals. xdescribe/xit map to .skip.

Zoneless gotchas (these are the common failures):

• fakeAsync / tick / waitForAsync are unavailable. Instead:
  • setTimeout-based delays → vi.useFakeTimers() + vi.advanceTimersByTime(n)
  • render / effects settle → await fixture.whenStable()
  • drain a chained microtask queue → await new Promise((r) => setTimeout(r))
• Mutating a plain (non-signal) field then calling fixture.detectChanges() throws NG0100 — call fixture.changeDetectorRef.markForCheck() first. Signal writes (input.set, model.set, componentRef.setInput) don't need it.

a11y in the same spec (matcher is pre-registered):

import { axe } from 'jest-axe';
// …after rendering / opening:
expect(await axe(container)).toHaveNoViolations();

References to copy: drawer/__tests__/drawer.spec.ts, form/__tests__/form-a11y.spec.ts.

Standard-backed test names. When a spec verifies an accessibility behavior, prefix the it(...) title with the standard it backs: [APG <Pattern>] and/or [WCAG <x.y.z>], APG before WCAG, no lowercasing — e.g. it('[APG Dialog][WCAG 4.1.2] links the trigger and popup with accessible ids and roles', …). Tag only specs that map cleanly to a criterion (roles/labels, keyboard, focus trap/restore, axe), not plumbing. This mirrors each primitive's Accessibility-table rows so the suite reads as a traceability matrix (full convention: storybook-story skill). Reference: dialog/__tests__/dialog.spec.ts.

2. Browser regression — apps/visual-regression (Playwright over the built Storybook)

This is the layer for everything jsdom can't see. Two spec kinds live in apps/visual-regression/tests/:

<name>.behavior.spec.ts — DOM/behavior, not pixels

Open the story via its real interaction, then assert. Prefer auto-retrying web-first assertions (expect(locator).toBeVisible()) over fixed waitForTimeout so async open/positioning settles deterministically.

import { expect, Page, test } from '@playwright/test';

async function gotoStory(page: Page, storyId: string) {
  await page.goto(`/iframe.html?id=${storyId}&viewMode=story`);
  await page.waitForSelector('#storybook-root', { state: 'attached' });
}

test('scroll viewport overflows and buttons toggle', async ({ page }) => {
  await gotoStory(page, 'primitives-select--with-scroll');
  await page.locator('[rdxSelectTrigger]').first().click();

  const up = page.locator('[rdxSelectScrollUpButton]');
  const down = page.locator('[rdxSelectScrollDownButton]');
  const list = page.locator('[rdxSelectList]');

  await expect(down).toBeVisible(); // parts use the [hidden] attribute
  await expect(up).toBeHidden();
  const m = await list.evaluate((el) => ({ sh: el.scrollHeight, ch: el.clientHeight }));
  expect(m.ch).toBeLessThan(m.sh); // a REAL overflow, not full-content expansion
  await list.evaluate((el) => el.scrollBy(0, 200));
  await expect(up).toBeVisible();
});

Catch open-time runtime errors (NG0201 / NG0951) — attach listeners before navigating:

const errors: string[] = [];
page.on('pageerror', (e) => errors.push(e.message));
page.on('console', (m) => m.type() === 'error' && errors.push(m.text()));
await gotoStory(page, 'primitives-select--aligned-position');
await page.locator('[rdxSelectTrigger]').first().click();
await expect(page.locator('[rdxSelectPopup]')).toBeVisible();
expect(errors).toEqual([]);

Story id derivation: lowercase the CSF title, replace / with -, append --, then the kebab-cased export name. Example: title Primitives/Select + export WithScroll → primitives-select--with-scroll.

<name>.visual.spec.ts — screenshot diffing

toHaveScreenshot with animations: 'disabled' (asserts the settled state, not mid-motion). Baselines committed under tests/*-snapshots/, suffixed per project+platform (…-chromium-darwin.png). stories.visual.spec.ts auto-shoots every story; overlays.visual.spec.ts covers open-state positioning. Opt a story out of the auto sweep with the !visual CSF tag.