Mixins / foldkit-mixins/testing

Conformance

namespace · packages/mixins/src/conformance.ts:17

export * as Conformance from './conformance.js'

Rendered conformance: scenarios over a widget mounted in a real browser, each a function of a small harness that returns its findings as data. A scenario reads what the page did (roles and names from Chromium's own accessibility tree, state from attributes, focus from document); it never reads a Model, a Slot or an obligation, so it holds a shipped widget and a view assembled from primitives to the same behaviour. Conformance.server is the half that reads server markup parsed back. Re-exported as Conformance from foldkit-mixins/testing.

"Rendered" is a claim about one page: these checks happened here. Whether the declarations fit together is A11y.check's (structural) and what the author says is provides (declared).

In the guides

Members

Conformance.AxNode

interface · packages/mixins/src/conformance.ts:17

interface AxNode {
  readonly role: string
  readonly name: string
  readonly states: Readonly<Record<string, string>>
  readonly node: Node
}

One node of Chromium's accessibility tree (Accessibility.getFullAXTree), reduced.

Conformance.BrowserTools

interface · packages/mixins/src/conformance.ts:60

interface BrowserTools {
  readonly cdp: () => CdpSession
  readonly userEvent: {
    readonly keyboard: (text: string) => Promise<unknown>
  }
}

What harness takes from Vitest's browser mode (import { cdp, userEvent } from 'vitest/browser'), passed in so this module imports no test runner.

Conformance.CdpSession

interface · packages/mixins/src/conformance.ts:41

interface CdpSession {
  send(method: 'Accessibility.enable'): Promise<unknown>
  send(method: 'Page.getFrameTree'): Promise<unknown>
  send(
    method: 'Accessibility.getFullAXTree',
    params: {
      frameId: string
    },
  ): Promise<unknown>
  send(
    method: 'DOM.resolveNode',
    params: {
      backendNodeId: number
      objectGroup: string
    },
  ): Promise<unknown>
  send(
    method: 'Runtime.callFunctionOn',
    params: {
      objectId: string
      functionDeclaration: string
    },
  ): Promise<unknown>
  send(
    method: 'Runtime.releaseObjectGroup',
    params: {
      objectGroup: string
    },
  ): Promise<unknown>
}

The Chrome DevTools Protocol calls harness makes; Vitest's cdp() session has them.

Conformance.Check

interface · packages/mixins/src/conformance.ts:177

interface Check {
  readonly scenario: string
  readonly check: string
  readonly passed: boolean
  readonly detail: string
}

One thing a scenario looked at.

Conformance.checkbox

function · packages/mixins/src/conformance.ts:486

function checkbox(harness: Harness, spec: CheckboxSpec): Promise<Result>

A checkbox: its role and name from the accessibility tree; Space toggles it and what it reports (aria-checked, or the native checked) follows, both ways; a press toggles it; a disabled one does not toggle.

Conformance.CheckboxSpec

interface · packages/mixins/src/conformance.ts:466

interface CheckboxSpec {
  readonly name: string
  readonly disabled?: string
  readonly enter: () => Promise<void>
}

Conformance.dialog

function · packages/mixins/src/conformance.ts:741

function dialog(harness: Harness, spec: DialogSpec): Promise<Result>

A dialog: its role and name from the accessibility tree; focus moves in when it opens and Tab never leaves it; Escape closes it and gives focus back to what had it; opened over another dialog, Escape closes only the inner one, focus returns into the outer, and a second Escape closes the outer.

Conformance.DialogSpec

interface · packages/mixins/src/conformance.ts:698

interface DialogSpec {
  readonly name: string
  readonly open: () => Promise<void>
  readonly trigger: () => HTMLElement | null
  readonly nested?: {
    readonly name: string
    readonly open: () => Promise<void>
    readonly trigger: () => HTMLElement | null
  }
}

Conformance.Direction

type · packages/mixins/src/conformance.ts:190

type Direction = 'ltr' | 'rtl'

Conformance.Expect

interface · packages/mixins/src/conformance.ts:977

interface Expect {
  readonly role: string
  readonly name: string
  readonly attributes?: Readonly<Record<string, string | boolean>>
}

What server markup, parsed back, must hold: roles, names and the state attributes each carries.

Conformance.failures

function · packages/mixins/src/conformance.ts:188

function failures(result: Result): Result

The checks that failed: a conforming widget gives [].

Conformance.Harness

interface · packages/mixins/src/conformance.ts:26

interface Harness {
  readonly root: Element | Document
  readonly press: (keys: string) => Promise<void>
  readonly accessibility: () => Promise<ReadonlyArray<AxNode>>
  readonly click: (element: Element) => Promise<void>
}

Conformance.harness

function · packages/mixins/src/conformance.ts:93

function harness(tools: BrowserTools, root?: Element | Document): Harness

A harness over Vitest's browser mode: keys from userEvent.keyboard, the accessibility tree from Chrome's own (Accessibility.getFullAXTree, which names an element as a screen reader hears it, where Vitest's locators read generated text Chrome leaves out), and a pointer press as dispatched events, which reach an aria-disabled element Playwright refuses to press. The tree is read in the frame root is drawn in and kept to the nodes inside root, each with its DOM node.

Conformance.listbox

function · packages/mixins/src/conformance.ts:304

function listbox(harness: Harness, spec: ListboxSpec): Promise<Result>

A listbox: roles and names from the accessibility tree; the arrows (mirrored under right to left when horizontal), Home and End move the keyboard over the enabled options and never onto a disabled one; Enter and Space activate; a press selects an enabled option and not a disabled one; aria-selected has a value on every option after every step.

Conformance.ListboxSpec

interface · packages/mixins/src/conformance.ts:275

interface ListboxSpec {
  readonly name: string
  readonly options: ReadonlyArray<string>
  readonly disabled?: string
  readonly orientation?: Orientation
  readonly direction?: Direction
  readonly enter: () => Promise<void>
}

Conformance.Orientation

type · packages/mixins/src/conformance.ts:191

type Orientation = 'vertical' | 'horizontal'

Conformance.Result

type · packages/mixins/src/conformance.ts:185

type Result = ReadonlyArray<Check>

Conformance.server

function · packages/mixins/src/conformance.ts:1034

function server(
  scenario: string,
  root: ParentNode,
  expected: ReadonlyArray<Expect>,
): Result

The server half: a widget rendered to a string and parsed back holds each expected role with its name and attributes, so a page served before it hydrates already conforms. scenario only labels the findings.

Conformance.tabs

function · packages/mixins/src/conformance.ts:853

function tabs(harness: Harness, spec: TabsSpec): Promise<Result>

Tabs: the tab list, tabs and the one panel from the accessibility tree, the panel named by its tab; exactly one tab selected, its aria-controls the panel; the arrows (mirrored under right to left) move over the enabled tabs and never onto a disabled one, which says it is disabled; Home and End reach the ends; aria-selected has a value on every tab after every step.

Conformance.TabsSpec

interface · packages/mixins/src/conformance.ts:830

interface TabsSpec {
  readonly name: string
  readonly tabs: ReadonlyArray<string>
  readonly disabled?: string
  readonly direction?: Direction
  readonly activation?: 'automatic' | 'manual'
  readonly enter: () => Promise<void>
}

Conformance.tree

function · packages/mixins/src/conformance.ts:584

function tree(harness: Harness, spec: TreeSpec): Promise<Result>

A tree: its role, name and rows from the accessibility tree; the arrow toward the end opens a shut parent, then moves onto its first child; the one toward the start goes back to the parent, then shuts it (both mirrored under right to left); Down and Up move over the rows showing; Home and End reach the ends; aria-expanded has a value on every parent.

Conformance.TreeSpec

interface · packages/mixins/src/conformance.ts:562

interface TreeSpec {
  readonly name: string
  readonly parent: string
  readonly child: string
  readonly next: string
  readonly direction?: Direction
  readonly enter: () => Promise<void>
}