API de Contexto

Vitest expone un módulo de contexto a través del punto de entrada @vitest/browser/context. Desde la versión 2.0, proporciona un conjunto de utilidades que pueden ser de gran ayuda en tus pruebas.

userEvent

TIP

La API userEvent se explica en detalle en API de Interactividad.

/**
 * Gestiona las interacciones del usuario. El soporte es proporcionado por el proveedor del navegador (`playwright` o `webdriverio`).
 * Si se utiliza con el proveedor `preview`, recurre a eventos simulados a través de `@testing-library/user-event`.
 * @experimental
 */
export const userEvent: {
  setup: () => UserEvent;
  cleanup: () => Promise<void>;
  click: (element: Element, options?: UserEventClickOptions) => Promise<void>;
  dblClick: (
    element: Element,
    options?: UserEventDoubleClickOptions
  ) => Promise<void>;
  tripleClick: (
    element: Element,
    options?: UserEventTripleClickOptions
  ) => Promise<void>;
  selectOptions: (
    element: Element,
    values: HTMLElement | HTMLElement[] | string | string[],
    options?: UserEventSelectOptions
  ) => Promise<void>;
  keyboard: (text: string) => Promise<void>;
  type: (
    element: Element,
    text: string,
    options?: UserEventTypeOptions
  ) => Promise<void>;
  clear: (element: Element) => Promise<void>;
  tab: (options?: UserEventTabOptions) => Promise<void>;
  hover: (element: Element, options?: UserEventHoverOptions) => Promise<void>;
  unhover: (element: Element, options?: UserEventHoverOptions) => Promise<void>;
  fill: (
    element: Element,
    text: string,
    options?: UserEventFillOptions
  ) => Promise<void>;
  dragAndDrop: (
    source: Element,
    target: Element,
    options?: UserEventDragAndDropOptions
  ) => Promise<void>;
};

commands

TIP

Esta API se explica en detalle en API de Comandos.

/**
 * Comandos disponibles para el navegador.
 * Un atajo a `server.commands`.
 */
export const commands: BrowserCommands;

page

La exportación page proporciona utilidades para interactuar con la página actual.

WARNING

Aunque expone algunas utilidades de la página de Playwright, no es el mismo objeto. Dado que el contexto del navegador se evalúa en el navegador, tus pruebas no tienen acceso directo al objeto page de Playwright, ya que este se ejecuta en el servidor.

Usa la API de Comandos si necesitas acceder al objeto page de Playwright.

export const page: {
  /**
   * Cambia el tamaño de la ventana gráfica del iframe.
   */
  viewport(width: number, height: number): Promise<void>;
  /**
   * Realiza una captura de pantalla del iframe de prueba o de un elemento específico.
   * @returns Ruta al archivo de la captura de pantalla o una cadena en base64.
   */
  screenshot(
    options: Omit<ScreenshotOptions, 'base64'> & { base64: true }
  ): Promise<{
    path: string;
    base64: string;
  }>;
  screenshot(options?: ScreenshotOptions): Promise<string>;
  /**
   * Extiende el objeto de página predeterminado con métodos personalizados.
   */
  extend(methods: Partial<BrowserPage>): BrowserPage;
  /**
   * Envuelve un elemento HTML en un `Locator`. Al consultar elementos, la búsqueda siempre devolverá este elemento.
   */
  elementLocator(element: Element): Locator;

  /**
   * APIs de Localizador. Consulta la documentación para más detalles.
   */
  getByRole(role: ARIARole | string, options?: LocatorByRoleOptions): Locator;
  getByLabelText(text: string | RegExp, options?: LocatorOptions): Locator;
  getByTestId(text: string | RegExp): Locator;
  getByAltText(text: string | RegExp, options?: LocatorOptions): Locator;
  getByPlaceholder(text: string | RegExp, options?: LocatorOptions): Locator;
  getByText(text: string | RegExp, options?: LocatorOptions): Locator;
  getByTitle(text: string | RegExp, options?: LocatorOptions): Locator;
};

TIP

La API getBy* se explica en API de Localizadores.

ADVERTENCIA 3.2.0+

Ten en cuenta que screenshot siempre devolverá una cadena base64 si save se establece en false. La ruta también se ignora en ese caso.

cdp

La exportación cdp devuelve la sesión actual del Protocolo de Herramientas de Desarrollo de Chrome (CDP). Es especialmente útil para los autores de bibliotecas que deseen construir herramientas sobre él.

WARNING

La sesión CDP solo funciona con el proveedor playwright y únicamente cuando se utiliza el navegador chromium. Puedes leer más sobre esto en la documentación de CDPSession de Playwright.

export const cdp: () => CDPSession;

server

La exportación server representa el entorno Node.js en el que se ejecuta el servidor Vitest. Es especialmente útil para depurar o para adaptar tus pruebas en función del entorno.

export const server: {
  /**
   * Plataforma en la que se ejecuta el servidor Vitest.
   * Equivalente a llamar a `process.platform` en el servidor.
   */
  platform: Platform;
  /**
   * Versión del tiempo de ejecución del servidor Vitest.
   * Equivalente a llamar a `process.version` en el servidor.
   */
  version: string;
  /**
   * Nombre del proveedor del navegador.
   */
  provider: string;
  /**
   * Nombre del navegador actual.
   */
  browser: string;
  /**
   * Comandos disponibles para el navegador.
   */
  commands: BrowserCommands;
  /**
   * Configuración de prueba serializada.
   */
  config: SerializedConfig;
};