or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

async.mdevents.mdindex.mdqueries.mdrendering.md
tile.json

tessl/npm-testing-library--vue

Simple and complete Vue DOM testing utilities that encourage good testing practices

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@testing-library/vue@8.1.x

To install, run

npx @tessl/cli install tessl/npm-testing-library--vue@8.1.0

index.mddocs/

Vue Testing Library

Vue Testing Library is a lightweight adapter built on top of DOM Testing Library and @vue/test-utils. It provides simple and complete Vue.js testing utilities that encourage good testing practices by focusing on testing components the way users interact with them.

Package Information

  • Package Name: @testing-library/vue
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install @testing-library/vue --save-dev

Core Imports

import { 
  render, 
  screen, 
  fireEvent, 
  cleanup,
  waitFor,
  waitForElementToBeRemoved,
  within,
  configure,
  getConfig,
  prettyDOM,
  logRoles,
  getRoles
} from "@testing-library/vue";

For CommonJS:

const { 
  render, 
  screen, 
  fireEvent, 
  cleanup,
  waitFor,
  waitForElementToBeRemoved,
  within,
  configure,
  getConfig,
  prettyDOM,
  logRoles,
  getRoles
} = require("@testing-library/vue");

All DOM Testing Library queries are also available:

import {
  // Single element queries
  getByRole, getByLabelText, getByPlaceholderText, getByText,
  getByDisplayValue, getByAltText, getByTitle, getByTestId,
  
  // Multiple element queries  
  getAllByRole, getAllByLabelText, getAllByPlaceholderText, getAllByText,
  getAllByDisplayValue, getAllByAltText, getAllByTitle, getAllByTestId,
  
  // Null-returning queries
  queryByRole, queryByLabelText, queryByPlaceholderText, queryByText,
  queryByDisplayValue, queryByAltText, queryByTitle, queryByTestId,
  
  // Multiple null-returning queries
  queryAllByRole, queryAllByLabelText, queryAllByPlaceholderText, queryAllByText,
  queryAllByDisplayValue, queryAllByAltText, queryAllByTitle, queryAllByTestId,
  
  // Async queries
  findByRole, findByLabelText, findByPlaceholderText, findByText,
  findByDisplayValue, findByAltText, findByTitle, findByTestId,
  
  // Multiple async queries
  findAllByRole, findAllByLabelText, findAllByPlaceholderText, findAllByText,
  findAllByDisplayValue, findAllByAltText, findAllByTitle, findAllByTestId
} from "@testing-library/vue";

Automatic cleanup (no import needed):

// Automatic cleanup is enabled by default
// Set VTL_SKIP_AUTO_CLEANUP=true to disable

Basic Usage

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

// Render a Vue component
const { getByRole } = render(Button, {
  props: { label: "Click me" }
});

// Query elements using DOM Testing Library queries
const button = screen.getByRole("button", { name: "Click me" });

// Simulate user interactions
await fireEvent.click(button);

// Assert behavior
expect(button).toBeInTheDocument();

Architecture

Vue Testing Library follows the testing philosophy of DOM Testing Library, built around several key components:

  • Rendering System: render function that mounts Vue components in a testing environment using @vue/test-utils
  • Query System: Complete set of query functions inherited from DOM Testing Library for finding elements
  • Event System: Vue-specific fireEvent implementation that handles Vue's async DOM updates
  • Screen Object: Pre-bound queries for convenient element selection
  • Cleanup System: Automatic component unmounting and DOM cleanup between tests

Capabilities

Component Rendering

Core functionality for rendering Vue components in tests with full control over props, slots, and mounting options.

function render<C>(
  TestComponent: C,
  options?: RenderOptions<C>
): RenderResult;

interface RenderOptions<C> {
  props?: ComponentProps<C>;
  slots?: ExtractSlots<C>;
  container?: Element;
  baseElement?: Element;
  global?: {
    plugins?: any[];
    mixins?: any[];
    mocks?: Record<string, unknown>;
    provide?: Record<string | symbol, unknown>;
    components?: Record<string, Component>;
    directives?: Record<string, Directive>;
    stubs?: Record<string, any>;
    config?: {
      globalProperties?: Record<string, any>;
      optionMergeStrategies?: Record<string, any>;
    };
  };
}

Component Rendering

Element Queries

Complete set of query functions for finding elements by user-visible characteristics like role, text, and labels.

// Single element queries (throw if no match)
function getByRole(role: string, options?: ByRoleOptions): HTMLElement;
function getByText(text: string | RegExp, options?: ByTextOptions): HTMLElement;
function getByLabelText(text: string | RegExp, options?: ByLabelTextOptions): HTMLElement;

