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 2.0, ele disponibiliza um pequeno conjunto de utilitários que podem ser úteis em seus testes.

userEvent

TIP

A API userEvent é explicada em detalhes na 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 na API de Comandos.

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

page

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

WARNING

Embora exponha alguns utilitários da página do Playwright, não é o mesmo objeto. Como o contexto do navegador é avaliado no próprio navegador, seus testes não têm acesso direto ao objeto de página do Playwright, pois ele é executado no servidor.

Use a API de Comandos se precisar acessar o objeto de página do Playwright.

export const page: {
  /**
   * Altera o tamanho da viewport do iframe.
   */
  viewport(width: number, height: number): Promise<void>;
  /**
   * Tira uma captura de tela do iframe de teste ou de um elemento específico.
   * @returns Caminho para o arquivo de screenshot ou caminho e o conteúdo em 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 por elementos, a busca sempre retornará este elemento específico.
   */
  elementLocator(element: Element): Locator;

  /**
   * APIs de Locator. Veja 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 na API de Locators.

cdp

A exportação cdp retorna a sessão atual do Chrome DevTools Protocol. É mais útil para autores de bibliotecas criarem ferramentas baseadas nela.

WARNING

A sessão CDP funciona apenas com o provedor playwright e somente ao usar o navegador chromium. Você pode ler mais sobre isso na documentação CDPSession do Playwright.

export const cdp: () => CDPSession;

server

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

export const server: {
  /**
   * Plataforma em que o servidor Vitest está sendo executado.
   * Equivalente a chamar `process.platform` no servidor.
   */
  platform: Platform;
  /**
   * Versão do runtime do servidor Vitest.
   * Equivalente a 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 serializada dos testes.
   */
  config: SerializedConfig;
};