Modo Navegador Experimental

Esta página fornece informações sobre o recurso experimental de modo navegador na API Vitest, que permite executar seus testes nativamente no navegador, fornecendo acesso a objetos globais do navegador como window e document. Este recurso está atualmente em desenvolvimento e as APIs podem mudar no futuro.

Instalação

Para facilitar a configuração, você pode usar o comando vitest init browser para instalar as dependências necessárias e criar o arquivo de configuração do navegador.

npm

npx vitest init browser

yarn

yarn exec vitest init browser

pnpm

pnpx vitest init browser

bun

bunx vitest init browser

Instalação Manual

Você também pode instalar pacotes manualmente. Por padrão, o Modo Navegador não exige nenhum provedor de teste de ponta a ponta (E2E) adicional para executar testes localmente, pois ele reutiliza seu navegador já existente.

npm

npm install -D vitest @vitest/browser

yarn

yarn add -D vitest @vitest/browser

pnpm

pnpm add -D vitest @vitest/browser

bun

bun add -D vitest @vitest/browser

WARNING

No entanto, para executar testes em CI, você precisa instalar playwright ou webdriverio. Também recomendamos alternar para um desses provedores para testes locais, em vez de usar o provedor preview padrão, já que este último depende da simulação de eventos em vez de utilizar o Chrome DevTools Protocol.

Se você ainda não utiliza uma dessas ferramentas, recomendamos começar com o Playwright. Ele suporta execução paralela, o que acelera seus testes. Além disso, o Chrome DevTools Protocol que o Playwright usa é geralmente mais rápido que o WebDriver.

::: tabs key:provider == Playwright Playwright é um framework para Testes Web e Automação.

npm

npm install -D vitest @vitest/browser playwright

yarn

yarn add -D vitest @vitest/browser playwright

pnpm

pnpm add -D vitest @vitest/browser playwright

bun

bun add -D vitest @vitest/browser playwright

== WebdriverIO

WebdriverIO permite que você execute testes localmente usando o protocolo WebDriver.

npm

npm

npm install -D vitest @vitest/browser webdriverio

yarn

yarn add -D vitest @vitest/browser webdriverio

pnpm

pnpm add -D vitest @vitest/browser webdriverio

bun

bun add -D vitest @vitest/browser webdriverio

Configuração

Para ativar o modo navegador na sua configuração Vitest, você pode usar a flag --browser ou definir o campo browser.enabled como true no seu arquivo de configuração Vitest. A seguir, um exemplo de configuração utilizando o campo browser:

export default defineConfig({
  test: {
    browser: {
      provider: 'playwright', // ou 'webdriverio'
      enabled: true,
      name: 'chromium', // o nome do navegador é necessário
    },
  },
});

INFO

O Vitest atribui a porta 63315 para evitar conflitos com o servidor de desenvolvimento, permitindo que você execute ambos em paralelo. Você pode alterar isso com a opção browser.api.

A partir do Vitest 2.1.5, a CLI não exibe mais a URL do Vite automaticamente. Você pode pressionar "b" para exibir a URL ao executar no modo de monitoramento (watch mode).

Se você ainda não utilizou o Vite, certifique-se de ter o plugin do seu framework instalado e especificado na configuração. Alguns frameworks podem exigir configuração adicional para funcionar – verifique a documentação relacionada ao Vite para confirmar.

vue

import { defineConfig } from 'vitest/config';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [vue()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      name: 'chromium',
    },
  },
});

svelte

import { defineConfig } from 'vitest/config';
import { svelte } from '@sveltejs/vite-plugin-svelte';

export default defineConfig({
  plugins: [svelte()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      name: 'chromium',
    },
  },
});

solid

import { defineConfig } from 'vitest/config';
import solidPlugin from 'vite-plugin-solid';

export default defineConfig({
  plugins: [solidPlugin()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      name: 'chromium',
    },
  },
});

marko

import { defineConfig } from 'vitest/config';
import marko from '@marko/vite';

