fix: three-layer test architecture and the defects it surfaced

[robsongajunior]

The webkit testing initiative: a three-layer test architecture for @aziontech/webkit (functional browser-mode suite, Storybook visual regression, one ordered CI pipeline), plus the component and packaging defects the new suites surfaced. 36 commits.

Layer 1 — Functional suite (Vitest browser mode)

• Vitest 4 + @vitest/browser-playwright running every test in real headless Chromium — behavior, structure, and ARIA on a real DOM, not jsdom.
• 75 suites / 1,588 tests (1,582 passing, 6 documented skips) covering every exported component, including the eight that had no suite: popover, accordion, split-button, scroll-area, input-group, field-input-group, field-phone-number, field-text-switch. The templates/ components are intentionally untested — the folder is slated for deletion.
• Shared foundation:
  • vitest.config.ts — browser mode, CI retry, v8 coverage config (report-only for now)
  • src/test/setup.ts — anchor-navigation guard (real <a href> clicks would tear down the test iframe) + per-test cleanup
  • src/test/axe.ts — axe-core structural a11y helper; every suite asserts zero violations (visual rules like color-contrast are disabled because this env doesn't run Tailwind — pixels belong to Layer 2)
• Adapted to the post-merge dev: the standardized stories tree (per-component folders, renamed exports) and the breaking event refactor — suites now assert the positional (event, item) payloads of dropdown select, split-button item-click, breadcrumb navigate, pick-list item-double-click and table row-click, including the originating MouseEvent/KeyboardEvent.
• Conventions documented in .claude/rules/testing.md and enforced by a new enforce-test-exists.mjs hook; the component-scaffold skill now emits a test file.

Real component defects documented via it.skip (verified red, not faked green)

1. split-button — Dropdown.Trigger (role="button" span) wraps the real IconButton <button> → axe nested-interactive (split-button.vue:141).
2. input-group — aria-required is set on the role="group" root, where it is not an allowed ARIA attribute → axe aria-allowed-attr.
3. field-phone-number — the country trigger (role="combobox") has no accessible name: the aria-label lands on the Select wrapper div (field-phone-number.vue:143). Blocks two axe assertions (same root cause).
4. field-phone-number — the dial code is passed as <SelectTrigger> slot content, but select-trigger.vue has no default slot → the trigger shows the raw ISO code ("BR" instead of "+55") (field-phone-number.vue:146).
5. breadcrumb — selecting an overflow Dropdown option doesn't surface the navigate emit under synthetic interaction; needs a component-level check.

Layer 2 — Visual regression (Storybook test-runner)

• @storybook/test-runner + jest-image-snapshot: every story (75 files / 309 snapshots) screenshotted at #storybook-root (1280×720, fonts ready, animations at 1ms via the visual-test-freeze style, pointer parked) and compared against committed baselines with a 0.01% threshold.
• 309 linux baselines committed — regenerated post-merge, so they match the standardized story IDs and the new parameters.layout geometry. Baselines are platform-specific: linux/ is the CI contract; darwin/ supports local runs and stays gitignored.
• Templates excluded from the visual layer (test-runner-jest.config.js → testPathIgnorePatterns): the stories/templates/ files are never collected — no render smoke, no snapshot, no baseline on -u. Their orphan baselines were removed.
• playwright pinned to ^1.61.1 in both packages/webkit and apps/storybook, so the CLI that installs Chromium in CI is the same version the runners use.
• Scripts: test:visual / test:visual:static / test:visual:ci / test:visual:update in the storybook app; at the root, storybook:test:visual* plus storybook:test:visual:update:baseline (dispatches the regeneration workflow).

Layer 3 — CI: one ordered pipeline, no loose checks

• governance.yml now carries the whole chain:
  changes → security ∥ lint ∥ types → build ∥ storybook ∥ tests → visual → Governance Gate
  • tests — the Vitest browser suite, sharded 4×, gated on lint + types (stories are unit fixtures, so apps/storybook changes retrigger it).
  • visual — last link: builds Storybook and runs test:visual:ci against the committed baselines only after everything upstream is green; uploads __diff_output__ on failure.
  • The gate's results map now includes tests and visual; cleanly-skipped jobs still pass (path-filtered).
• package-webkit-test.yml removed — its shard matrix moved into governance, so the suite no longer double-runs per PR.
• app-storybook-generate-baseline.yml — dispatch-only baseline tool: run with update_baselines=true, download the visual-baselines-linux artifact, commit its contents.

Defects surfaced and fixed by the suites

• breadcrumb: the overflow menu nested a real IconButton inside Dropdown.Trigger (itself role="button") — an axe nested-interactive violation. The Trigger now carries the icon and styling directly.
• calendar.test.ts rewritten for the post-[ENG-46317] feat(webkit): evolve Calendar into a date-range picker #707 date-range picker (33 tests: trigger→popover flow, draft + Apply commit semantics, show-apply=false immediate mode, presets, keyboard grid navigation, clearable, axe).
• copy-button suite adapted to the post-[NO-ISSUE] fix(webkit): apply loading as a disabled visual state with distinct cursors #715 IconButton span wrapper; orphan empty-results-block.test.ts removed.

Packaging / publish hygiene

• The npm tarball no longer ships tests: files negations (!src/**/*.test.{ts,js}, !src/test/**) plus a pack:check guard script that fails if a test file leaks into npm pack.
• pnpm-workspace.yaml: @swc/core postinstall disabled (the native binary ships via the platform optionalDep; the script is only a download fallback).
• Storybook imports @aziontech/webkit directly — the @aziontech/webkit.dev Vite alias is gone (follow-up to the [NO-ISSUE] fix: resolve prettier format and vue-tsc type-check CI failures #726 package rename). Dead webkit-v3 ref and unused root deps removed.

How to run

pnpm webkit:test                          # full browser-mode suite (root)
pnpm webkit:test:coverage                 # + v8 coverage report
pnpm storybook:test:visual                # build storybook + visual run against local baselines
pnpm storybook:test:visual:update:baseline  # dispatch the CI workflow that regenerates linux baselines

Verification

• Functional suite: 75 files, 1,582 passed / 6 skipped (skips = the documented component defects above)
• Visual suite: 75 story files / 309 linux baselines, templates excluded by config
• vue-tsc --noEmit, ESLint (--max-warnings 0), and prettier all clean