tessl/npm-storybook--testing-library

Instrumented version of Testing Library for Storybook Interactions addon

—

Pending

Overview

Eval results

Files

DOM Queries

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

Complete set of Testing Library query functions for finding elements in the DOM. All queries are instrumented for Storybook interaction tracking and follow the Testing Library query pattern: getBy* (throw error), getAllBy* (throw error, return array), queryBy* (return null), queryAllBy* (return empty array), findBy* (async, reject), findAllBy* (async, reject, return array).

Capabilities

getBy* Queries

Synchronous queries that throw an error if no matching element is found. Use these when you expect the element to exist.

/**
 * Find element by ARIA role
 * @param container - Container element to search within
 * @param role - ARIA role to search for
 * @param options - Additional options for role matching
 * @returns Single matching element
 * @throws Error if no element found or multiple elements found
 */
function getByRole(container: HTMLElement, role: string, options?: ByRoleOptions): HTMLElement;

/**
 * Find element by text content
 * @param container - Container element to search within  
 * @param text - Text content to search for (string or regex)
 * @param options - Text matching options
 * @returns Single matching element
 * @throws Error if no element found or multiple elements found
 */
function getByText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement;

/**
 * Find element by test-id attribute
 * @param container - Container element to search within
 * @param testId - Test ID attribute value to search for
 * @param options - Text matching options
 * @returns Single matching element
 * @throws Error if no element found or multiple elements found
 */
function getByTestId(container: HTMLElement, testId: string, options?: SelectorMatcherOptions): HTMLElement;

/**
 * Find element by label text
 * @param container - Container element to search within
 * @param text - Label text to search for (string or regex)
 * @param options - Text matching options
 * @returns Single matching element
 * @throws Error if no element found or multiple elements found
 */
function getByLabelText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement;

/**
 * Find element by placeholder text
 * @param container - Container element to search within
 * @param text - Placeholder text to search for (string or regex)
 * @param options - Text matching options
 * @returns Single matching element
 * @throws Error if no element found or multiple elements found
 */
function getByPlaceholderText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement;

/**
 * Find element by alt attribute
 * @param container - Container element to search within
 * @param text - Alt text to search for (string or regex)
 * @param options - Text matching options
 * @returns Single matching element
 * @throws Error if no element found or multiple elements found
 */
function getByAltText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement;

/**
 * Find element by title attribute
 * @param container - Container element to search within
 * @param text - Title text to search for (string or regex)
 * @param options - Text matching options
 * @returns Single matching element
 * @throws Error if no element found or multiple elements found
 */
function getByTitle(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement;

/**
 * Find form element by display value
 * @param container - Container element to search within
 * @param value - Display value to search for (string or regex)
 * @param options - Text matching options
 * @returns Single matching element
 * @throws Error if no element found or multiple elements found
 */
function getByDisplayValue(container: HTMLElement, value: string | RegExp, options?: SelectorMatcherOptions): HTMLElement;

getAllBy* Queries

Synchronous queries that return an array of all matching elements. Throw an error if no elements are found.

/**
 * Find all elements by ARIA role
 * @param container - Container element to search within
 * @param role - ARIA role to search for
 * @param options - Additional options for role matching
 * @returns Array of matching elements
 * @throws Error if no elements found
 */
function getAllByRole(container: HTMLElement, role: string, options?: ByRoleOptions): HTMLElement[];

/**
 * Find all elements by text content
 * @param container - Container element to search within
 * @param text - Text content to search for (string or regex)
 * @param options - Text matching options
 * @returns Array of matching elements
 * @throws Error if no elements found
 */
function getAllByText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];

/**
 * Find all elements by test-id attribute
 * @param container - Container element to search within
 * @param testId - Test ID attribute value to search for
 * @param options - Text matching options
 * @returns Array of matching elements
 * @throws Error if no elements found
 */
function getAllByTestId(container: HTMLElement, testId: string, options?: SelectorMatcherOptions): HTMLElement[];

