tessl/npm-testing-library--vue

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

—

Pending

Overview

Eval results

Files

Event Simulation

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

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

Capabilities

FireEvent Object

Main event firing utility that automatically waits for Vue's DOM updates after triggering events.

/**
 * Fire DOM events on elements with Vue-specific async handling
 * @param element - Target element
 * @param event - Event object to fire
 * @returns Promise that resolves after Vue DOM updates
 */
declare const fireEvent: {
  (element: Element, event: Event): Promise<void>;
  
  /** Click event */
  click(element: Element, options?: MouseEventInit): Promise<void>;
  
  /** Double click event */
  dblClick(element: Element, options?: MouseEventInit): Promise<void>;
  
  /** Mouse down event */
  mouseDown(element: Element, options?: MouseEventInit): Promise<void>;
  
  /** Mouse up event */
  mouseUp(element: Element, options?: MouseEventInit): Promise<void>;
  
  /** Mouse enter event */
  mouseEnter(element: Element, options?: MouseEventInit): Promise<void>;
  
  /** Mouse leave event */
  mouseLeave(element: Element, options?: MouseEventInit): Promise<void>;
  
  /** Mouse move event */
  mouseMove(element: Element, options?: MouseEventInit): Promise<void>;
  
  /** Mouse over event */
  mouseOver(element: Element, options?: MouseEventInit): Promise<void>;
  
  /** Mouse out event */
  mouseOut(element: Element, options?: MouseEventInit): Promise<void>;
  
  /** Change event */
  change(element: Element, options?: EventInit): Promise<void>;
  
  /** Input event */
  input(element: Element, options?: InputEventInit): Promise<void>;
  
  /** Focus event */
  focus(element: Element, options?: FocusEventInit): Promise<void>;
  
  /** Blur event */
  blur(element: Element, options?: FocusEventInit): Promise<void>;
  
  /** Key down event */
  keyDown(element: Element, options?: KeyboardEventInit): Promise<void>;
  
  /** Key up event */
  keyUp(element: Element, options?: KeyboardEventInit): Promise<void>;
  
  /** Key press event */
  keyPress(element: Element, options?: KeyboardEventInit): Promise<void>;
  
  /** Submit event */
  submit(element: Element, options?: EventInit): Promise<void>;
  
  /** Load event */
  load(element: Element, options?: EventInit): Promise<void>;
  
  /** Error event */
  error(element: Element, options?: EventInit): Promise<void>;
  
  /** Scroll event */
  scroll(element: Element, options?: EventInit): Promise<void>;
  
  /** Resize event */
  resize(element: Element, options?: UIEventInit): Promise<void>;
  
  /** Vue-specific touch event (focus then blur) */
  touch(element: Element): Promise<void>;
  
  /** Vue-specific form update utility */
  update(element: Element, value?: string): Promise<void>;
};

Usage Examples:

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

render(Counter);

// Basic click event
const button = screen.getByRole("button", { name: "Increment" });
await fireEvent.click(button);

// Input with keyboard events
const input = screen.getByLabelText("Search");
await fireEvent.focus(input);
await fireEvent.keyDown(input, { key: "A", code: "KeyA" });
await fireEvent.input(input, { target: { value: "Hello" } });

// Form submission
const form = screen.getByRole("form");
await fireEvent.submit(form);

Vue-Specific Event Methods

Touch Event

Convenience method that focuses an element then immediately blurs it, useful for testing touch interactions.

/**
 * Touch event - focus then blur an element
 * @param element - Element to touch
 * @returns Promise that resolves after both focus and blur complete
 */
function touch(element: Element): Promise<void>;

Usage Example:

const touchButton = screen.getByRole("button");
await fireEvent.touch(touchButton);

Update Event

Special utility for handling Vue's v-model updates on form elements. Automatically determines the correct event type based on the element.

/**
 * Update form element value (v-model helper)
 * @param element - Form element to update
 * @param value - New value (optional for checkboxes/radios)
 * @returns Promise that resolves after update completes
 */
function update(element: Element, value?: string): Promise<void>;

Usage Examples:

// Text input
const textInput = screen.getByLabelText("Name");
await fireEvent.update(textInput, "John Doe");

// Select dropdown
const select = screen.getByLabelText("Country");
await fireEvent.update(select, "USA");

// Checkbox (no value needed)
const checkbox = screen.getByRole("checkbox");
await fireEvent.update(checkbox);

// Radio button (no value needed)
const radio = screen.getByRole("radio", { name: "Option A" });
await fireEvent.update(radio);

// Select option
const option = screen.getByRole("option", { name: "Blue" });
await fireEvent.update(option);

Event Options

Mouse Event Options

interface MouseEventInit {
  /** Alt key pressed */
  altKey?: boolean;
  /** Mouse button pressed (0=left, 1=middle, 2=right) */
  button?: number;
  /** Buttons currently pressed */
  buttons?: number;
  /** X coordinate relative to client area */
  clientX?: number;
  /** Y coordinate relative to client area */
  clientY?: number;
  /** Ctrl key pressed */
  ctrlKey?: boolean;
  /** Meta key pressed */
  metaKey?: boolean;
  /** Related target element */
  relatedTarget?: Element | null;
  /** X coordinate relative to screen */
  screenX?: number;
  /** Y coordinate relative to screen */
  screenY?: number;
  /** Shift key pressed */
  shiftKey?: boolean;
}

Keyboard Event Options

interface KeyboardEventInit {
  /** Alt key pressed */
  altKey?: boolean;
  /** Physical key code */
  code?: string;
  /** Ctrl key pressed */
  ctrlKey?: boolean;
  /** Logical key value */
  key?: string;
  /** Key location */
  location?: number;
  /** Meta key pressed */
  metaKey?: boolean;
  /** Key is auto-repeating */
  repeat?: boolean;
  /** Shift key pressed */
  shiftKey?: boolean;
}

Focus Event Options

interface FocusEventInit {
  /** Related target element */
  relatedTarget?: Element | null;
}

Input Event Options

interface InputEventInit {
  /** Input data */
  data?: string | null;
  /** Input type */
  inputType?: string;
  /** Is composing */
  isComposing?: boolean;
}

Common Event Patterns

Form Interactions

// Fill out a form
const nameInput = screen.getByLabelText("Full Name");
const emailInput = screen.getByLabelText("Email");
const submitButton = screen.getByRole("button", { name: "Submit" });

await fireEvent.update(nameInput, "John Doe");
await fireEvent.update(emailInput, "john@example.com");
await fireEvent.click(submitButton);

Keyboard Navigation

// Navigate with keyboard
const input = screen.getByRole("textbox");
await fireEvent.focus(input);
await fireEvent.keyDown(input, { key: "Tab" });
await fireEvent.keyDown(document.activeElement, { key: "Enter" });

Mouse Interactions

// Hover and click
const button = screen.getByRole("button");
await fireEvent.mouseOver(button);
await fireEvent.mouseMove(button);
await fireEvent.click(button);
await fireEvent.mouseOut(button);

Error Handling

Vue Testing Library will show warnings for potentially incorrect event usage:

Using fireEvent.change or fireEvent.input directly may lead to unexpected results
Recommended to use fireEvent.update() for form elements instead
Warning can be disabled with VTL_SKIP_WARN_EVENT_UPDATE environment variable

Install with Tessl CLI

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

docs