// Single element queries (return null if no match)  
function queryByRole(role: string, options?: ByRoleOptions): HTMLElement | null;
function queryByText(text: string | RegExp, options?: ByTextOptions): HTMLElement | null;

// Async queries (wait for element to appear)
function findByRole(role: string, options?: ByRoleOptions): Promise<HTMLElement>;
function findByText(text: string | RegExp, options?: ByTextOptions): Promise<HTMLElement>;

Element Queries

Event Simulation

Vue-specific event firing utilities that properly handle Vue's asynchronous DOM updates and form interactions.

interface VueFireEventObject {
  (element: Element, event: Event): Promise<void>;
  click(element: Element, options?: MouseEventInit): Promise<void>;
  change(element: Element, options?: EventInit): Promise<void>;
  input(element: Element, options?: InputEventInit): Promise<void>;
  touch(element: Element): Promise<void>;
  update(element: Element, value?: string): Promise<void>;
}

declare const fireEvent: VueFireEventObject;

Event Simulation

Async Utilities

Utilities for waiting for asynchronous operations and DOM changes in Vue components.

function waitFor<T>(
  callback: () => T | Promise<T>,
  options?: {
    container?: Element;
    timeout?: number;
    interval?: number;
    onTimeout?: (error: Error) => Error;
    mutationObserverOptions?: MutationObserverInit;
  }
): Promise<T>;

function waitForElementToBeRemoved<T>(
  element: Element | Element[] | (() => Element | Element[] | null),
  options?: {
    container?: Element;
    timeout?: number;
    interval?: number;
    onTimeout?: (error: Error) => Error;
    mutationObserverOptions?: MutationObserverInit;
  }
): Promise<void>;

Async Utilities

Configuration and Debugging

Configuration utilities and debugging helpers for customizing library behavior and troubleshooting tests.

function configure(options: {
  testIdAttribute?: string;
  asyncUtilTimeout?: number;
  defaultHidden?: boolean;
  defaultIgnore?: string;
  showOriginalStackTrace?: boolean;
  throwSuggestions?: boolean;
}): void;

function getConfig(): {
  testIdAttribute: string;
  asyncUtilTimeout: number;
  defaultHidden: boolean;
  defaultIgnore: string;
  showOriginalStackTrace: boolean;
  throwSuggestions: boolean;
};

function prettyDOM(
  dom?: Element | HTMLDocument,
  maxLength?: number,
  options?: PrettyDOMOptions
): string | false;

function logRoles(container: HTMLElement, options?: { hidden?: boolean }): void;

function getRoles(container: HTMLElement): { [role: string]: HTMLElement[] };

Auto-cleanup

Automatic component cleanup functionality that runs after each test to ensure test isolation.

// Automatically imported cleanup - no manual setup required
// Controlled by VTL_SKIP_AUTO_CLEANUP environment variable

Types

interface RenderResult {
  container: Element;
  baseElement: Element;
  debug: (element?: Element | Element[], maxLength?: number) => void;
  unmount(): void;
  html(): string;
  emitted<T = unknown>(): Record<string, T[]>;
  emitted<T = unknown>(name?: string): T[];
  rerender(props: object): Promise<void>;
  // All query functions from DOM Testing Library
  getByRole: (role: string, options?: ByRoleOptions) => HTMLElement;
  queryByRole: (role: string, options?: ByRoleOptions) => HTMLElement | null;
  findByRole: (role: string, options?: ByRoleOptions) => Promise<HTMLElement>;
  // ... all other query functions
}

interface PrettyDOMOptions {
  highlight?: boolean;
  maxDepth?: number;
  min?: boolean;
  plugins?: any[];
  printFunctionName?: boolean;
  theme?: any;
}

interface ByRoleOptions {
  name?: string | RegExp;
  hidden?: boolean;
  description?: string | RegExp;
  expanded?: boolean;
  checked?: boolean;
  pressed?: boolean;
  selected?: boolean;
  level?: number;
  current?: boolean | string;
  exact?: boolean;
}

interface ByTextOptions {
  exact?: boolean;
  normalizer?: (text: string) => string;
  selector?: string;
}

interface ByLabelTextOptions {
  selector?: string;
  exact?: boolean;
  normalizer?: (text: string) => string;
}

interface ByPlaceholderTextOptions {
  exact?: boolean;
  normalizer?: (text: string) => string;
}

interface ByAltTextOptions {
  exact?: boolean;
  normalizer?: (text: string) => string;
}

interface ByTitleOptions {
  exact?: boolean;
  normalizer?: (text: string) => string;
}

interface ByDisplayValueOptions {
  exact?: boolean;
  normalizer?: (text: string) => string;
}

interface ByTestIdOptions {
  exact?: boolean;
  normalizer?: (text: string) => string;
}