/**
 * Find all elements by label text
 * @param container - Container element to search within
 * @param text - Label text to search for (string or regex)
 * @param options - Text matching options
 * @returns Array of matching elements
 * @throws Error if no elements found
 */
function getAllByLabelText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];

/**
 * Find all elements by placeholder text
 * @param container - Container element to search within
 * @param text - Placeholder text to search for (string or regex)
 * @param options - Text matching options
 * @returns Array of matching elements
 * @throws Error if no elements found
 */
function getAllByPlaceholderText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];

/**
 * Find all elements by alt attribute
 * @param container - Container element to search within
 * @param text - Alt text to search for (string or regex)
 * @param options - Text matching options
 * @returns Array of matching elements
 * @throws Error if no elements found
 */
function getAllByAltText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];

/**
 * Find all elements by title attribute
 * @param container - Container element to search within
 * @param text - Title text to search for (string or regex)
 * @param options - Text matching options
 * @returns Array of matching elements
 * @throws Error if no elements found
 */
function getAllByTitle(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];

/**
 * Find all form elements by display value
 * @param container - Container element to search within
 * @param value - Display value to search for (string or regex)
 * @param options - Text matching options
 * @returns Array of matching elements
 * @throws Error if no elements found
 */
function getAllByDisplayValue(container: HTMLElement, value: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];

queryBy* Queries

Synchronous queries that return null if no matching element is found. Use these for optional elements or when you want to check if an element doesn't exist.

/**
 * Query element by ARIA role
 * @param container - Container element to search within
 * @param role - ARIA role to search for
 * @param options - Additional options for role matching
 * @returns Single matching element or null if not found
 */
function queryByRole(container: HTMLElement, role: string, options?: ByRoleOptions): HTMLElement | null;

/**
 * Query element by text content
 * @param container - Container element to search within
 * @param text - Text content to search for (string or regex)
 * @param options - Text matching options
 * @returns Single matching element or null if not found
 */
function queryByText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement | null;

/**
 * Query element by test-id attribute
 * @param container - Container element to search within
 * @param testId - Test ID attribute value to search for
 * @param options - Text matching options
 * @returns Single matching element or null if not found
 */
function queryByTestId(container: HTMLElement, testId: string, options?: SelectorMatcherOptions): HTMLElement | null;

/**
 * Query element by label text
 * @param container - Container element to search within
 * @param text - Label text to search for (string or regex)
 * @param options - Text matching options
 * @returns Single matching element or null if not found
 */
function queryByLabelText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement | null;

/**
 * Query element by placeholder text
 * @param container - Container element to search within
 * @param text - Placeholder text to search for (string or regex)
 * @param options - Text matching options
 * @returns Single matching element or null if not found
 */
function queryByPlaceholderText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement | null;

/**
 * Query element by alt attribute
 * @param container - Container element to search within
 * @param text - Alt text to search for (string or regex)
 * @param options - Text matching options
 * @returns Single matching element or null if not found
 */
function queryByAltText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement | null;

/**
 * Query element by title attribute
 * @param container - Container element to search within
 * @param text - Title text to search for (string or regex)
 * @param options - Text matching options
 * @returns Single matching element or null if not found
 */
function queryByTitle(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement | null;

/**
 * Query form element by display value
 * @param container - Container element to search within
 * @param value - Display value to search for (string or regex)
 * @param options - Text matching options
 * @returns Single matching element or null if not found
 */
function queryByDisplayValue(container: HTMLElement, value: string | RegExp, options?: SelectorMatcherOptions): HTMLElement | null;

/**
 * Query element by any attribute
 * @param container - Container element to search within
 * @param attribute - Attribute name
 * @param value - Attribute value to search for (string or regex)
 * @param options - Text matching options
 * @returns Single matching element or null if not found
 */
function queryByAttribute(container: HTMLElement, attribute: string, value: string | RegExp, options?: SelectorMatcherOptions): HTMLElement | null;

queryAllBy* Queries

Synchronous queries that return an empty array if no matching elements are found.

/**
 * Query all elements by ARIA role
 * @param container - Container element to search within
 * @param role - ARIA role to search for
 * @param options - Additional options for role matching
 * @returns Array of matching elements (empty if none found)
 */
function queryAllByRole(container: HTMLElement, role: string, options?: ByRoleOptions): HTMLElement[];

/**
 * Query all elements by text content
 * @param container - Container element to search within
 * @param text - Text content to search for (string or regex)
 * @param options - Text matching options
 * @returns Array of matching elements (empty if none found)
 */
function queryAllByText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];

