DOCSEARCHbyAlgolia
Submit Docs

Vue Testing Library

repository·main·Indexed 22 days ago

https://github.com/testing-library/vue-testing-library

A lightweight adapter built on top of DOM Testing Library and @vue/test-utils that provides utilities for testing Vue.js components. It encourages DOM-centric testing practices by focusing on DOM nodes rather than component instances to resemble real user interactions. Supports Vue 3 and Vue 2 (version 5), and requires TypeScript 4.X or higher.

Tokens
1.2K
Snippets
5
Records
10
Agent score
28%

What's inside @testing-library/vue

  1. Guiding Principles of Vue Testing Library

    main

    Vue Testing Library is designed to encourage testing practices that resemble how software is actually used. Its core principles are:

    1. DOM-centric testing: Utilities deal with DOM nodes rather than component instances. You should avoid testing component internal state or instances directly.
    2. Versatility: Utilities are useful for testing both individual components and full Vue applications.
    3. Simplicity: APIs are designed to be simple, flexible, and lightweight.

  3. Install @testing-library/vue

    main

    Install Vue Testing Library as a development dependency using npm.

    For Vue 3:

    npm install --save-dev @testing-library/vue

    Note: This has peer dependencies for Vue 3 and @vue/compiler-sfc.

    For Vue 2: If you are using Vue 2, install version 5:

    npm install --save-dev @testing-library/vue@^5

    Recommended Additions:

    • Install jest-dom to use custom matchers like .toBeInTheDocument().

  4. Basic usage example with render, screen, and fireEvent

    main

    This example demonstrates how to render a Vue component, query elements using screen, and simulate user interactions with fireEvent.

    • render(Component): Renders the component into the document and binds available queries to screen.
    • screen.queryByText(text): Returns the first matching node or null.
    • screen.getByText(text): Returns the first matching node or throws an error.
    • fireEvent.click(element): Simulates a click event on the specified element (returns a Promise).

    It is recommended to use getByRole (e.g., screen.getByRole('button', { name: 'increment' })) as a more robust alternative to text-based queries.

    import {render, screen, fireEvent} from '@testing-library/vue'
import Button from './Button'

test('increments value on click', async () => {
  render(Button)

  expect(screen.queryByText('Times clicked: 0')).toBeTruthy()

  const button = screen.getByText('increment')

  await fireEvent.click(button)
  await fireEvent.click(button)

  expect(screen.queryByText('Times clicked: 2')).toBeTruthy()
})

  5. Configure automatic cleanup behavior

    main

    By default, if your test runner supports afterEach (like Jest or Vitest), @testing-library/vue automatically calls cleanup() after every test to ensure isolation.

    If you need to disable this automatic behavior, set the environment variable VTL_SKIP_AUTO_CLEANUP to 'true'.

    # Example: Disabling auto-cleanup in your environment
VTL_SKIP_AUTO_CLEANUP=true npm test

  7. Use render() to test Vue components

    main

    The render function is the primary utility for testing Vue components. It creates a container and renders the component into the DOM, returning utilities to interact with the rendered output.

    import { render } from '@testing-library/vue'

// Example usage (conceptual based on export)
const { container } = render(MyComponent)

  10. Use fireEvent() to trigger DOM events

    main

    The fireEvent utility allows you to trigger DOM events (like click, change, or input) on elements within your rendered Vue component to simulate user interaction.

    import { render, fireEvent } from '@testing-library/vue'

// Example usage (conceptual based on export)
const { getByText } = render(MyComponent)
const button = getByText('Click me')
await fireEvent.click(button)