{"id":14256,"library":"vitest-dom","title":"Vitest DOM Matchers","description":"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.","status":"active","version":"0.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/chaance/vitest-dom","tags":["javascript"],"install":[{"cmd":"npm install vitest-dom","lang":"bash","label":"npm"},{"cmd":"yarn add vitest-dom","lang":"bash","label":"yarn"},{"cmd":"pnpm add vitest-dom","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime peer dependency for test runner and `expect` functionality.","package":"vitest","optional":false}],"imports":[{"note":"Imports all DOM matchers as a single object for manual extension with `expect.extend(matchers)`.","wrong":"const matchers = require('vitest-dom/matchers');","symbol":"* as matchers","correct":"import * as matchers from 'vitest-dom/matchers';"},{"note":"Automatically extends Vitest's `expect` with DOM matchers. This is the recommended approach for simpler setup, especially with TypeScript for automatic type inclusion.","wrong":"require('vitest-dom/extend-expect');","symbol":"extend-expect","correct":"import 'vitest-dom/extend-expect';"},{"note":"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.","wrong":"import { ToHaveTextContent } from 'vitest-dom/extend-expect';","symbol":"TypeScript types","correct":"/// <reference types=\"vitest-dom/extend-expect\" />"}],"quickstart":{"code":"import { defineConfig } from 'vitest/config';\nimport path from 'path';\n\n// vitest.config.ts\nexport default defineConfig({\n  test: {\n    environment: 'happy-dom', // or 'jsdom'\n    setupFiles: [path.resolve(__dirname, './vitest-setup.ts')],\n  },\n});\n\n// vitest-setup.ts\nimport 'vitest-dom/extend-expect';\n\n// my-component.test.ts\nimport { render, screen } from '@testing-library/vue'; // Example with Vue Testing Library\nimport MyComponent from './MyComponent.vue';\nimport { expect } from 'vitest';\n\ndescribe('MyComponent', () => {\n  it('should render with a greeting', () => {\n    render(MyComponent, { props: { name: 'World' } });\n    expect(screen.getByText('Hello, World!')).toBeInTheDocument();\n    expect(screen.getByRole('heading')).toHaveTextContent('Hello, World!');\n    expect(screen.getByRole('button')).toBeDisabled();\n  });\n});","lang":"typescript","description":"Demonstrates installation, configuration with `setupFiles` in `vitest.config.ts`, and basic usage of `vitest-dom` matchers in a component test file."},"warnings":[{"fix":"Always use `vitest-dom` when working with Vitest to ensure correct types and integrations. Only use `@testing-library/jest-dom` with Jest.","message":"As 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Pin your dependency to an exact version (`~0.1.x`) and thoroughly review changelogs when upgrading, especially before `1.0.0` is released.","message":"Being 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.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Ensure your `vitest.config.js` includes `test: { environment: 'jsdom' }` or `test: { environment: 'happy-dom' }`. Refer to Vitest documentation for environment configuration.","message":"Properly 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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`.","message":"If 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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'/jest-dom':25,107 '0.1.1':53 '1.0.0':64 'api':32 'assert':12 'avoid':97 'break':68 'chang':69 'clash':99 'could':70 'current':49 'custom':8 'dedic':90 'develop':61 'differenti':87 'direct':19,108 'dom':2,6,18 'drop':37 'drop-in':36 'earli':60 'environ':94 'even':75 'exist':41 'fork':20 'implement':30 'impli':66 'indic':54 'javascript':111 'jest':45 'librari':24,106 'major':81 'make':33 'matcher':3,10 'minor':73 'occur':71 'patch':76 'potenti':98 'pre':63 'primari':86 'provid':7 'reach':84 'releas':77 'replac':39 'share':27 'stabl':50,80 'stage':62 'state':15 'still':57 'support':91 'test':23,42,105 'testing-librari':22,104 'transit':43 'tri':101 'type':96 'use':103 'version':51,82 'vitest':1,5,9,47,93,110 'vitest-dom':4","created_at":"2026-04-20T01:58:45.947977+00:00","updated_at":"2026-04-20T01:58:45.947977+00:00","problems":[{"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.","cause":"Vitest's `expect` object has not been extended with `vitest-dom` matchers, or TypeScript types are missing.","error":"Property 'toBeInTheDocument' does not exist on type 'Assertion<any>'."},{"fix":"Add `test: { environment: 'jsdom' }` or `test: { environment: 'happy-dom' }` to your `vitest.config.js`.","cause":"Vitest is running in a Node.js environment without a DOM implementation.","error":"Error: Neither 'document' nor 'window' are defined. This usually happens when the 'testEnvironment' is not configured correctly."},{"fix":"Make sure `import { expect } from 'vitest';` is present before calling `expect.extend()`, or use the `import 'vitest-dom/extend-expect';` convenience import.","cause":"Attempting to use `expect.extend` before `vitest`'s `expect` object is available or correctly imported.","error":"TypeError: Cannot read properties of undefined (reading 'extend')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/chaance/vitest-dom","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vitest-dom","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}