Modo Navegador Experimental

Esta página proporciona información sobre la característica experimental del modo navegador en Vitest, que le permite ejecutar sus pruebas de forma nativa en el navegador, proporcionando acceso a objetos globales del navegador como window y document. Esta característica se encuentra actualmente en desarrollo y las APIs podrían cambiar en el futuro.

Instalación

Para una configuración más sencilla, puede usar el comando vitest init browser para instalar las dependencias necesarias y crear la configuración del navegador.

npm

npx vitest init browser

yarn

yarn exec vitest init browser

pnpm

pnpx vitest init browser

bun

bunx vitest init browser

Instalación Manual

También puede instalar los paquetes de forma manual. Por defecto, el Modo Navegador no requiere proveedores E2E adicionales para ejecutar pruebas localmente, ya que reutiliza su navegador actual.

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

Sin embargo, para ejecutar pruebas en CI, necesita instalar playwright o webdriverio. También recomendamos cambiar a uno de ellos para las pruebas locales en lugar de usar el proveedor preview predeterminado, ya que se basa en la simulación de eventos en lugar de usar el Protocolo de Herramientas de Desarrollo de Chrome.

Si aún no utiliza una de estas herramientas, le recomendamos que comience con Playwright, ya que soporta la ejecución paralela, lo que hace que sus pruebas se ejecuten más rápido. Además, el Protocolo de Herramientas de Desarrollo de Chrome que utiliza Playwright es generalmente más rápido que WebDriver.

::: tabs key:provider == Playwright Playwright es un framework para Pruebas Web y Automatización.

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 le permite ejecutar pruebas localmente usando el 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

Configuración

Para activar el modo navegador en su configuración de Vitest, puede usar la bandera --browser o establecer el campo browser.enabled en true en su archivo de configuración de Vitest. Aquí tiene un ejemplo de configuración que utiliza el campo browser:

export default defineConfig({
  test: {
    browser: {
      provider: 'playwright', // o 'webdriverio'
      enabled: true,
      name: 'chromium', // el nombre del navegador es requerido
    },
  },
});

INFO

Vitest asigna el puerto 63315 para evitar conflictos con el servidor de desarrollo, lo que le permite ejecutar ambos en paralelo. Puede cambiar esto con la opción browser.api.

Desde Vitest 2.1.5, la CLI ya no imprime la URL de Vite automáticamente. Puede presionar "b" para imprimir la URL cuando se ejecuta en modo de observación.

Si no ha utilizado Vite antes, asegúrese de tener el plugin de su framework instalado y configurado. Algunos frameworks pueden requerir configuración adicional para que funcionen; consulte su documentación relacionada con Vite para asegurarse.

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 no requiere un plugin para su funcionamiento, pero preact requiere configuración extra para que los alias funcionen correctamente.

Si necesita ejecutar algunas pruebas usando un ejecutor basado en Node, puede definir un archivo de espacio de trabajo con configuraciones separadas para diferentes estrategias de prueba:

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

export default defineWorkspace([
  {
    test: {
      // un ejemplo de convención basada en archivos,
      // no tiene que seguirla
      include: [
        'tests/unit/**/*.{test,spec}.ts',
        'tests/**/*.unit.{test,spec}.ts',
      ],
      name: 'unit',
      environment: 'node',
    },
  },
  {
    test: {
      // un ejemplo de convención basada en archivos,
      // no tiene que seguirla
      include: [
        'tests/browser/**/*.{test,spec}.ts',
        'tests/**/*.browser.{test,spec}.ts',
      ],
      name: 'browser',
      browser: {
        enabled: true,
        name: 'chrome',
      },
    },
  },
]);

Configuración del Proveedor

:::tabs key:provider == Playwright Puede configurar cómo Vitest lanza el navegador y crea el contexto de página a través del campo providerOptions:

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

Para tener sugerencias de tipos, agregue @vitest/browser/providers/playwright a compilerOptions.types en su archivo tsconfig.json. == WebdriverIO Puede configurar qué opciones debe usar Vitest al iniciar un navegador a través del campo providerOptions:

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

Para tener sugerencias de tipos, agregue @vitest/browser/providers/webdriverio a compilerOptions.types en su archivo tsconfig.json. :::

Tipos de Opciones del Navegador

La opción de navegador en Vitest depende del proveedor. Vitest fallará si se pasa --browser y no se especifica su nombre en el archivo de configuración. Opciones disponibles:

• webdriverio soporta estos navegadores:
  • firefox
  • chrome
  • edge
  • safari
• playwright soporta estos navegadores:
  • firefox
  • webkit
  • chromium

Compatibilidad del Navegador

Vitest utiliza el servidor de desarrollo de Vite para ejecutar sus pruebas, por lo que solo soporta las características especificadas en la opción esbuild.target (esnext por defecto).

Por defecto, Vite apunta a navegadores que soportan Módulos ES nativos, importación dinámica ESM nativa, y import.meta. Además, utilizamos BroadcastChannel para comunicarnos entre iframes:

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

Ejecución de Pruebas

Cuando especifica un nombre de navegador en la opción browser, Vitest intentará ejecutar el navegador especificado usando preview por defecto, y luego ejecutará las pruebas en él. Si no desea usar preview, puede configurar el proveedor de navegador personalizado usando la opción browser.provider.

