vitest-browser-qwik

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.

This project uses Qwik v2 to render components, if you want to use v1, please downgrade to vitest-browser-qwik@0.1.0.

Getting Started

npm install -D 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

Vitest Config Setup

Vitest 4+

import { defineConfig } from 'vitest/config'
import { qwikVite } from '@qwik.dev/core/optimizer'
import { playwright } from '@vitest/browser-playwright'

// optional, run the tests in SSR mode
import { testSSR } from 'vitest-browser-qwik/ssr-plugin'

export default defineConfig({
  plugins: [testSSR(), qwikVite()],
  test: {
    browser: {
      enabled: true,
      provider: playwright(),
      instances: [{ browser: 'chromium' }]
    },
  },
})

Vitest 3 (Legacy)

import { defineConfig } from 'vitest/config'
import { qwikVite } from '@qwik.dev/core/optimizer'

// optional, run the tests in SSR mode
import { testSSR } from 'vitest-browser-qwik/ssr-plugin'

export default defineConfig({
  plugins: [testSSR(), qwikVite()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }]
    },
  },
})

Client-Side Rendering Example

import { render } from 'vitest-browser-qwik'
import { expect, test } from 'vitest'
import { Counter } from './components/counter'

test('renders counter with CSR', async () => {
  const screen = await render(<Counter initialCount={1} />);
  await expect.element(screen.getByText('Count is 1')).toBeVisible();
  await screen.getByRole('button', { name: 'Increment' }).click();
  await expect.element(screen.getByText('Count is 2')).toBeVisible();
});

Server-Side Rendering Example

import { renderSSR } from 'vitest-browser-qwik'
import { expect, test } from 'vitest'
import { Counter } from './components/counter'

test('renders counter with SSR', async () => {
  const screen = await renderSSR(<Counter initialCount={5} />);
  
  // Test the server-rendered HTML
  expect(screen.container.innerHTML).toContain('Count is 5');
  expect(screen.container.innerHTML).toContain('button');
  
  // Can also use DOM queries on the content initially rendered by SSR
  await expect.element(screen.getByText('Count is 5')).toBeVisible();
});

Hook Testing Example

import { useSignal } from "@qwik.dev/core";
import { expect, test } from "vitest";
import { renderHook } from "vitest-browser-qwik";
import { useCounter } from "./fixtures/useCounter";

test("should increment counter", async () => {
	const { result } = await renderHook(() =>
		useCounter({ countSignal: useSignal(0) }),
	);

	console.log("RESULT", result);

	await result.increment$();

	expect(result.count.value).toBe(1);
});

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:

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

Example with options:

import { render } from 'vitest-browser-qwik'

test('renders with custom container', async () => {
  const customContainer = document.createElement('div');
  const screen = await render(<MyComponent />, { 
    container: customContainer 
  });
});

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

Compatibility

In testing, we have observed render issues with Vite 5.x. We recommend using Vite 6+. Qwik 1 currently specifies Vite 5.x, but Vite 6.x should work as well.

Limitations

• For renderSSR, if you have a component declared locally in the test file, and you import something in the browser test file that is browser only other than vitest, it will not be available in the SSR context. Make sure to put this in a separate file.

Contributing

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

License

MIT