API

@noma.to/qwik-testing-library re-exports everything from @testing-library/dom, as well as:

• render
• cleanup

render

Render your component to the DOM with Qwik. By default, when no options are provided, the component will be rendered into a <host> appended to document.body.

import {render} from '@noma.to/qwik-testing-library'
import {MockProvider} from './MockProvider'
import {MyComponent} from './MyComponent'

const result = await render(<MyComponent />, {
  baseElement: document.body,
  container: document.createElement('host'),
  wrapper: MockProvider,
})

Render Options

You may also customize how Qwik Testing Library renders your component. Most of the time, you shouldn't need to modify these options.

Option	Description	Default
container	The container in which the component is rendered.	document.createElement('host')
baseElement	The base element for queries and debug.	document.body
queries	Custom Queries.	N/A
wrapper	The wrapper to provide a context to the component.	N/A

wrapper

You can wrap your component into a wrapper to provide a context and other functionalities needed by the component under test.

import {render} from '@noma.to/qwik-testing-library'
import {QwikCityMockProvider} from '@builder.io/qwik-city'

await render(<MyComponent />, {wrapper: QwikCityMockProvider})

Render Results

Result	Description
baseElement	The base DOM element used for queries.
container	The DOM element the component is mounted to.
asFragment	Convert the DOM element to a DocumentFragment.
debug	Log elements using prettyDOM.
unmount	Unmount and destroy the component.
...queries	Query functions bound to baseElement.

baseElement

The base DOM element that queries are bound to. Corresponds to renderOptions.baseElement. If you do not use renderOptions.baseElement, this will be document.body.

container

The DOM element the component is mounted in. Corresponds to renderOptions.container. If you do not use renderOptions.container, this will be document.createElement('host'). In general, avoid using container directly to query for elements; use testing-library queries instead.

asFragment

Returns a DocumentFragment of your rendered component. This can be useful if you need to avoid live bindings and see how your component reacts to events.

import {component$} from '@builder.io/qwik';
import {render} from '@testing-library/react';
import {userEvent} from "@testing-library/user-event";

const TestComponent = component$(() => {
  const count = useSignal(0);

  return (
    <button onClick$={() => (count.value++))}>
      Click to increase: {count}
    </button>
  )
});

const {getByText, asFragment} = await render(<TestComponent />)
const firstRender = asFragment()

userEvent.click(getByText(/Click to increase/))

// This will snapshot only the difference between the first render, and the
// state of the DOM after the click event.
// See https://github.com/jest-community/snapshot-diff
expect(firstRender).toMatchDiffSnapshot(asFragment())

debug

Log the baseElement or a given element using prettyDOM.

tip

If your baseElement is the default document.body, we recommend using screen.debug.

import {render, screen} from '@noma.to/qwik-testing-library'

const {debug} = await render(<MyComponent />)

const button = screen.getByRole('button')

// log `document.body`
screen.debug()

// log your custom the `baseElement`
debug()

// log a specific element
screen.debug(button)
debug(button)

unmount

Unmount and destroy the Qwik component.

const {unmount} = await render(<MyComponent />)

unmount()

Queries

Query functions bound to the baseElement. If you passed custom queries to render, those will be available instead of the default queries.

tip

If your baseElement is the default document.body, we recommend using screen rather than bound queries.

import {render, screen} from '@noma.to/qwik-testing-library'

const {getByRole} = await render(<MyComponent />)

// query `document.body`
const button = screen.getByRole('button')

// query using a custom `target` or `baseElement`
const button = getByRole('button')

cleanup

Destroy all components and remove any elements added to document.body or renderOptions.baseElement.

import {render, cleanup} from '@noma.to/qwik-testing-library'

// Default: runs after each test
afterEach(() => {
  cleanup()
})

await render(<MyComponent />)

// Called manually for more control
cleanup()