CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-testing-library--vue

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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;
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@testing-library/vue@8.1.x
Publish Source
CLI
Badge
tessl/npm-testing-library--vue badge