Referencia de Configuración del Navegador

Puede cambiar la configuración del navegador mediante la actualización del campo test.browser en su archivo de configuración. Un ejemplo de un archivo de configuración sencillo:

import { defineConfig } from 'vitest/config';

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

Consulta el artículo "Referencia de Configuración" para ver diferentes ejemplos de configuración.

WARNING

Todas las opciones listadas en esta página se encuentran dentro de la propiedad test en la configuración:

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

browser.enabled

• Tipo: boolean
• Por defecto: false
• CLI: --browser, --browser.enabled=false

Ejecuta todas las pruebas en un navegador. Ten en cuenta que --browser solo funciona si tienes al menos un elemento configurado en browser.instances.

browser.instances

• Tipo: BrowserConfig
• Por defecto: [{ browser: name }]

Define múltiples configuraciones de navegadores. Cada configuración debe tener al menos un campo browser. Esta configuración es compatible con las opciones de tus proveedores:

• Configurando Playwright
• Configurando WebdriverIO

TIP

Para una mejor seguridad de tipos al usar proveedores integrados, debes hacer referencia a uno de estos tipos (para el proveedor que estés usando) en tu archivo de configuración:

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

Además, también puedes especificar la mayoría de las opciones de proyecto (no marcadas con el icono *) y algunas de las opciones de browser como browser.testerHtmlPath.

WARNING

Cada configuración de navegador hereda opciones de la configuración raíz:

export default defineConfig({
  test: {
    setupFile: ['./root-setup-file.js'],
    browser: {
      enabled: true,
      testerHtmlPath: './custom-path.html',
      instances: [
        {
          // tendrá ambos archivos de configuración: "root" y "browser"
          setupFile: ['./browser-setup-file.js'],
          // implícitamente tiene "testerHtmlPath" de la configuración raíz
          // testerHtmlPath: './custom-path.html',
        },
      ],
    },
  },
})

Durante el desarrollo, Vitest solo admite una configuración no-headless. Puedes limitar el proyecto con interfaz gráfica tú mismo especificando headless: false en la configuración, o proporcionando la bandera --browser.headless=false, o filtrando proyectos con la bandera --project=chromium.

Para más ejemplos, consulta la guía "Múltiples Configuraciones".

Lista de opciones browser disponibles:

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

Por defecto, Vitest crea un array con un solo elemento que usa el campo browser.name como browser. Ten en cuenta que este comportamiento se eliminará con Vitest 4.

Internamente, Vitest transforma estas instancias en proyectos de prueba separados que comparten un único servidor Vite para un mejor rendimiento de caché.

browser.name obsoleto

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

OBSOLETO

Esta API está obsoleta y se eliminará en Vitest 4. Usa la opción browser.instances en su lugar.

Ejecuta todas las pruebas en un navegador específico. Posibles opciones en diferentes proveedores:

• webdriverio: firefox, chrome, edge, safari
• playwright: firefox, webkit, chromium
• personalizado: cualquier cadena que se pasará al proveedor

browser.headless

• Tipo: boolean
• Por defecto: process.env.CI
• CLI: --browser.headless, --browser.headless=false

Ejecuta el navegador en modo sin interfaz gráfica (headless). Si estás ejecutando Vitest en CI, se habilitará por defecto.

browser.isolate

• Tipo: boolean
• Por defecto: true
• CLI: --browser.isolate, --browser.isolate=false

Ejecuta cada prueba en un iframe separado.

browser.testerHtmlPath

• Tipo: string

Ruta al punto de entrada HTML. Puede ser relativa a la raíz del proyecto. Este archivo se procesará con el hook transformIndexHtml.

browser.api

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

Configura las opciones para el servidor Vite que sirve el código en el navegador. No afecta la opción test.api. Por defecto, Vitest asigna el puerto 63315 para evitar conflictos con el servidor de desarrollo, lo que te permite ejecutar ambos en paralelo.

browser.provider

• Tipo: 'webdriverio' | 'playwright' | 'preview' | string
• Por defecto: 'preview'
• CLI: --browser.provider=playwright