export default defineConfig({
  plugins: [marko()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      name: 'chromium',
    },
  },
});

TIP

react não exige um plugin para funcionar, mas preact requer configuração adicional para que os aliases funcionem corretamente.

Se você precisar executar alguns testes utilizando um runner baseado em Node, pode definir um arquivo de espaço de trabalho com configurações separadas para diferentes estratégias de teste:

// vitest.workspace.ts
import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  {
    test: {
      // um exemplo de convenção baseada em arquivo,
      // você não precisa segui-la
      include: [
        'tests/unit/**/*.{test,spec}.ts',
        'tests/**/*.unit.{test,spec}.ts',
      ],
      name: 'unit',
      environment: 'node',
    },
  },
  {
    test: {
      // um exemplo de convenção baseada em arquivo,
      // você não precisa segui-la
      include: [
        'tests/browser/**/*.{test,spec}.ts',
        'tests/**/*.browser.{test,spec}.ts',
      ],
      name: 'browser',
      browser: {
        enabled: true,
        name: 'chrome',
      },
    },
  },
]);

Configuração do Provedor

:::tabs key:provider == Playwright Você pode configurar como o Vitest inicia o navegador e cria o contexto da página através do campo providerOptions:

export default defineConfig({
  test: {
    browser: {
      providerOptions: {
        launch: {
          devtools: true,
        },
        context: {
          geolocation: {
            latitude: 45,
            longitude: -30,
          },
          reducedMotion: 'reduce',
        },
      },
    },
  },
});

Para obter sugestões de tipo (type hints), adicione @vitest/browser/providers/playwright a compilerOptions.types no seu arquivo tsconfig.json. == WebdriverIO Você pode configurar quais opções o Vitest deve usar ao iniciar um navegador através do campo providerOptions:

export default defineConfig({
  test: {
    browser: {
      browser: 'chrome',
      providerOptions: {
        region: 'eu',
        capabilities: {
          browserVersion: '27.0',
          platformName: 'Windows 10',
        },
      },
    },
  },
});

Para obter sugestões de tipo (type hints), adicione @vitest/browser/providers/webdriverio a compilerOptions.types no seu arquivo tsconfig.json. :::

Tipos de Opções do Navegador

A opção de navegador no Vitest depende do provedor. O Vitest apresentará um erro se você passar --browser e não especificar o nome do navegador no arquivo de configuração. Opções disponíveis:

• webdriverio suporta estes navegadores:
  • firefox
  • chrome
  • edge
  • safari
• playwright suporta estes navegadores:
  • firefox
  • webkit
  • chromium

Compatibilidade do Navegador

O Vitest utiliza o servidor de desenvolvimento Vite para executar seus testes, portanto, suportamos apenas os recursos especificados na opção esbuild.target (esnext por padrão).

Por padrão, o Vite tem como alvo navegadores que suportam Módulos ES nativos, importação dinâmica ESM nativa e import.meta. Além disso, utilizamos BroadcastChannel para comunicação entre iframes:

• Chrome >=87
• Firefox >=78
• Safari >=15.4
• Edge >=88

Executando Testes

Quando você especifica um nome de navegador na opção browser, o Vitest tentará executar o navegador especificado usando preview por padrão e, em seguida, executará os testes nesse ambiente. Se você não quiser usar preview, pode configurar o provedor de navegador personalizado utilizando a opção browser.provider.

Para especificar um navegador usando a CLI, use a flag --browser seguida do nome do navegador, assim:

npx vitest --browser=chrome

Ou você pode fornecer opções de navegador para a CLI usando a notação de ponto:

npx vitest --browser.name=chrome --browser.headless

Por padrão, o Vitest abrirá automaticamente a interface do usuário do navegador para desenvolvimento. Seus testes serão executados dentro de um iframe centralizado na tela. Você pode configurar a viewport selecionando as dimensões preferidas, invocando page.viewport dentro do teste, ou definindo valores padrão na configuração.

Headless

