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, soprocessElementcan't be driven in a unit harness:
Node.ELEMENT_NODEisundefinedin happy-dom →el.nodeType !== Node.ELEMENT_NODEis1 !== undefined→processElementbails on every element.- After polyfilling the nodeType constants,
el.attributesin very-happy-dom is a Map, not a NamedNodeMap — soArray.from(el.attributes)[i].nameis 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/:elsechains (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 handleflushEffects()— drain pending reactive effects so assertions see post-update statefireEvent.click(el)/fireEvent.input(el, { value: 'x' })— standard event helpersfindByText/findByRole/queryByText— DOM Testing Library-style queriesunmount()— 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/dompackage exposing the maintainer's existingtest-utils/dom-runtime-shim.ts - Phase 2:
mount/unmount/flushEffectshelpers - Phase 3: Query helpers (
findByTextetc.) 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."