Ruta a un proveedor para ejecutar pruebas de navegador. Vitest proporciona tres proveedores: preview (por defecto), webdriverio y playwright. Los proveedores personalizados deben exportarse usando la exportación default y tener esta forma:

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 AVANZADA

La API de proveedor personalizado es experimental y puede cambiar entre parches. Si solo necesitas ejecutar pruebas en un navegador, usa la opción browser.instances en su lugar.

browser.providerOptions obsoleto

• Tipo: BrowserProviderOptions

OBSOLETO

Esta API está obsoleta y se eliminará en Vitest 4. Usa la opción browser.instances en su lugar.

Opciones que se pasarán al proveedor al llamar a provider.initialize.

import { defineConfig } from 'vitest/config';

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

TIP

Para una mejor seguridad de tipos al usar proveedores integrados, debes hacer referencia a uno de estos tipos (para el proveedor que estés usando) en tu archivo de configuración:

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

browser.ui

• Tipo: boolean
• Por defecto: !isCI
• CLI: --browser.ui=false

¿Debe inyectarse la interfaz de usuario de Vitest en la página? Por defecto, el iframe de la interfaz de usuario se inyecta durante el desarrollo.

browser.viewport

• Tipo: { width, height }
• Por defecto: 414x896

Viewport predeterminado del iframe.

browser.locators

Opciones para los localizadores de navegador integrados.

browser.locators.testIdAttribute

• Tipo: string
• Por defecto: data-testid

Atributo para encontrar elementos con el localizador getByTestId.

browser.screenshotDirectory

• Tipo: string
• Por defecto: __screenshots__ en el directorio del archivo de prueba

Ruta al directorio de capturas de pantalla relativa a la root.

browser.screenshotFailures

• Tipo: boolean
• Por defecto: !browser.ui

Indica si Vitest debe tomar capturas de pantalla cuando falla una prueba.

browser.orchestratorScripts

• Tipo: BrowserScript[]
• Por defecto: []

Scripts personalizados que deben inyectarse en el HTML del orquestador antes de que se inicien los iframes de prueba. Este documento HTML solo configura los iframes y no importa tu código.

El src y el content del script serán procesados por los plugins de Vite. El script debe proporcionarse de la siguiente forma:

export interface BrowserScript {
  /**
   * Si se proporciona "content" y el tipo es "module", este será su identificador.
   *
   * Si estás usando TypeScript, puedes añadir la extensión `.ts` aquí, por ejemplo.
   * @default `injected-${index}.js`
   */
  id?: string;
  /**
   * Contenido JavaScript a inyectar. Esta cadena es procesada por los plugins de Vite si el tipo es "module".
   *
   * Puedes usar `id` para darle a Vite una pista sobre la extensión del archivo.
   */
  content?: string;
  /**
   * Ruta al script. Este valor es resuelto por Vite, por lo que puede ser un módulo de Node.js o una ruta de archivo.
   */
  src?: string;
  /**
   * Si el script debe cargarse asincrónicamente.
   */
  async?: boolean;
  /**
   * Tipo de script.
   * @default 'module'
   */
  type?: string;
}

browser.testerScripts

• Tipo: BrowserScript[]
• Por defecto: []

OBSOLETO

Esta API está obsoleta y se eliminará en Vitest 4. Usa el campo browser.testerHtmlPath en su lugar.

Scripts personalizados que deben inyectarse en el HTML del probador antes de que se inicie el entorno de pruebas. Esto es útil para inyectar polyfills requeridos para la implementación del navegador de Vitest. Se recomienda usar setupFiles en casi todos los casos en lugar de esta opción.

El src y el content del script serán procesados por los plugins de Vite.

browser.commands

• Tipo: Record<string, BrowserCommand>
• Por defecto: { readFile, writeFile, ... }

Comandos personalizados que se pueden importar durante las pruebas del navegador desde @vitest/browser/commands.

browser.connectTimeout

• Tipo: number
• Por defecto: 60_000

Tiempo de espera en milisegundos. Si la conexión al navegador tarda más, el conjunto de pruebas fallará.

INFO

Este es el tiempo que debe tardar el navegador en establecer la conexión WebSocket con el servidor Vitest. En circunstancias normales, este tiempo de espera nunca debería alcanzarse.