Para especificar un navegador usando la CLI, use la bandera --browser seguida del nombre del navegador, así:

npx vitest --browser=chrome

O puede proporcionar opciones de navegador a la CLI con notación de puntos:

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

Por defecto, Vitest abrirá automáticamente la interfaz de usuario del navegador para desarrollar. Sus pruebas se ejecutarán dentro de un iframe. Puede configurar el viewport seleccionando las dimensiones preferidas, invocando page.viewport dentro de la prueba, o estableciendo valores predeterminados en la configuración.

Sin interfaz gráfica (Headless)

El modo headless es otra opción disponible en el modo navegador. En el modo headless, el navegador se ejecuta en segundo plano sin una interfaz de usuario, lo que lo hace útil para ejecutar pruebas automatizadas. La opción headless en Vitest puede configurarse con un valor booleano para habilitar o deshabilitar el modo headless.

Cuando se usa el modo headless, Vitest no abrirá automáticamente la interfaz de usuario. Si desea seguir usando la interfaz de usuario pero ejecutar las pruebas en modo headless, puede instalar el paquete @vitest/ui y pasar la bandera --ui al ejecutar Vitest.

Aquí hay un ejemplo de configuración que habilita el modo headless:

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

También puede establecer el modo headless usando la bandera --browser.headless en la CLI, así:

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

En este caso, Vitest se ejecutará en modo headless usando el navegador Chrome.

WARNING

El modo headless no está disponible por defecto. Necesita usar los proveedores playwright o webdriverio para habilitar esta característica.

Ejemplos

Vitest proporciona paquetes para renderizar componentes para varios frameworks populares listos para usar:

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

Si su framework no está representado, no dude en crear su propio paquete; es un simple envoltorio alrededor del renderizador del framework y la API page.elementLocator. Agregaremos un enlace a él en esta página. Asegúrese de que su nombre comience con vitest-browser-.

Además de renderizar componentes y localizar elementos, también necesitará hacer aserciones. Vitest incluye la biblioteca @testing-library/jest-dom para proporcionar una amplia gama de aserciones DOM listas para usar. Lea más en la API de Aserciones.

import { expect } from 'vitest';
import { page } from '@vitest/browser/context';
// el elemento se renderiza correctamente
await expect.element(page.getByText('Hello World')).toBeInTheDocument();

Vitest expone una API de Contexto con un pequeño conjunto de utilidades que pueden resultarle útiles en las pruebas. Por ejemplo, si necesita realizar una interacción, como hacer clic en un elemento o introducir texto en un campo de entrada, puede usar userEvent de @vitest/browser/context. Lea más en la API de Interactividad.

import { page, userEvent } from '@vitest/browser/context';
await userEvent.fill(page.getByLabelText(/username/i), 'Alice');
// o simplemente 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);

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

  // Obtiene el nodo DOM del input consultando la etiqueta asociada.
  const usernameInput = screen.getByLabelText(/username/i);

  // Escribe el nombre en el input. Esto ya valida que el input
  // se ha rellenado correctamente, sin necesidad de verificar el 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 un elemento React en el DOM
  const screen = render(<Fetch url="/greeting" />);

  await screen.getByText('Load Greeting').click();
  // espera un momento antes de lanzar un error si no se encuentra el elemento
  const heading = screen.getByRole('heading');

  // afirma que el mensaje de alerta es correcto
  await expect.element(heading).toHaveTextContent('hello there');
  await expect.element(screen.getByRole('button')).toBeDisabled();
});

Vitest no soporta todos los frameworks de serie, pero puede usar herramientas externas para ejecutar pruebas con estos frameworks. También animamos a la comunidad a crear sus propios vitest-browser wrappers; si tiene uno, no dude en agregarlo a los ejemplos anteriores.

Para frameworks no soportados, recomendamos usar los paquetes 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 proporciona un paquete @testing-library/user-event. No recomendamos usarlo directamente porque simula eventos en lugar de dispararlos realmente; en su lugar, use userEvent importado de @vitest/browser/context que utiliza el Protocolo de Herramientas de Desarrollo de Chrome o Webdriver (dependiendo del proveedor) en segundo plano.

preact

// basado en el ejemplo de @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() devolverá el elemento o null si no se puede encontrar.
  // .element() devolverá el elemento o lanzará un error si no se encuentra.
  expect(screen.getByText(testMessage).query()).not.toBeInTheDocument();

  // Las consultas pueden aceptar una expresión regular para que sus selectores sean más
  // resistentes a ajustes y cambios de contenido.
  await screen.getByLabelText(/show/i).click();

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

solid

// basado en la API de @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

// basado en la API de @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>
  `);
});

Limitaciones

Diálogos que Bloquean Hilos

Al usar Vitest Browser, es importante tener en cuenta que los diálogos de bloqueo de hilo como alert o confirm no se pueden usar de forma nativa. Esto se debe a que bloquean la página web, lo que significa que Vitest no puede seguir comunicándose con la página, provocando que la ejecución se cuelgue.

En tales situaciones, Vitest proporciona mocks por defecto con valores de retorno predeterminados para estas APIs. Esto garantiza que si el usuario usa accidentalmente APIs web síncronas de ventanas emergentes, la ejecución no se bloqueará. Sin embargo, aún se recomienda que el usuario simule estas APIs web para una experiencia óptima. Lea más en Mocking.