@llui/test

Test harness for LLui components. Mount components in jsdom, send messages, and assert on state and DOM.

pnpm add -D @llui/test

Usage

import { testView } from '@llui/test'
import { counterDef } from './counter'

const harness = testView(counterDef, { count: 0 })

harness.click('[data-testid="increment"]')

expect(harness.text('[data-testid="display"]')).toBe('1')
harness.unmount()

A complete example

import { describe, it, expect } from 'vitest'
import { component, type SignalComponentDef } from '@llui/dom'
import { testComponent, testView, assertEffects } from '@llui/test'

type State = { count: number }
type Msg = { type: 'inc' } | { type: 'dec' } | { type: 'reset' }
type Effect = { type: 'logged'; level: 'info' | 'warn'; payload: unknown }

const Counter: SignalComponentDef<State, Msg, Effect> = component<State, Msg, Effect>({
  name: 'Counter',
  init: () => [{ count: 0 }, [{ type: 'logged', level: 'info', payload: 'mount' }]],
  update: (state, msg) => {
    switch (msg.type) {
      case 'inc':
        return [{ count: state.count + 1 }, []]
      case 'dec':
        return [{ count: state.count - 1 }, []]
      case 'reset':
        return [{ count: 0 }, [{ type: 'logged', level: 'warn', payload: { reason: 'reset' } }]]
    }
  },
  view: () => [],
})

describe('Counter', () => {
  it('drives state via send, reads effects', () => {
    const harness = testComponent(Counter)
    harness.send({ type: 'inc' })
    harness.send({ type: 'inc' })
    // `send` is synchronous — the reducer has already run and state is applied.
    expect(harness.state.count).toBe(2)

    // assertEffects partial-matches the recorded effect log; init() emits
    // a 'logged' on mount, then nothing for inc/inc.
    assertEffects(harness.effects, [{ type: 'logged', level: 'info', payload: 'mount' }])
  })
})

For DOM-level assertions (clicking buttons, reading text), use testView against a component whose view() renders elements — see the Usage snippet above.

API

testComponent

// @doc-skip — API signature illustration, not runnable code
testComponent(def) => { state, send, flush, effects }

Mount a component definition headlessly. Returns current state snapshot and message dispatch.

testView

// @doc-skip — API signature illustration
testView(def, state?, options?) => ViewHarness<M>

Mount a component into jsdom with full DOM. Returns a harness with DOM query and interaction methods. options is forwarded to mountApp unchanged, minus the two options that would shadow testView's own seed and container (initialState — the state argument is the seed — and hydrate), so a test can run in the mode the app really runs in: with { scheduler: 'raf' } a burst of harness.handle.send(...) coalesces into ONE commit, which harness.handle.flush() forces synchronously. Omitted, the runtime default scheduler: 'sync' applies and every send commits on its own.

| Method | Description | | ------------------------ | ----------------------------------------------- | | .send(msg) | Dispatch a message | | .flush() | Force synchronous update (skip microtask queue) | | .click(selector) | Simulate click on element | | .input(selector, val) | Set input value and fire input event | | .text(selector) | Get textContent of element | | .attr(selector, name) | Get attribute value | | .query(selector) | querySelector on mounted DOM | | .queryAll(selector) | querySelectorAll on mounted DOM | | .fire(selector, event) | Dispatch a custom event | | .unmount() | Tear down the component and clean up |

assertEffects

// @doc-skip — API signature illustration
assertEffects(effects, expected, options?) => void

Partial-match assertion on effect arrays. The lists must be the same length, and each effect must contain everything its expectation names — unspecified keys are ignored, nested arrays match by index with a length check. Provides clear diff output on mismatch.

An expected undefined is an assertion, not a wildcard: { url: undefined } demands the effect carry a url key holding undefined, and fails both for a url with a value and for an effect with no url key at all. To leave a field unconstrained, omit its key.

Pass { exact: true } to also reject keys the expectation does not name (at every level it reaches). Callback fields and keys holding undefined are exempt — they are outside the effect's JSON data. Exact mode is how you assert a key is absent.

propertyTest

// @doc-skip — API signature illustration
propertyTest(def, config) => void

Property-based testing over a component definition: config.messageGenerators produce random message sequences and config.invariants are checked after every step, with automatic shrinking to a minimal failing sequence. An optional config.mount block also mounts the component into a real DOM container and drives the sequence through send/flush, asserting no console.error and an optional assertDom(state, container) after each commit. Every mounted run restores console.error and disposes the handle however it exits, and is swept for timers still armed at dispose() — mount.leaks picks 'warn' (default), 'error', or 'off'.

replayTrace

// @doc-skip — API signature illustration
replayTrace(def, trace) => void

Replay a recorded message trace against a component definition. Asserts state at each step.

The trace's lluiTrace version and its component are checked before the first reducer call, so a trace from another component — or from a future format — fails with a version/identity error instead of a misleading state diff. A trace with no component field is replayed anyway with a warning (older exports predate the field); only a component that is present and different is an error.

emulateBlurOnRemoval / withBlurOnRemoval

// @doc-skip — API signature illustration
emulateBlurOnRemoval(doc?) => () => void   // returns an uninstall fn
withBlurOnRemoval(fn, doc?) => ReturnType<fn>

Browser-faithful blur emulation for jsdom. The HTML "removing steps" run a focus fixup: when the focused element (or an ancestor) is removed from the document, real browsers synchronously fire blur then focusout on it. jsdom resets document.activeElement but fires no events, so the most reentrancy-prone view pattern — an inline-edit <input> whose onBlur commits, inside a branch arm the commit itself swaps out — can't be exercised on its real path.

emulateBlurOnRemoval() patches removeChild / remove / replaceChild to dispatch the missing events synchronously, in browser order. It returns an uninstall function (call it in afterEach); withBlurOnRemoval(fn) scopes the patch around fn and always uninstalls.

import { emulateBlurOnRemoval } from '@llui/test'

it('commits an inline edit when the focused input is swapped out', () => {
  const uninstall = emulateBlurOnRemoval()
  // …focus the input, trigger the arm swap; blur now fires synchronously…
  uninstall()
})