Referência de Configuração do Navegador

Você pode modificar a configuração do navegador atualizando o campo test.browser no seu arquivo de configuração. Um exemplo de um arquivo de configuração simples:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [
        {
          browser: 'chromium',
          setupFile: './chromium-setup.js',
        },
      ],
    },
  },
});

Consulte o artigo "Referência de Configuração" para exemplos de configurações diferentes.

WARNING

Todas as opções listadas nesta página estão localizadas dentro de uma propriedade test na configuração:

export default defineConfig({
  test: {
    browser: {},
  },
});

browser.enabled

• Tipo: boolean
• Padrão: false
• CLI: --browser, --browser.enabled=false

Habilita a execução de todos os testes em um navegador por padrão. Note que --browser só funciona se você tiver pelo menos um item em browser.instances.

browser.instances

• Tipo: BrowserConfig
• Padrão: [{ browser: name }]

Define múltiplas configurações de navegador. Cada configuração deve ter pelo menos um campo browser. A configuração suporta as opções dos seus provedores:

• Configurando Playwright
• Configurando WebdriverIO

TIP

Para ter uma tipagem mais segura ao usar provedores embutidos, você deve referenciar um desses tipos (para o provedor que você está usando) no seu arquivo de configuração:

/// <reference types="@vitest/browser/providers/playwright" />
/// <reference types="@vitest/browser/providers/webdriverio" />

Adicionalmente, você pode especificar a maioria das opções de projeto (não marcadas com um ícone *) e algumas das opções browser como browser.testerHtmlPath.

WARNING

Cada configuração de navegador herda as opções da configuração raiz:

export default defineConfig({
  test: {
    setupFile: ['./root-setup-file.js'],
    browser: {
      enabled: true,
      testerHtmlPath: './custom-path.html',
      instances: [
        {
          // terá ambos os arquivos de setup: "root" e "browser"
          setupFile: ['./browser-setup-file.js'],
          // implicitamente herda "testerHtmlPath" da configuração raiz
          // testerHtmlPath: './custom-path.html',
        },
      ],
    },
  },
})

Durante o desenvolvimento, o Vitest suporta apenas uma configuração não-headless. Você pode controlar qual projeto será executado com interface gráfica especificando headless: false na configuração, fornecendo a flag --browser.headless=false ou filtrando projetos com a flag --project=chromium.

Para mais exemplos, consulte o guia "Múltiplas Configurações".

Lista de opções browser disponíveis:

• browser.headless
• browser.locators
• browser.viewport
• browser.testerHtmlPath
• browser.screenshotDirectory
• browser.screenshotFailures

Por padrão, o Vitest cria um array com um único elemento que usa o valor do campo browser.name como o navegador. Note que este comportamento será removido com o Vitest 4.

Nos bastidores, o Vitest transforma essas instâncias em projetos de teste separados, compartilhando um único servidor Vite para melhor desempenho de cache.

browser.name depreciado

• Tipo: string
• CLI: --browser=safari

DEPRECIADO

Esta API está depreciada e será removida no Vitest 4. Por favor, use a opção browser.instances em vez disso.

Executa todos os testes em um navegador específico. Opções possíveis em diferentes provedores:

• webdriverio: firefox, chrome, edge, safari
• playwright: firefox, webkit, chromium
• customizado: qualquer string que será passada para o provedor

browser.headless

• Tipo: boolean
• Padrão: process.env.CI
• CLI: --browser.headless, --browser.headless=false

Executa o navegador em modo headless (sem interface gráfica). Se você estiver executando o Vitest em CI, será habilitado por padrão.

browser.isolate

• Tipo: boolean
• Padrão: true
• CLI: --browser.isolate, --browser.isolate=false

Executa cada teste em um iframe separado.

browser.testerHtmlPath

• Tipo: string

Um caminho para o arquivo HTML de entrada. Pode ser relativo à raiz do projeto. Este arquivo será processado pelo hook transformIndexHtml.

browser.api

• Tipo: number | { port?, strictPort?, host? }
• Padrão: 63315
• CLI: --browser.api=63315, --browser.api.port=1234, --browser.api.host=example.com

Configura opções para o servidor Vite que disponibiliza o código no navegador. Não interfere na opção test.api. Por padrão, o Vitest atribui a porta 63315 para evitar conflitos com o servidor de desenvolvimento, permitindo que você execute ambos em paralelo.

browser.provider

• Tipo: 'webdriverio' | 'playwright' | 'preview' | string
• Padrão: 'preview'
• CLI: --browser.provider=playwright

Define o caminho para o provedor que será usado ao executar testes de navegador. O Vitest fornece três provedores: preview (padrão), webdriverio e playwright. Provedores personalizados devem ser exportados usando a exportação default e ter a seguinte estrutura:

