Skip to main content

API

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

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.

OptionDescriptionDefault
containerThe container in which the component is rendered.document.createElement('host')
baseElementThe base element for queries and debug.document.body
queriesCustom Queries.N/A
wrapperThe 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

ResultDescription
baseElementThe base DOM element used for queries.
containerThe DOM element the component is mounted to.
asFragmentConvert the DOM element to a DocumentFragment.
debugLog elements using prettyDOM.
unmountUnmount and destroy the component.
...queriesQuery 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()