vitest-dom

library0.1.1jsnpmunverified

vitest-dom provides custom Vitest matchers to assert on the state of the DOM, directly forked from `@testing-library/jest-dom`. It shares the same implementation and API, making it a drop-in replacement for existing tests transitioning from Jest to Vitest. The current stable version is `0.1.1`, indicating it's still in its early development stages (pre-1.0.0), which implies that breaking changes could occur in minor or even patch releases before a stable major version is reached. Its primary differentiation is its dedicated support for Vitest environments and types, avoiding potential clashes when trying to use `@testing-library/jest-dom` directly with Vitest.

testing

npm install vitest-dom

github ↗package ↗

INSTALL

IMPORT

SIG · VITEST-DOM

vitest-dom

testingjavascriptv0.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

* as matchers

✓ import * as matchers from 'vitest-dom/matchers';

✗ const matchers = require('vitest-dom/matchers');

Imports all DOM matchers as a single object for manual extension with `expect.extend(matchers)`.

extend-expect

✓ import 'vitest-dom/extend-expect';

✗ require('vitest-dom/extend-expect');

Automatically extends Vitest's `expect` with DOM matchers. This is the recommended approach for simpler setup, especially with TypeScript for automatic type inclusion.

TypeScript types

✓ /// <reference types="vitest-dom/extend-expect" />

✗ import { ToHaveTextContent } from 'vitest-dom/extend-expect';

For explicit type inclusion without `import 'vitest-dom/extend-expect';`, use a reference directive or configure `tsconfig.json` `types` option. Individual matcher types are not typically imported directly by users.

Demonstrates installation, configuration with `setupFiles` in `vitest.config.ts`, and basic usage of `vitest-dom` matchers in a component test file.

import { defineConfig } from 'vitest/config'; import path from 'path'; // vitest.config.ts export default defineConfig({ test: { environment: 'happy-dom', // or 'jsdom' setupFiles: [path.resolve(__dirname, './vitest-setup.ts')], }, }); // vitest-setup.ts import 'vitest-dom/extend-expect'; // my-component.test.ts import { render, screen } from '@testing-library/vue'; // Example with Vue Testing Library import MyComponent from './MyComponent.vue'; import { expect } from 'vitest'; describe('MyComponent', () => { it('should render with a greeting', () => { render(MyComponent, { props: { name: 'World' } }); expect(screen.getByText('Hello, World!')).toBeInTheDocument(); expect(screen.getByRole('heading')).toHaveTextContent('Hello, World!'); expect(screen.getByRole('button')).toBeDisabled(); }); });

Debug

Known issues

gotchaAs a fork of `@testing-library/jest-dom`, users might confuse `vitest-dom` with the original package. While the API is identical, direct usage of `@testing-library/jest-dom` with Vitest can lead to type conflicts or unexpected behavior due to Jest-specific globals.

fix

Always use `vitest-dom` when working with Vitest to ensure correct types and integrations. Only use `@testing-library/jest-dom` with Jest.

affects: >=0.1.0

breakingBeing pre-1.0.0 (current version 0.1.1), `vitest-dom` may introduce breaking changes in minor or even patch versions. The API is based on `@testing-library/jest-dom`'s stable API, but internal implementations or type definitions might evolve rapidly.

fix

Pin your dependency to an exact version (`~0.1.x`) and thoroughly review changelogs when upgrading, especially before `1.0.0` is released.

affects: >=0.1.0

gotchaProperly setting up the Vitest environment (e.g., `jsdom` or `happy-dom`) is crucial for `vitest-dom` to function correctly. If no DOM environment is configured, DOM matchers will fail or throw errors.

fix

Ensure your `vitest.config.js` includes `test: { environment: 'jsdom' }` or `test: { environment: 'happy-dom' }`. Refer to Vitest documentation for environment configuration.

affects: >=0.1.0

gotchaIf manually extending `expect` via `import * as matchers from 'vitest-dom/matchers'; expect.extend(matchers);`, TypeScript users must explicitly include the types either via a `/// <reference />` directive or in `tsconfig.json`'s `types` array.

fix

For automatic type inclusion, use `import 'vitest-dom/extend-expect';`. Otherwise, add `/// <reference types="vitest-dom/extend-expect" />` to your setup file or `"types": ["vitest-dom/extend-expect"]` to `compilerOptions` in `tsconfig.json`.

affects: >=0.1.0

Errors

Common errors & fixes

Property 'toBeInTheDocument' does not exist on type 'Assertion<any>'.

Vitest's `expect` object has not been extended with `vitest-dom` matchers, or TypeScript types are missing.

fix

Ensure `vitest-dom/extend-expect` is imported in a `setupFiles` configured in `vitest.config.js` (and that the setup file is `.ts` for TypeScript). If manually extending, verify `expect.extend(matchers)` is called and types are referenced correctly.

Error: Neither 'document' nor 'window' are defined. This usually happens when the 'testEnvironment' is not configured correctly.

Vitest is running in a Node.js environment without a DOM implementation.

fix

Add `test: { environment: 'jsdom' }` or `test: { environment: 'happy-dom' }` to your `vitest.config.js`.

TypeError: Cannot read properties of undefined (reading 'extend')

Attempting to use `expect.extend` before `vitest`'s `expect` object is available or correctly imported.

fix

Make sure `import { expect } from 'vitest';` is present before calling `expect.extend()`, or use the `import 'vitest-dom/extend-expect';` convenience import.

Upgrade

Version history

0.1.1latest on npm

Audit

Dependencies

vitestrequiredRuntime peer dependency for test runner and `expect` functionality.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/chaance/vitest-dom ↗

packagehttps://www.npmjs.com/package/vitest-dom ↗