Referencia

ascua-testing

Montar, tocar y desmontar un componente en un test. Nueve funciones.

ts
import { check, cleanup, click, drag, input, render, submit, wait, waitFor } from "ascua-testing";

Funciona con cualquier runner que tenga un DOM —Vitest con happy-dom, jsdom—. La guía está en Tests.

render

ts
function render(construir: () => Node): RenderResult;

interface RenderResult {
  container: HTMLElement;
  get<T extends Element = HTMLElement>(selector: string): T;
  getAll<T extends Element = HTMLElement>(selector: string): T[];
  text(selector?: string): string;
  waitFor<T extends Element = HTMLElement>(selector: string, options?: { timeout?: number }): Promise<T>;
  unmount(): void;
}

Monta en un contenedor propio, añadido al documento: el foco, closest y las medidas solo funcionan ahí. get falla con el HTML montado en el mensaje cuando el selector no encuentra nada. El waitFor que devuelve es el de abajo, limitado al contenedor.

cleanup

ts
function cleanup(): void;

Desmonta todo lo montado con render. Va en un afterEach.

click

ts
function click(nodo: Element): void;

Un click que burbujea, como el de un usuario.

input

ts
function input(campo: HTMLInputElement | HTMLTextAreaElement, valor: string): void;

Cambia el valor y dispara input.

check

ts
function check(casilla: HTMLInputElement, checked?: boolean): void;

Cambia checked y dispara change.

submit

ts
function submit(formulario: HTMLFormElement): void;

Un submit cancelable, como el de pulsar Enter.

drag

ts
function drag(nodo: Element, puntos: readonly Point[], options?: DragOptions): void;

interface Point { x: number; y: number }

interface DragOptions {
  pointerId?: number;                          // 1
  pointerType?: "mouse" | "pen" | "touch";     // "mouse"
  cancel?: boolean;                            // termina con pointercancel
}

pointerdown en el primer punto, pointermove en cada uno de los siguientes y pointerup en el último; con cancel, pointercancel, que es lo que manda iOS cuando entra un gesto del sistema. Un solo punto es un toque. Todo va al mismo nodo, como con setPointerCapture.

El DOM de los tests no hace layout: si el componente calcula qué hay bajo el dedo a partir de clientX/Y, conviene que pueda recibir el rectángulo desde fuera en vez de pedirle getBoundingClientRect() a un nodo que mide cero.

wait

ts
function wait(milisegundos?: number): Promise<void>;

Cede el turno para que corran las promesas pendientes. Solo hace falta si lo que se prueba es asíncrono: los efectos no lo son.

waitFor

ts
function waitFor<T extends Element = HTMLElement>(
  selector: string,
  options?: WaitForOptions,
): Promise<T>;

interface WaitForOptions {
  within?: ParentNode;   // dónde buscar; por defecto, el documento
  timeout?: number;      // en milisegundos; por defecto 1000
}

Espera a que aparezca un nodo que encaje con selector y resuelve con él en cuanto aparece; si ya está, resuelve en el acto. Si pasa el plazo sin que aparezca, falla con el HTML que había dentro de within, igual que get.

Es para cuando no se sabe cuántos turnos tarda lo que se prueba —un resource que encadena varias promesas, un fetch simulado con retraso— y un wait() suelto sería adivinar. render() devuelve su propio waitFor, que busca solo dentro del contenedor.