DOM Element Wrapper

/**
 * Set value on form inputs and emit appropriate events
 * Handles input, textarea, select, checkbox, and radio elements
 * Automatically calls appropriate internal methods based on element type
 * @param value - Value to set (string for text inputs, boolean for checkboxes)
 * @returns Promise that resolves after value is set and events are emitted
 */
setValue(value: any): Promise<void>;

import { mount } from "@vue/test-utils";

const wrapper = mount(MyForm);

// Text input
await wrapper.find('input[type="text"]').setValue("Hello World");

// Email input
await wrapper.find('input[type="email"]').setValue("test@example.com");

// Textarea
await wrapper.find('textarea').setValue("Multi-line\ntext content");

// Checkbox - use setValue with boolean
await wrapper.find('input[type="checkbox"]').setValue(true);
await wrapper.find('input[type="checkbox"]').setValue(false);

// Radio button - use setValue with boolean  
await wrapper.find('input[type="radio"][value="option1"]').setValue(true);

// Select dropdown
await wrapper.find('select').setValue("option2");

// Note: setValue automatically handles different input types internally

/**
 * Find all Vue components within this DOM element's scope
 * @param selector - Component selector (constructor, name, or ref)
 * @returns Array of VueWrapper instances for matched components
 */
findAllComponents(selector: FindAllComponentsSelector): VueWrapper<any>[];

const wrapper = mount(MyComponent);
const containerDiv = wrapper.find('.container');

// Find components within the container
const childComponents = containerDiv.findAllComponents({ name: 'ChildComponent' });
expect(childComponents).toHaveLength(2);

// Find components by constructor
import SpecificComponent from "./SpecificComponent.vue";
const specificComponents = containerDiv.findAllComponents(SpecificComponent);

/**
 * Find first matching element within this wrapper's scope
 * @param selector - CSS selector or component selector
 * @returns DOMWrapper for matched element
 */
find<T extends Node = Node>(selector: string): DOMWrapper<T>;

/**
 * Find all matching elements within this wrapper's scope
 * @param selector - CSS selector
 * @returns Array of DOMWrapper instances for matched elements
 */
findAll<T extends Node = Node>(selector: string): DOMWrapper<T>[];

/**
 * Find first matching Vue component within this wrapper's scope
 * @param selector - Component selector (ref, name, or constructor)
 * @returns VueWrapper for matched component
 */
findComponent(selector: FindComponentSelector): VueWrapper<any>;

/**
 * Find element or throw error if not found
 * @param selector - CSS selector
 * @returns DOMWrapper for matched element (guaranteed to exist)
 */
get<T extends Node = Node>(selector: string): DOMWrapper<T>;

/**
 * Find component or throw error if not found
 * @param selector - Component selector
 * @returns VueWrapper for matched component (guaranteed to exist)
 */
getComponent(selector: FindComponentSelector): VueWrapper<any>;

/**
 * Get HTML content of the element including children
 * @returns HTML string with optional beautification
 */
html(): string;

/**
 * Get text content of the element and its children
 * @returns Plain text content
 */
text(): string;

/**
 * Get CSS classes of the element
 * @param className - Optional specific class to check
 * @returns Array of class names or boolean if className specified
 */
classes(): string[];
classes(className: string): boolean;

/**
 * Get HTML attributes of the element
 * @param key - Optional specific attribute to check
 * @returns Attributes object or specific attribute value
 */
attributes(): Record<string, string>;
attributes(key: string): string;

/**
 * Check if the element exists in the DOM
 * @returns true if element exists, false otherwise
 */
exists(): boolean;

/**
 * Check if the element is visible
 * Considers CSS display, visibility, and opacity properties
 * @returns true if element is visible, false otherwise
 */
isVisible(): boolean;

/**
 * Trigger DOM events on the element
 * @param eventString - Event type (e.g., 'click', 'keydown', 'focus')
 * @param options - Event options and properties
 * @returns Promise that resolves after event is triggered and processed
 */
trigger(eventString: string, options?: TriggerOptions): Promise<void>;

interface TriggerOptions {
  /** Key code for keyboard events */
  keyCode?: number;
  /** Which key for keyboard events */
  which?: number;
  /** Key name for keyboard events */
  key?: string;
  /** Mouse button for mouse events */
  button?: number;
  /** Additional event properties */
  [key: string]: any;
}

const wrapper = mount(MyComponent);

// Element querying
const button = wrapper.find('button');
const inputs = wrapper.findAll('input');
const childComponent = wrapper.findComponent({ name: 'ChildComponent' });

// Content inspection
expect(button.text()).toBe('Click me');
expect(button.html()).toContain('<span>');
expect(button.classes()).toContain('btn-primary');
expect(button.attributes('disabled')).toBe('true');

// Element state
expect(button.exists()).toBe(true);
expect(button.isVisible()).toBe(true);

// Event triggering
await button.trigger('click');
await wrapper.find('input').trigger('keydown', { key: 'Enter', keyCode: 13 });
await wrapper.find('form').trigger('submit');

// HTML element specific typing
const input = wrapper.find<HTMLInputElement>('input');
input.element.value; // Typed as HTMLInputElement

const button = wrapper.find<HTMLButtonElement>('button');
button.element.disabled; // Typed as HTMLButtonElement

// SVG element typing
const circle = wrapper.find<SVGCircleElement>('circle');
circle.element.r; // Typed as SVGCircleElement

// Text inputs
await wrapper.find('input[type="text"]').setValue("text value");
await wrapper.find('input[type="email"]').setValue("user@example.com");
await wrapper.find('input[type="password"]').setValue("secret");
await wrapper.find('input[type="number"]').setValue("42");
await wrapper.find('input[type="url"]').setValue("https://example.com");

// Textarea
await wrapper.find('textarea').setValue("Multi-line content");

// Checkboxes and radio buttons
await wrapper.find('input[type="checkbox"]').setValue(true);
await wrapper.find('input[type="radio"]').setValue(true);

// Select elements
await wrapper.find('select').setValue("option-value");

// File inputs (limited support)
const fileInput = wrapper.find('input[type="file"]');
// File input setValue has limitations due to browser security

const wrapper = mount(MyComponent);

try {
  const element = wrapper.get('[data-test="required-element"]');
  await element.setValue("value");
} catch (error) {
  console.error("Element interaction failed:", error.message);
}