tessl/npm-testing-library--vue

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

—

Pending

Overview

Eval results

Files

Element Queries

Name: tessl/npm-testing-library--vue
Author: tessl

Complete set of query functions for finding elements by user-visible characteristics like role, text, and labels. All queries are inherited from DOM Testing Library and work seamlessly with Vue components.

Capabilities

Query Types

Vue Testing Library provides three types of queries for each search method:

getBy*: Returns element, throws error if not found or multiple found
queryBy*: Returns element or null if not found, throws if multiple found
findBy*: Returns Promise<Element>, waits for element to appear

By Role Queries

Find elements by their accessible role. This is the recommended query method as it most closely matches how users and assistive technologies interact with elements.

/**
 * Get element by ARIA role (recommended query method)
 * @param role - ARIA role name
 * @param options - Additional filtering options
 * @returns HTMLElement matching the role
 */
function getByRole(role: string, options?: ByRoleOptions): HTMLElement;
function queryByRole(role: string, options?: ByRoleOptions): HTMLElement | null;
function findByRole(role: string, options?: ByRoleOptions): Promise<HTMLElement>;
function getAllByRole(role: string, options?: ByRoleOptions): HTMLElement[];
function queryAllByRole(role: string, options?: ByRoleOptions): HTMLElement[];
function findAllByRole(role: string, options?: ByRoleOptions): Promise<HTMLElement[]>;

interface ByRoleOptions {
  /** Filter by accessible name */
  name?: string | RegExp;
  /** Include hidden elements */
  hidden?: boolean;
  /** Filter by description */
  description?: string | RegExp;
  /** Filter by expanded state */
  expanded?: boolean;
  /** Filter by checked state */
  checked?: boolean;
  /** Filter by pressed state */
  pressed?: boolean;
  /** Filter by selected state */
  selected?: boolean;
  /** Filter by level (for headings) */
  level?: number;
  /** Filter by current state */
  current?: boolean | string;
  /** Exact match for name */
  exact?: boolean;
}

Usage Examples:

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

// Find button by role
const button = screen.getByRole("button");
const submitButton = screen.getByRole("button", { name: "Submit" });

// Find heading by level
const mainHeading = screen.getByRole("heading", { level: 1 });

// Find checkbox by checked state
const checkedBox = screen.getByRole("checkbox", { checked: true });

By Text Queries

Find elements by their text content.

/**
 * Get element by text content
 * @param text - Text to search for (string or regex)
 * @param options - Additional options
 * @returns HTMLElement containing the text
 */
function getByText(text: string | RegExp, options?: ByTextOptions): HTMLElement;
function queryByText(text: string | RegExp, options?: ByTextOptions): HTMLElement | null;
function findByText(text: string | RegExp, options?: ByTextOptions): Promise<HTMLElement>;
function getAllByText(text: string | RegExp, options?: ByTextOptions): HTMLElement[];
function queryAllByText(text: string | RegExp, options?: ByTextOptions): HTMLElement[];
function findAllByText(text: string | RegExp, options?: ByTextOptions): Promise<HTMLElement[]>;

interface ByTextOptions {
  /** Exact text match */
  exact?: boolean;
  /** Ignore case when matching */
  normalizer?: (text: string) => string;
  /** Custom selector for container */
  selector?: string;
}

By Label Text Queries

Find form elements by their associated label text.

/**
 * Get form element by label text
 * @param text - Label text to search for
 * @param options - Additional options
 * @returns HTMLElement associated with the label
 */
function getByLabelText(text: string | RegExp, options?: ByLabelTextOptions): HTMLElement;
function queryByLabelText(text: string | RegExp, options?: ByLabelTextOptions): HTMLElement | null;
function findByLabelText(text: string | RegExp, options?: ByLabelTextOptions): Promise<HTMLElement>;
function getAllByLabelText(text: string | RegExp, options?: ByLabelTextOptions): HTMLElement[];
function queryAllByLabelText(text: string | RegExp, options?: ByLabelTextOptions): HTMLElement[];
function findAllByLabelText(text: string | RegExp, options?: ByLabelTextOptions): Promise<HTMLElement[]>;

interface ByLabelTextOptions {
  /** Custom selector for form elements */
  selector?: string;
  /** Exact text match */
  exact?: boolean;
  /** Text normalizer function */
  normalizer?: (text: string) => string;
}

By Placeholder Text Queries

Find form elements by their placeholder text.

/**
 * Get element by placeholder text
 * @param text - Placeholder text to search for
 * @param options - Additional options
 * @returns HTMLElement with matching placeholder
 */
function getByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): HTMLElement;
function queryByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): HTMLElement | null;
function findByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): Promise<HTMLElement>;
function getAllByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): HTMLElement[];
function queryAllByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): HTMLElement[];
function findAllByPlaceholderText(text: string | RegExp, options?: ByPlaceholderTextOptions): Promise<HTMLElement[]>;

interface ByPlaceholderTextOptions {
  /** Exact text match */
  exact?: boolean;
  /** Text normalizer function */
  normalizer?: (text: string) => string;
}

By Alt Text Queries

Find elements (typically images) by their alt attribute.

/**
 * Get element by alt text
 * @param text - Alt text to search for
 * @param options - Additional options
 * @returns HTMLElement with matching alt text
 */