/**
 * Query all elements by test-id attribute
 * @param container - Container element to search within
 * @param testId - Test ID attribute value to search for
 * @param options - Text matching options
 * @returns Array of matching elements (empty if none found)
 */
function queryAllByTestId(container: HTMLElement, testId: string, options?: SelectorMatcherOptions): HTMLElement[];

/**
 * Query all elements by label text
 * @param container - Container element to search within
 * @param text - Label text to search for (string or regex)
 * @param options - Text matching options
 * @returns Array of matching elements (empty if none found)
 */
function queryAllByLabelText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];

/**
 * Query all elements by placeholder text
 * @param container - Container element to search within
 * @param text - Placeholder text to search for (string or regex)
 * @param options - Text matching options
 * @returns Array of matching elements (empty if none found)
 */
function queryAllByPlaceholderText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];

/**
 * Query all elements by alt attribute
 * @param container - Container element to search within
 * @param text - Alt text to search for (string or regex)
 * @param options - Text matching options
 * @returns Array of matching elements (empty if none found)
 */
function queryAllByAltText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];

/**
 * Query all elements by title attribute
 * @param container - Container element to search within
 * @param text - Title text to search for (string or regex)
 * @param options - Text matching options
 * @returns Array of matching elements (empty if none found)
 */
function queryAllByTitle(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];

/**
 * Query all form elements by display value
 * @param container - Container element to search within
 * @param value - Display value to search for (string or regex)
 * @param options - Text matching options
 * @returns Array of matching elements (empty if none found)
 */
function queryAllByDisplayValue(container: HTMLElement, value: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];

/**
 * Query all elements by any attribute
 * @param container - Container element to search within
 * @param attribute - Attribute name
 * @param value - Attribute value to search for (string or regex)
 * @param options - Text matching options
 * @returns Array of matching elements (empty if none found)
 */
function queryAllByAttribute(container: HTMLElement, attribute: string, value: string | RegExp, options?: SelectorMatcherOptions): HTMLElement[];

findBy* Queries

Asynchronous queries that return a Promise. The Promise resolves when a matching element is found, or rejects if no element is found within the timeout period. All findBy* queries are instrumented for Storybook interactions.

/**
 * Async find element by ARIA role
 * @param container - Container element to search within
 * @param role - ARIA role to search for
 * @param options - Additional options for role matching
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to single matching element
 * @throws Error if no element found within timeout
 */
