ReviewOS

stacks/stx

testing: ship a DOM runtime shim compatible with happy-dom + Vitest so components can be unit-tested end-to-end

#1741
Closed glennmichael123 opened this 22 days ago · 0 comments
22 days ago

Problem

stx today has no end-to-end component testing story. The maintainer documented this in their own #1737 close comment:

"The signals runtime is written against real-browser DOM semantics that very-happy-dom (our test DOM) doesn't provide, so processElement can't be driven in a unit harness:

  1. Node.ELEMENT_NODE is undefined in happy-dom → el.nodeType !== Node.ELEMENT_NODE is 1 !== undefined → processElement bails on every element.
  2. After polyfilling the nodeType constants, el.attributes in very-happy-dom is a Map, not a NamedNodeMap — so Array.from(el.attributes)[i].name is undefined and the attribute loop throws."

The maintainer subsequently built a shim (test-utils/dom-runtime-shim.ts, commit b2d29ca) to bridge these gaps for their own internal testing. But adopters don't have access to that shim, and there's no documented way to test a component against a real-DOM-faithful environment.

This means:

  • Adopters can't write component-level integration tests (mount a component, assert on rendered DOM, fire events, assert on updates)
  • Adopters can't write tests for their own :if/:else chains (the very behavior #1734 and #1737 are about)
  • Adopters can't validate hydration matches across SSR + client runtime
  • Every bug is regression-tested at the end-to-end Playwright level instead of fast unit-level

Proposed approach

Ship the shim publicly as @stacksjs/testing/dom:

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import { stxDomEnvironment } from '@stacksjs/testing/dom'

export default defineConfig({
  test: {
    environment: stxDomEnvironment,   // happy-dom + the shim
  },
})
// my-component.test.ts
import { mount } from '@stacksjs/testing'
import { state } from '@stacksjs/stx'
import MyComponent from './MyComponent.stx'

test('shows skeleton while loading, list when loaded', async () => {
  const loading = state(true)
  const items = state<string[]>([])
  const { container } = mount(MyComponent, { props: { loading, items } })

  expect(container.querySelector('[data-skeleton]')).toBeVisible()
  expect(container.querySelector('[data-list]')).toBeHidden()

  loading.set(false)
  items.set(['a', 'b'])
  await flushEffects()

  expect(container.querySelector('[data-skeleton]')).toBeHidden()
  expect(container.querySelector('[data-list]')).toBeVisible()
  expect(container.querySelectorAll('[data-list] li')).toHaveLength(2)
})

Required surface

  • mount(Component, { props, scope }) — instantiate a component in the test DOM, return container + scope handle
  • flushEffects() — drain pending reactive effects so assertions see post-update state
  • fireEvent.click(el) / fireEvent.input(el, { value: 'x' }) — standard event helpers
  • findByText / findByRole / queryByText — DOM Testing Library-style queries
  • unmount() — clean up subscribers + DOM

This is the React Testing Library / Vue Test Utils shape — adopters from either ecosystem transfer immediately.

Prior art

  • React Testing Library — the de-facto React testing primitive
  • Vue Test Utils — Vue equivalent
  • @testing-library/svelte — Svelte version
  • Cypress Component Testing — heavier alternative
  • Playwright Component Tests — browser-real but slower

Every modern framework has at least one. Stx has zero.

Impact

  • Adopter test coverage: today's bench-review has ZERO component tests because there's no way to write them. With this primitive, every component gets test coverage in minutes.
  • Bug-class prevention: regression tests for things like #1733/#1734/#1737 become routine — adopters can write them, not just framework maintainers.
  • CI reliability: component-level unit tests are 100× faster than Playwright e2e for the same coverage.

Phasing

  • Phase 1: Public @stacksjs/testing/dom package exposing the maintainer's existing test-utils/dom-runtime-shim.ts
  • Phase 2: mount / unmount / flushEffects helpers
  • Phase 3: Query helpers (findByText etc.) matching DOM Testing Library shape
  • Phase 4: Snapshot testing for reactive scope state

Happy to PR Phase 1 — most of the work is "expose what already exists, document, publish."

Sign in to comment on this issue.