export interface BrowserProvider {
  name: string;
  supportsParallelism: boolean;
  getSupportedBrowsers: () => readonly string[];
  beforeCommand?: (command: string, args: unknown[]) => Awaitable<void>;
  afterCommand?: (command: string, args: unknown[]) => Awaitable<void>;
  getCommandsContext: (sessionId: string) => Record<string, unknown>;
  openPage: (
    sessionId: string,
    url: string,
    beforeNavigate?: () => Promise<void>
  ) => Promise<void>;
  getCDPSession?: (sessionId: string) => Promise<CDPSession>;
  close: () => Awaitable<void>;
  initialize(
    ctx: TestProject,
    options: BrowserProviderInitializationOptions
  ): Awaitable<void>;
}

API AVANÇADA

A API de provedor personalizado é altamente experimental e pode sofrer alterações entre patches. Se você precisar apenas executar testes em um navegador, use a opção browser.instances em vez disso.

browser.providerOptions depreciado

• Tipo: BrowserProviderOptions

DEPRECIADO

Esta API está depreciada e será removida no Vitest 4. Por favor, use a opção browser.instances em vez disso.

Opções que serão passadas ao provedor ao chamar provider.initialize.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    browser: {
      providerOptions: {
        launch: {
          devtools: true,
        },
      },
    },
  },
});

TIP

Para ter uma tipagem mais segura ao usar provedores embutidos, você deve referenciar um desses tipos (para o provedor que você está usando) no seu arquivo de configuração:

/// <reference types="@vitest/browser/providers/playwright" />
/// <reference types="@vitest/browser/providers/webdriverio" />

browser.ui

• Tipo: boolean
• Padrão: !isCI
• CLI: --browser.ui=false

Define se a UI do Vitest deve ser injetada na página. Por padrão, o iframe da UI é injetado durante o desenvolvimento.

browser.viewport

• Tipo: { width, height }
• Padrão: 414x896

Define o viewport padrão do iframe.

browser.locators

Opções para localizadores de navegador integrados.

browser.locators.testIdAttribute

• Tipo: string
• Padrão: data-testid

Define o atributo usado para encontrar elementos com o localizador getByTestId.

browser.screenshotDirectory

• Tipo: string
• Padrão: __screenshots__ no diretório do arquivo de teste

Define o caminho para o diretório de capturas de tela relativo à root.

browser.screenshotFailures

• Tipo: boolean
• Padrão: !browser.ui

Define se o Vitest deve tirar capturas de tela se o teste falhar.

browser.orchestratorScripts

• Tipo: BrowserScript[]
• Padrão: []

Scripts personalizados a serem injetados no HTML do orquestrador antes que os iframes de teste sejam iniciados. Este documento HTML apenas configura iframes e não carrega o seu código.

Os atributos src e content dos scripts serão processados pelos plugins do Vite. O script deve ser fornecido na seguinte forma:

export interface BrowserScript {
  /**
   * Se "content" for fornecido e o tipo for "module", este será usado como seu identificador.
   *
   * Se você estiver usando TypeScript, você pode adicionar a extensão `.ts` aqui, por exemplo.
   * @default `injected-${index}.js`
   */
  id?: string;
  /**
   * Conteúdo JavaScript para ser injetado. Esta string será processada pelos plugins do Vite se o tipo for "module".
   *
   * Você pode usar `id` para fornecer ao Vite uma indicação sobre a extensão do arquivo.
   */
  content?: string;
  /**
   * Caminho para o script. Este valor é resolvido pelo Vite, então pode ser um módulo Node.js ou um caminho de arquivo.
   */
  src?: string;
  /**
   * Define se o script deve ser carregado assincronamente.
   */
  async?: boolean;
  /**
   * Tipo de script.
   * @default 'module'
   */
  type?: string;
}

browser.testerScripts

• Tipo: BrowserScript[]
• Padrão: []

DEPRECIADO

Esta API está depreciada e será removida no Vitest 4. Por favor, use o campo browser.testerHtmlPath em vez disso.

Scripts personalizados a serem injetados no HTML do testador antes que o ambiente de testes seja iniciado. É útil para injetar polyfills necessários para a implementação do navegador Vitest. Recomenda-se usar setupFiles em quase todos os casos, em seu lugar.

Os atributos src e content dos scripts serão processados pelos plugins do Vite.

browser.commands

• Tipo: Record<string, BrowserCommand>
• Padrão: { readFile, writeFile, ... }

Comandos personalizados a serem importados durante os testes de navegador de @vitest/browser/commands.

browser.connectTimeout

• Tipo: number
• Padrão: 60_000

Define o tempo limite em milissegundos. Se a conexão com o navegador levar mais tempo, os testes falharão.

INFO

Este é o tempo que o navegador leva para estabelecer a conexão WebSocket com o servidor Vitest. Em circunstâncias normais, este tempo limite não deveria ser atingido.