# Testing cascivo components
How to test UIs built with cascivo using Vitest + Testing Library. cascivo's
own component suite (199 components, `packages/components/src/*/[name].test.tsx`)
uses exactly this stack; the patterns below are lifted from it.
## Setup
```sh
pnpm add -D vitest jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event
```
```ts
// vite.config.ts (or vitest.config.ts)
export default defineConfig({
test: {
environment: 'jsdom',
globals: true,
setupFiles: ['./src/test-setup.ts'],
},
})
```
```ts
// src/test-setup.ts
import '@testing-library/jest-dom'
```
## Basics: render, query by role, interact
Signal-driven components need no special harness — render them and assert on
the DOM like any React component. From cascivo's own `Toggle` suite:
```tsx
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { Toggle } from '@cascivo/react'
it('toggles when clicked (uncontrolled)', async () => {
render()
const toggle = screen.getByRole('switch')
await userEvent.click(toggle)
expect(toggle).toHaveAttribute('aria-checked', 'true')
})
```
Prefer role queries (`getByRole('switch', { name: 'Notifications' })`) —
cascivo components ship full ARIA wiring, so the accessible name/role is the
stable contract to test against, not class names.
## The `useSignals` gotcha
cascivo components call `useSignals()` internally, so **testing the components
themselves just works**. The trap is in _your_ components: any React component
that reads a signal's `.value` during render must call `useSignals()` (from
`@cascivo/core`) as its first statement. Without it the component never
subscribes — in tests the symptom is that handlers fire (spies are called) but
assertions on the rendered output keep seeing the old UI:
```tsx
import { signal, useSignals } from '@cascivo/core'
const count = signal(0) // module-level: no hook subscribes you
function Counter() {
useSignals() // ← without this, the count below never updates on screen
return (
)
}
```
State from a cascivo hook subscribes you on its own — `const [count, setCount] =
useSignalState(0)` needs no `useSignals()`. Write it through `setCount`, not `count.value = …`.
If a test shows a click handler being invoked but the DOM frozen at its initial
state, check `useSignals()` before anything else. (The same bug reproduces in
the browser — see [TROUBLESHOOTING.md](/docs/troubleshooting.md).)
## What to polyfill in jsdom
jsdom does not implement everything cascivo's overlay components touch. These
are the shims cascivo's own suite uses; add the ones your tests hit to your
setup file.
**`