O modo sem cabeça (headless) é outra opção disponível no modo navegador. No modo headless, o navegador é executado em segundo plano, sem interface gráfica, o que o torna útil para executar testes automatizados. A opção headless no Vitest pode ser definida como true ou false para habilitar ou desabilitar o modo headless.

Ao usar o modo headless, o Vitest não abrirá a interface do usuário automaticamente. Se você quiser continuar usando a interface do usuário e executar os testes em modo headless, pode instalar o pacote @vitest/ui e passar a flag --ui ao executar o Vitest.

Aqui está um exemplo de configuração que habilita o modo headless:

export default defineConfig({
  test: {
    browser: {
      provider: 'playwright',
      enabled: true,
      headless: true,
    },
  },
});

Você também pode definir o modo headless usando a flag --browser.headless na CLI, assim:

npx vitest --browser.name=chrome --browser.headless

Neste caso, o Vitest será executado em modo headless usando o navegador Chrome.

WARNING

O modo headless não está disponível por padrão. Você precisa usar os provedores playwright ou webdriverio para habilitar este recurso.

Exemplos

O Vitest fornece pacotes para renderizar componentes para vários frameworks populares, com suporte nativo:

• vitest-browser-vue para renderizar componentes vue
• vitest-browser-svelte para renderizar componentes svelte
• vitest-browser-react para renderizar componentes react

Se o seu framework não estiver listado, sinta-se à vontade para criar seu próprio pacote – ele é um wrapper simples para o renderizador do framework e a API page.elementLocator. Adicionaremos um link para ele nesta página. Certifique-se de que o nome comece com vitest-browser-.

Além de renderizar componentes e localizar elementos, você também precisará realizar asserções. O Vitest empacota a biblioteca @testing-library/jest-dom para fornecer uma vasta gama de asserções DOM prontas para uso. Saiba mais na API de Asserções.

import { expect } from 'vitest';
import { page } from '@vitest/browser/context';
// elemento renderizado corretamente
await expect.element(page.getByText('Hello World')).toBeInTheDocument();

O Vitest expõe uma API de Contexto com um conjunto de utilitários que podem ser úteis em seus testes. Por exemplo, se você precisar realizar uma interação, como clicar em um elemento ou inserir texto em um campo de entrada, você pode usar userEvent de @vitest/browser/context. Saiba mais na API de Interatividade.

import { page, userEvent } from '@vitest/browser/context';
await userEvent.fill(page.getByLabelText(/username/i), 'Alice');
// ou apenas locator.fill
await page.getByLabelText(/username/i).fill('Alice');

vue

import { render } from 'vitest-browser-vue';
import Component from './Component.vue';

test('properly handles v-model', async () => {
  const screen = render(Component);

  // Verifica o estado inicial.
  await expect
    .element(screen.getByText('Hi, my name is Alice'))
    .toBeInTheDocument();

  // Obtém o nó DOM do campo de entrada consultando o rótulo associado.
  const usernameInput = screen.getByLabelText(/username/i);

  // Digita o nome no campo de entrada. Isso já verifica se o campo de entrada
  // está preenchido corretamente, sem a necessidade de verificar o valor manualmente.
  await usernameInput.fill('Bob');

  await expect
    .element(screen.getByText('Hi, my name is Bob'))
    .toBeInTheDocument();
});

svelte

import { render } from 'vitest-browser-svelte';
import { expect, test } from 'vitest';

import Greeter from './greeter.svelte';

test('greeting appears on click', async () => {
  const screen = render(Greeter, { name: 'World' });

  const button = screen.getByRole('button');
  await button.click();
  const greeting = screen.getByText(/hello world/iu);

  await expect.element(greeting).toBeInTheDocument();
});

react

import { render } from 'vitest-browser-react';
import Fetch from './fetch';

