Modo Navegador Experimental

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

TIP

Se você está procurando documentação para expect, vi ou qualquer API geral como projetos de teste ou teste de tipo, consulte o guia "Introdução".

Instalação

Para facilitar a configuração, você pode usar o comando vitest init browser para instalar as dependências necessárias e criar a 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 requer provedores E2E adicionais para executar testes localmente, pois ele reutiliza seu navegador 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 mudar para um deles para testes locais, em vez de usar o provedor preview padrão, já que ele depende da simulação de eventos em vez de usar o Chrome DevTools Protocol.

Se você ainda não usa uma dessas ferramentas, recomendamos começar com o Playwright porque ele suporta execução paralela, o que acelera seus testes. Além disso, o Playwright usa o Chrome DevTools Protocol, que 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 configuração do Vitest, defina o campo browser.enabled como true no seu arquivo de configuração do Vitest. Aqui está um exemplo de configuração usando o campo browser:

import { defineConfig } from 'vitest/config';
export default defineConfig({
  test: {
    browser: {
      provider: 'playwright', // ou 'webdriverio'
      enabled: true,
      // pelo menos uma instância é necessária
      instances: [{ browser: 'chromium' }],
    },
  },
});

INFO

O Vitest reserva 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.

Desde o Vitest 2.1.5, a CLI não exibe mais a URL do Vite automaticamente. Você pode pressionar "b" para imprimir a URL no modo de observação.

Se você nunca usou o Vite antes, certifique-se de ter o plugin do seu framework instalado e especificado na configuração. Alguns frameworks podem exigir configuração extra para funcionar - verifique a documentação relacionada ao Vite para confirmar.

react

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

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

vue

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

export default defineConfig({
  plugins: [vue()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: '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',
      instances: [{ browser: 'chromium' }],
    },
  },
});

solid

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

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

marko

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

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

Se você precisar executar alguns testes usando um executor baseado em Node, você pode definir a opção projects com configurações separadas para diferentes estratégias de teste:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      {
        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,
            instances: [{ browser: 'chromium' }],
          },
        },
      },
    ],
  },
});

Tipos de Opções do Navegador

A opção browser no Vitest depende do provedor. O Vitest falhará se você passar --browser sem especificar seu nome no arquivo de configuração. Opções disponíveis:

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

TypeScript

Por padrão, o TypeScript não reconhece opções de provedores nem as propriedades extras do expect. Se você não usa provedores, certifique-se de que @vitest/browser/matchers seja referenciado em algum lugar nos seus testes, arquivo de setup ou um arquivo de configuração para que as definições extras do expect sejam reconhecidas. Se você estiver usando provedores personalizados, certifique-se de adicionar @vitest/browser/providers/playwright ou @vitest/browser/providers/webdriverio ao mesmo arquivo para que o TypeScript possa carregar as definições para as opções personalizadas:

default

/// <reference types="@vitest/browser/matchers" />

playwright

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

webdriverio

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

Alternativamente, você também pode adicioná-los ao campo compilerOptions.types no seu arquivo tsconfig.json. Observe que especificar qualquer coisa neste campo desativará o carregamento automático de pacotes @types/*.

default

{
  "compilerOptions": {
    "types": ["@vitest/browser/matchers"]
  }
}

playwright

{
  "compilerOptions": {
    "types": ["@vitest/browser/providers/playwright"]
  }
}

webdriverio

{
  "compilerOptions": {
    "types": ["@vitest/browser/providers/webdriverio"]
  }
}

Compatibilidade do Navegador

O Vitest usa o servidor de desenvolvimento Vite para executar seus testes, então 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 nele. Se você não quiser usar preview, pode configurar o provedor de navegador personalizado usando 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=chromium

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

npx vitest --browser.headless

WARNING

Desde o Vitest 3.2, se você não tiver a opção browser em sua configuração, mas especificar a flag --browser, o Vitest apresentará um erro porque não pode assumir que a configuração se destina ao navegador e não a testes Node.js.

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. Você pode configurar a viewport selecionando as dimensões preferidas, chamando page.viewport dentro do teste ou definindo valores padrão na configuração.

Headless

O modo headless é outra funcionalidade disponível no modo navegador. No modo headless, o navegador é executado em segundo plano sem uma interface de usuário, o que o torna útil para executar testes automatizados. A opção headless no Vitest pode ser definida como um valor booleano 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, mas quiser que os testes sejam executados em modo headless, você 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:

import { defineConfig } from 'vitest/config';
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.headless

Neste caso, o Vitest será executado no 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

Por padrão, você não precisa de nenhum pacote externo para trabalhar com o Modo Navegador:

import { expect, test } from 'vitest';
import { page } from '@vitest/browser/context';
import { render } from './my-render-function.js';

test('properly handles form inputs', async () => {
  render(); // monta elementos DOM

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

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

  // Digita o nome na entrada. Isso já valida que a entrada
  // está preenchida corretamente, não há necessidade de verificar o valor manualmente.
  await usernameInput.fill('Bob');

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

No entanto, o Vitest também fornece pacotes para renderizar componentes para vários frameworks populares prontos para uso:

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

Pacotes da comunidade estão disponíveis para outros frameworks:

• vitest-browser-lit para renderizar componentes lit
• vitest-browser-preact para renderizar componentes preact

Se o seu framework não estiver representado, sinta-se à vontade para criar seu próprio pacote - é um wrapper simples em torno do renderizador do framework e da 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á fazer asserções. O Vitest faz um fork da biblioteca @testing-library/jest-dom para fornecer uma ampla gama de asserções DOM prontas para uso. Leia mais na API de Asserções.

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

O Vitest expõe uma API de Contexto com um pequeno conjunto de utilitários que podem ser úteis em seus testes. Por exemplo, se você precisar fazer uma interação, como clicar em um elemento ou digitar texto em um input, você pode usar userEvent de @vitest/browser/context. Leia 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 de entrada consultando o rótulo associado.
  const usernameInput = screen.getByLabelText(/username/i);

  // Digita o nome na entrada. Isso já valida que a entrada
  // está preenchida corretamente, não há 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 um elemento React no DOM
  const screen = render(<Fetch url="/greeting" />);

  await screen.getByText('Load Greeting').click();
  // espera antes de lançar um erro se não conseguir encontrar 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();
});

lit

import { render } from 'vitest-browser-lit';
import { html } from 'lit';
import './greeter-button';

test('greeting appears on click', async () => {
  const screen = render(html`<greeter-button name="World"></greeter-button>`);

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

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

preact

import { render } from 'vitest-browser-preact';
import { createElement } from 'preact';
import Greeting from '.Greeting';

test('greeting appears on click', async () => {
  const screen = render(<Greeting />);

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

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

O Vitest não suporta todos os frameworks de forma nativa, mas você pode usar ferramentas externas para executar testes com esses frameworks. Também encorajamos a comunidade a criar seus próprios vitest-browser wrappers - se você tiver um, sinta-se à vontade para adicioná-lo aos exemplos acima.

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

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

Você pode ver mais exemplos no repositório browser-examples.

WARNING

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

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();
  expect(container.firstChild).toMatchInlineSnapshot(`
    <h1>Hello, Marko!</h1>
  `);
});

Limitações

Diálogos que Bloqueiam a Thread

Ao usar o Vitest Browser, é importante notar que diálogos de bloqueio de thread como alert ou confirm não podem ser usados nativamente. Isso ocorre porque eles bloqueiam a página da web, o que significa que o Vitest não pode continuar se comunicando com a página, causando um travamento na execução.

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