function findByRole(container: HTMLElement, role: string, options?: ByRoleOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;

/**
 * Async find element by text content
 * @param container - Container element to search within
 * @param text - Text content to search for (string or regex)
 * @param options - Text matching options
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to single matching element
 * @throws Error if no element found within timeout
 */
function findByText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;

/**
 * Async find element by test-id attribute
 * @param container - Container element to search within
 * @param testId - Test ID attribute value to search for
 * @param options - Text matching options
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to single matching element
 * @throws Error if no element found within timeout
 */
function findByTestId(container: HTMLElement, testId: string, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;

/**
 * Async find element by label text
 * @param container - Container element to search within
 * @param text - Label text to search for (string or regex)
 * @param options - Text matching options
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to single matching element
 * @throws Error if no element found within timeout
 */
function findByLabelText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;

/**
 * Async find element by placeholder text
 * @param container - Container element to search within
 * @param text - Placeholder text to search for (string or regex)
 * @param options - Text matching options
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to single matching element
 * @throws Error if no element found within timeout
 */
function findByPlaceholderText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;

/**
 * Async find element by alt attribute
 * @param container - Container element to search within
 * @param text - Alt text to search for (string or regex)
 * @param options - Text matching options
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to single matching element
 * @throws Error if no element found within timeout
 */
function findByAltText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;

/**
 * Async find element by title attribute
 * @param container - Container element to search within
 * @param text - Title text to search for (string or regex)
 * @param options - Text matching options
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to single matching element
 * @throws Error if no element found within timeout
 */
function findByTitle(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;

/**
 * Async find form element by display value
 * @param container - Container element to search within
 * @param value - Display value to search for (string or regex)
 * @param options - Text matching options
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to single matching element
 * @throws Error if no element found within timeout
 */
function findByDisplayValue(container: HTMLElement, value: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement>;

findAllBy* Queries

Asynchronous queries that return a Promise resolving to an array of elements. All findAllBy* queries are instrumented for Storybook interactions.

/**
 * Async find all elements by ARIA role
 * @param container - Container element to search within
 * @param role - ARIA role to search for
 * @param options - Additional options for role matching
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to array of matching elements
 * @throws Error if no elements found within timeout
 */
function findAllByRole(container: HTMLElement, role: string, options?: ByRoleOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;

/**
 * Async find all elements by text content
 * @param container - Container element to search within
 * @param text - Text content to search for (string or regex)
 * @param options - Text matching options
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to array of matching elements
 * @throws Error if no elements found within timeout
 */
function findAllByText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;

/**
 * Async find all elements by test-id attribute
 * @param container - Container element to search within
 * @param testId - Test ID attribute value to search for
 * @param options - Text matching options
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to array of matching elements
 * @throws Error if no elements found within timeout
 */
function findAllByTestId(container: HTMLElement, testId: string, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;

/**
 * Async find all elements by label text
 * @param container - Container element to search within
 * @param text - Label text to search for (string or regex)
 * @param options - Text matching options
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to array of matching elements
 * @throws Error if no elements found within timeout
 */
function findAllByLabelText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;

/**
 * Async find all elements by placeholder text
 * @param container - Container element to search within
 * @param text - Placeholder text to search for (string or regex)
 * @param options - Text matching options
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to array of matching elements
 * @throws Error if no elements found within timeout
 */
function findAllByPlaceholderText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;

/**
 * Async find all elements by alt attribute
 * @param container - Container element to search within
 * @param text - Alt text to search for (string or regex)
 * @param options - Text matching options
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to array of matching elements
 * @throws Error if no elements found within timeout
 */
function findAllByAltText(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;

/**
 * Async find all elements by title attribute
 * @param container - Container element to search within
 * @param text - Title text to search for (string or regex)
 * @param options - Text matching options
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to array of matching elements
 * @throws Error if no elements found within timeout
 */
function findAllByTitle(container: HTMLElement, text: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;

/**
 * Async find all form elements by display value
 * @param container - Container element to search within
 * @param value - Display value to search for (string or regex)  
 * @param options - Text matching options
 * @param waitForOptions - Timeout and retry options
 * @returns Promise that resolves to array of matching elements
 * @throws Error if no elements found within timeout
 */
function findAllByDisplayValue(container: HTMLElement, value: string | RegExp, options?: SelectorMatcherOptions, waitForOptions?: WaitForOptions): Promise<HTMLElement[]>;

Usage Examples

import { within } from "@storybook/testing-library";

export const QueryExamples = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    
    // Synchronous queries - throw if not found
    const submitButton = canvas.getByRole('button', { name: /submit/i });
    const emailInput = canvas.getByLabelText(/email/i);
    const errorMessage = canvas.getByTestId('error-message');
    
    // Query - returns null if not found  
    const optionalElement = canvas.queryByText(/optional text/i);
    if (optionalElement) {
      // Element exists, do something
    }
    
    // Async queries - wait for element to appear
    const loadingSpinner = await canvas.findByTestId('loading');
    const results = await canvas.findAllByRole('listitem');
  }
};

Install with Tessl CLI

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

docs