test('loads and displays greeting', async () => {
  // Renderiza elemento React no DOM
  const screen = render(<Fetch url="/greeting" />);

  await screen.getByText('Load Greeting').click();
  // aguarda antes de gerar um erro caso não encontre um elemento
  const heading = screen.getByRole('heading');

  // verifica se a mensagem de alerta está correta
  await expect.element(heading).toHaveTextContent('hello there');
  await expect.element(screen.getByRole('button')).toBeDisabled();
});

Embora o Vitest não ofereça suporte nativo a todos os frameworks, você pode usar ferramentas externas para executar testes com eles. Além disso, incentivamos a comunidade a criar seus próprios wrappers vitest-browser – se você tiver um, sinta-se à vontade para adicioná-lo aos exemplos acima.

Para frameworks não suportados, recomendamos usar os pacotes testing-library:

• @testing-library/preact para renderizar componentes preact
• @solidjs/testing-library para renderizar componentes solid
• @marko/testing-library para renderizar componentes marko

WARNING

testing-library fornece o pacote @testing-library/user-event. Não recomendamos usá-lo diretamente, pois ele simula eventos em vez de realmente acioná-los. Em vez disso, utilize userEvent importado de @vitest/browser/context, que usa o Chrome DevTools Protocol ou Webdriver (dependendo do provedor) internamente.

preact

// baseado no exemplo @testing-library/preact
// https://testing-library.com/docs/preact-testing-library/example

import { h } from 'preact';
import { page } from '@vitest/browser/context';
import { render } from '@testing-library/preact';

import HiddenMessage from '../hidden-message';

test('shows the children when the checkbox is checked', async () => {
  const testMessage = 'Test Message';

  const { baseElement } = render(<HiddenMessage>{testMessage}</HiddenMessage>);

  const screen = page.elementLocator(baseElement);

  // .query() retornará o elemento ou null caso não seja encontrado.
  // .element() retornará o elemento ou lançará um erro caso não seja encontrado.
  expect(screen.getByText(testMessage).query()).not.toBeInTheDocument();

  // As consultas podem receber uma regex para tornar seus seletores mais
  // resistentes a alterações e variações de conteúdo.
  await screen.getByLabelText(/show/i).click();

  await expect.element(screen.getByText(testMessage)).toBeInTheDocument();
});

solid

// baseado na API @testing-library/solid
// https://testing-library.com/docs/solid-testing-library/api

import { render } from '@testing-library/solid';

it('uses params', async () => {
  const App = () => (
    <>
      <Route
        path="/ids/:id"
        component={() => (
          <p>
            Id:
            {useParams()?.id}
          </p>
        )}
      />
      <Route path="/" component={() => <p>Start</p>} />
    </>
  );
  const { baseElement } = render(() => <App />, { location: 'ids/1234' });
  const screen = page.elementLocator(baseElement);

  await expect.screen(screen.getByText('Id: 1234')).toBeInTheDocument();
});

marko

// baseado na API @testing-library/marko
// https://testing-library.com/docs/marko-testing-library/api

import { render, screen } from '@marko/testing-library';
import Greeting from './greeting.marko';

test('renders a message', async () => {
  const { baseElement } = await render(Greeting, { name: 'Marko' });
  const screen = page.elementLocator(baseElement);
  await expect.element(screen.getByText(/Marko/)).toBeInTheDocument();
  await expect.element(container.firstChild).toMatchInlineSnapshot(`
    <h1>Hello, Marko!</h1>
  `);
});

Limitações

Diálogos de Bloqueio de Thread

Ao usar o Vitest Browser, é importante notar que diálogos que bloqueiam a thread, como alert ou confirm, não podem ser usados nativamente. Isso ocorre porque eles bloqueiam a página da web, impedindo a comunicação contínua do Vitest com a página e, consequentemente, causando o travamento da execução.

Nessas situações, o Vitest fornece mocks padrão com valores de retorno predefinidos para essas APIs. Isso garante que, se o usuário acidentalmente usar APIs web de popup síncronas, a execução não será interrompida. No entanto, ainda é recomendado que o usuário crie mocks para essas APIs web para uma melhor experiência. Leia mais em Mocking.