Vitest Browser Qwik

A modern testing setup demonstrating browser-based testing for Qwik components using Vitest. This project showcases how to effectively test Qwik components with both Client-Side Rendering (CSR) and Server-Side Rendering (SSR), making it perfect for testing complex UI behaviors across environments.

Getting Started

1pnpm add vitest-browser-qwik

Core Features

• render - Client-Side Rendering for interactive component testing
• renderSSR - Server-Side Rendering for testing SSR output and environment contexts
• renderHook - Hook testing utilities (currently only CSR supported)
• All functions are async for predictable testing behavior

Client-Side Rendering Example

1import { render } from 'vitest-browser-qwik'
2import { expect, test } from 'vitest'
3import { Counter } from './components/counter'
4
5test('renders counter with CSR', async () => {
6  const screen = await render(<Counter initialCount={1} />);
7  await expect.element(screen.getByText('Count is 1')).toBeVisible();
8  await screen.getByRole('button', { name: 'Increment' }).click();
9  await expect.element(screen.getByText('Count is 2')).toBeVisible();
10});

Server-Side Rendering Example

1import { renderSSR } from 'vitest-browser-qwik'
2import { expect, test } from 'vitest'
3import { Counter } from './components/counter'
4
5test('renders counter with SSR', async () => {
6  const screen = await renderSSR(<Counter initialCount={5} />);
7  
8  // Test the server-rendered HTML
9  expect(screen.container.innerHTML).toContain('Count is 5');
10  expect(screen.container.innerHTML).toContain('button');
11  
12  // Can also use DOM queries on the content initially rendered by SSR
13  await expect.element(screen.getByText('Count is 5')).toBeVisible();
14});

Hook Testing Example

1import { useSignal } from "@builder.io/qwik";
2import { expect, test } from "vitest";
3import { renderHook } from "vitest-browser-qwik";
4import { useCounter } from "./fixtures/useCounter";
5
6test("should increment counter", async () => {
7	const { result } = await renderHook(() =>
8		useCounter({ countSignal: useSignal(0) }),
9	);
10
11	console.log("RESULT", result);
12
13	await result.increment$();
14
15	expect(result.count.value).toBe(1);
16});

SSR vs CSR

Both render and renderSSR provide the same testing interface, but work differently under the hood:

• render (CSR): Renders components in the browser context
• renderSSR (SSR): Executes components in a Node.js context to generate server-side HTML, then provides that HTML for testing

The SSR approach is unique because it executes your components in a different context than your test files, real server-side rendering behavior in Vitest.

Render Options

The render function accepts an options object as its second parameter:

1interface RenderOptions {
2  // Optional HTMLElement where the component will be rendered
3  container?: HTMLElement;
4  // Optional HTMLElement that serves as the base element (defaults to document.body)
5  baseElement?: HTMLElement;
6}

Example with options:

1import { render } from 'vitest-browser-qwik'
2
3test('renders with custom container', async () => {
4  const customContainer = document.createElement('div');
5  const screen = await render(<MyComponent />, { 
6    container: customContainer 
7  });
8});

Note: renderSSR currently does not support custom render options due to its execution in a separate Node.js context.

Important Notes

• Always await: All functions from vitest-browser-qwik are async and should be awaited for predictable behavior
• SSR Context: renderSSR executes components in a Node.js context separate from your test files, providing true server-side rendering simulation
• Same Interface: Both CSR and SSR provide the same testing interface, making it easy to test both rendering modes

Limitations

• For renderSSR you must always import the component from another file, local components are not supported. This is because this would require importing the vitest context, or moving local components into separate files dynamically, which involves a lot of unwanted complexity.

• In the vitest config there is a hardcoded value for whether or not browser mode is headless. This is because when relying on environment variables, it seems there is an additional cost in the vitest core side that introduces potential race conditions.

Contributing

Feel free to open issues and pull requests. All contributions are welcome!

License

MIT