API de Contexto

O Vitest expõe um módulo de contexto através do ponto de entrada @vitest/browser/context. A partir da versão 3.0, ele disponibiliza um pequeno conjunto de utilitários que podem ser úteis para seus testes.

userEvent

TIP

A API userEvent é explicada em detalhes em API de Interatividade.

/**
 * Manipulador para interações do usuário. O suporte é implementado pelo provedor de navegador (`playwright` ou `webdriverio`).
 * Se usado com o provedor `preview`, recorre a eventos simulados via `@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 é explicada em detalhes em API de Comandos.

/**
 * Comandos disponíveis para o navegador.
 * Um atalho para `server.commands`.
 */
export const commands: BrowserCommands;

page

A exportação page oferece utilitários para interagir com a página atual.

WARNING

Embora exponha alguns utilitários do objeto page do Playwright, não é o mesmo objeto. Como o contexto do navegador é avaliado no navegador, seus testes não têm acesso ao objeto page do Playwright porque ele é executado no servidor.

Use a API de Comandos se precisar ter acesso ao objeto page do Playwright.

export const page: {
  /**
   * Altera o tamanho da área de visualização do iframe.
   */
  viewport(width: number, height: number): Promise<void>;
  /**
   * Cria uma captura de tela do iframe de teste ou de um elemento específico.
   * @returns Caminho para o arquivo de captura de tela ou um objeto contendo o caminho e a string base64.
   */
  screenshot(
    options: Omit<ScreenshotOptions, 'base64'> & { base64: true }
  ): Promise<{
    path: string;
    base64: string;
  }>;
  screenshot(options?: ScreenshotOptions): Promise<string>;
  /**
   * Estende o objeto `page` padrão com métodos personalizados.
   */
  extend(methods: Partial<BrowserPage>): BrowserPage;
  /**
   * Encapsula um elemento HTML em um `Locator`. Ao consultar elementos, a pesquisa sempre retornará este elemento.
   */
  elementLocator(element: Element): Locator;

  /**
   * APIs de Locator. Consulte sua documentação para mais detalhes.
   */
  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

A API getBy* é explicada em API de Localizadores.

AVISO 3.2.0+

Note que a função screenshot sempre retornará uma string base64 se o parâmetro save estiver definido como false. O caminho também é ignorado nesse caso.

cdp

A exportação cdp retorna a sessão atual do Chrome DevTools Protocol. É principalmente útil para autores de bibliotecas que desejam construir ferramentas com base nela.

WARNING

A sessão CDP funciona somente com o provedor playwright e apenas quando o navegador chromium está em uso. Você pode ler mais sobre isso na documentação da CDPSession do Playwright.

export const cdp: () => CDPSession;

server

A exportação server representa o ambiente Node.js onde o servidor do Vitest está sendo executado. É principalmente útil para depuração ou para adaptar seus testes com base no ambiente.

export const server: {
  /**
   * Plataforma em que o servidor Vitest está sendo executado.
   * O mesmo que chamar `process.platform` no servidor.
   */
  platform: Platform;
  /**
   * Versão de tempo de execução do servidor Vitest.
   * O mesmo que chamar `process.version` no servidor.
   */
  version: string;
  /**
   * Nome do provedor de navegador.
   */
  provider: string;
  /**
   * Nome do navegador atual.
   */
  browser: string;
  /**
   * Comandos disponíveis para o navegador.
   */
  commands: BrowserCommands;
  /**
   * Configuração de teste serializada.
   */
  config: SerializedConfig;
};