function getByAltText(text: string | RegExp, options?: ByAltTextOptions): HTMLElement;
function queryByAltText(text: string | RegExp, options?: ByAltTextOptions): HTMLElement | null;
function findByAltText(text: string | RegExp, options?: ByAltTextOptions): Promise<HTMLElement>;
function getAllByAltText(text: string | RegExp, options?: ByAltTextOptions): HTMLElement[];
function queryAllByAltText(text: string | RegExp, options?: ByAltTextOptions): HTMLElement[];
function findAllByAltText(text: string | RegExp, options?: ByAltTextOptions): Promise<HTMLElement[]>;

interface ByAltTextOptions {
  /** Exact text match */
  exact?: boolean;
  /** Text normalizer function */
  normalizer?: (text: string) => string;
}

By Title Queries

Find elements by their title attribute.

/**
 * Get element by title attribute
 * @param text - Title text to search for
 * @param options - Additional options
 * @returns HTMLElement with matching title
 */
function getByTitle(text: string | RegExp, options?: ByTitleOptions): HTMLElement;
function queryByTitle(text: string | RegExp, options?: ByTitleOptions): HTMLElement | null;
function findByTitle(text: string | RegExp, options?: ByTitleOptions): Promise<HTMLElement>;
function getAllByTitle(text: string | RegExp, options?: ByTitleOptions): HTMLElement[];
function queryAllByTitle(text: string | RegExp, options?: ByTitleOptions): HTMLElement[];
function findAllByTitle(text: string | RegExp, options?: ByTitleOptions): Promise<HTMLElement[]>;

interface ByTitleOptions {
  /** Exact text match */
  exact?: boolean;
  /** Text normalizer function */
  normalizer?: (text: string) => string;
}

By Display Value Queries

Find form elements by their current value.

/**
 * Get form element by display value
 * @param text - Value to search for
 * @param options - Additional options
 * @returns HTMLElement with matching value
 */
function getByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): HTMLElement;
function queryByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): HTMLElement | null;
function findByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): Promise<HTMLElement>;
function getAllByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): HTMLElement[];
function queryAllByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): HTMLElement[];
function findAllByDisplayValue(text: string | RegExp, options?: ByDisplayValueOptions): Promise<HTMLElement[]>;

interface ByDisplayValueOptions {
  /** Exact text match */
  exact?: boolean;
  /** Text normalizer function */
  normalizer?: (text: string) => string;
}

By Test ID Queries

Find elements by their test ID attribute (use as last resort).

/**
 * Get element by test ID (last resort)
 * @param testId - Test ID to search for
 * @param options - Additional options
 * @returns HTMLElement with matching test ID
 */
function getByTestId(testId: string, options?: ByTestIdOptions): HTMLElement;
function queryByTestId(testId: string, options?: ByTestIdOptions): HTMLElement | null;
function findByTestId(testId: string, options?: ByTestIdOptions): Promise<HTMLElement>;
function getAllByTestId(testId: string, options?: ByTestIdOptions): HTMLElement[];
function queryAllByTestId(testId: string, options?: ByTestIdOptions): HTMLElement[];
function findAllByTestId(testId: string, options?: ByTestIdOptions): Promise<HTMLElement[]>;

interface ByTestIdOptions {
  /** Exact match */
  exact?: boolean;
  /** Text normalizer function */
  normalizer?: (text: string) => string;
}

Utility Objects

Screen Object

Pre-bound queries for the entire document, eliminating the need to destructure from render results.

/**
 * Screen object with all query functions bound to document.body
 */
declare const screen: {
  // All query functions
  getByRole(role: string, options?: ByRoleOptions): HTMLElement;
  queryByRole(role: string, options?: ByRoleOptions): HTMLElement | null;
  findByRole(role: string, options?: ByRoleOptions): Promise<HTMLElement>;
  getAllByRole(role: string, options?: ByRoleOptions): HTMLElement[];
  queryAllByRole(role: string, options?: ByRoleOptions): HTMLElement[];
  findAllByRole(role: string, options?: ByRoleOptions): Promise<HTMLElement[]>;
  // ... all other query functions
  
  // Debugging utilities
  debug(element?: Element | Element[], maxLength?: number): void;
  logTestingPlaygroundURL(element?: Element): void;
};

Usage Example:

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

render(MyComponent);

// Use screen instead of destructuring from render result
const button = screen.getByRole("button");
const input = screen.getByLabelText("Email");

Within Function

Create scoped queries bound to a specific element.

/**
 * Get queries bound to a specific element
 * @param element - Element to bind queries to
 * @returns Object with all query functions scoped to the element
 */
function within(element: Element): {
  getByRole(role: string, options?: ByRoleOptions): HTMLElement;
  queryByRole(role: string, options?: ByRoleOptions): HTMLElement | null;
  // ... all other query functions
};

Usage Example:

import { render, screen, within } from "@testing-library/vue";

const form = screen.getByRole("form");
const withinForm = within(form);

// Queries are now scoped to the form element
const submitButton = withinForm.getByRole("button", { name: "Submit" });

Install with Tessl CLI

npx tessl i tessl/npm-testing-library--vue

docs