Remix Testing Library

a small wrapper around DOM Testing Library for use with Remix v3

Installation

npm install --save-dev @mcansh/remix-testing-library

pnpm add --save-dev @mcansh/remix-testing-library

yarn add --dev @mcansh/remix-testing-library

You will also need a DOM environment for your test runner. For example, with Vitest and happy-dom:

npm install --save-dev vitest happy-dom

// vitest.config.js
import { defineConfig } from "vitest/config"

export default defineConfig({
	test: {
		environment: "happy-dom",
		globals: true, // required for auto-cleanup after each test
	},
})

Usage

Basic render

import { render, screen } from "@mcansh/remix-testing-library"

it("renders a greeting", () => {
	function Greeting() {
		return (props: { name: string }) => <p>Hello, {props.name}!</p>
	}

	render(<Greeting name="world" />)

	screen.getByText("Hello, world!")
})

Rerendering

import { render, screen } from "@mcansh/remix-testing-library"

it("updates when rerendered with new props", () => {
	function Greeting() {
		return (props: { message: string }) => <div>{props.message}</div>
	}

	const { rerender } = render(<Greeting message="hi" />)
	screen.getByText("hi")

	rerender(<Greeting message="hey" />)
	screen.getByText("hey")
})

Interactive components

Note: The interactive example below uses @testing-library/user-event, which must be installed separately:

npm install --save-dev @testing-library/user-event

import { on, pressEvents, type Handle } from "@remix-run/component"
import { userEvent } from "@testing-library/user-event"
import { render, screen } from "@mcansh/remix-testing-library"

it("increments a counter on click", async () => {
	let user = userEvent.setup()

	function Counter(handle: Handle) {
		let count = 0
		return () => (
			<button
				mix={[
					pressEvents(),
					on(pressEvents.press, async () => {
						count += 1
						await handle.update()
					}),
				]}
			>
				Clicked {count} time{count === 1 ? "" : "s"}
			</button>
		)
	}

	render(<Counter />)

	const button = screen.getByRole("button")
	expect(button.textContent).toBe("Clicked 0 times")

	await user.click(button)

	expect(button.textContent).toBe("Clicked 1 time")
})

API

render(ui, options?)

Renders a Remix component into a container appended to document.body and returns an object with:

| Property | Description | | ---------------------------------- | -------------------------------------------------------------------------------------------------------- | | container | The div element the component was rendered into | | baseElement | document.body (or the custom baseElement option if provided) | | debug(el?, maxLength?, options?) | Logs a pretty-printed DOM snapshot to the console | | rerender(ui) | Re-renders the component with new props | | dispose() | Unmounts the component | | asFragment() | Returns a DocumentFragment snapshot of the current DOM | | ...queries | All DOM Testing Library queries bound to baseElement |

Options:

| Option | Type | Description | | -------------------- | -------------------- | ---------------------------------------------------------------------------------------- | | container | HTMLElement | Custom container element (defaults to a new div appended to baseElement) | | baseElement | HTMLElement | Custom base element for queries (defaults to document.body) | | wrapper | component | Wraps the rendered UI with the given component | | queries | Queries | Custom queries to bind to baseElement (defaults to all @testing-library/dom queries) | | virtualRootOptions | VirtualRootOptions | Options forwarded to createRoot from @remix-run/component |

cleanup()

Unmounts all components rendered with render and removes their containers from document.body. This is called automatically after each test only when a global afterEach or teardown function is available on globalThis. Jest provides this by default; in Vitest, you must enable test.globals: true in your Vitest config — simply importing afterEach in a test file is not sufficient. Import from @mcansh/remix-testing-library/pure to opt out of auto-cleanup.

Pure imports (no auto-cleanup)

If you prefer to manage cleanup yourself, import from the pure entry point:

import { render, cleanup } from "@mcansh/remix-testing-library/pure"

You can also disable auto-cleanup globally by setting the RTL_SKIP_AUTO_CLEANUP environment variable to "true".

Re-exports

@mcansh/remix-testing-library re-exports everything from @testing-library/dom, including all queries (e.g. screen, getByText, findByRole) and utilities (e.g. waitFor, fireEvent).