Modo Navegador experimental

Esta página describe la función experimental del modo navegador en la API de Vitest, que permite ejecutar pruebas directamente en el navegador, dando acceso a objetos globales del navegador como window y document. Esta función está actualmente en desarrollo y las APIs podrían cambiar en el futuro.

Compatibilidad del navegador

Vitest utiliza Vite dev server para ejecutar tus pruebas, por lo que solo admitimos las funciones especificadas en la opción esbuild.target (esnext de forma predeterminada).

De forma predeterminada, Vite se dirige a navegadores que admiten ES Modules nativos, importación dinámica ESM nativa e import.meta. Además, utilizamos BroadcastChannel para comunicarnos entre iframes:

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

Motivación

Hemos desarrollado el modo navegador de Vitest para optimizar los flujos de trabajo de las pruebas y obtener resultados más precisos y confiables. Esta adición experimental a nuestra API de pruebas permite a los desarrolladores ejecutar pruebas en un entorno de navegador nativo. En esta sección, exploraremos las motivaciones detrás de esta función y sus beneficios para las pruebas.

Diferentes formas de probar

Existen varias formas de probar código JavaScript. Algunos frameworks de pruebas simulan entornos de navegador en Node.js, mientras que otros ejecutan pruebas en navegadores reales. En este contexto, jsdom es un ejemplo de una implementación de especificación que simula un entorno de navegador al ser utilizado con un gestor de pruebas como Jest o Vitest. Por otro lado, herramientas como WebdriverIO o Cypress permiten a los desarrolladores probar sus aplicaciones en un navegador real. Playwright, por su parte, proporciona un motor de navegador.

La limitación de la simulación

Probar programas JavaScript en entornos simulados como jsdom o happy-dom ha simplificado la configuración de las pruebas y ha proporcionado una API fácil de usar. Esto los hace adecuados para muchos proyectos y aumenta la confianza en los resultados de las pruebas. Sin embargo, es importante recordar que estas herramientas simulan un entorno de navegador, no un navegador real, lo que puede generar discrepancias. Por lo tanto, pueden ocurrir falsos positivos o negativos en los resultados de las pruebas.

Por eso hemos desarrollado el modo navegador en Vitest, que permite a los desarrolladores ejecutar pruebas de manera nativa en un navegador y obtener resultados más precisos y confiables. Con las pruebas a nivel de navegador, los desarrolladores pueden tener más confianza en que su aplicación funcionará como se espera en un escenario del mundo real.

Desventajas

Es importante considerar las siguientes desventajas al usar el navegador Vitest:

Etapa temprana de desarrollo

La función de modo navegador de Vitest aún está en sus primeras etapas de desarrollo. Por lo tanto, es posible que aún no esté completamente optimizada y que existan errores o problemas por resolver. Se recomienda que los usuarios complementen su experiencia con Vitest utilizando un gestor de pruebas independiente en el navegador, como WebdriverIO, Cypress o Playwright.

Inicialización más lenta

El navegador Vitest requiere iniciar el proveedor y el navegador durante la inicialización, lo que puede llevar tiempo. Esto puede resultar en tiempos de inicialización más lentos en comparación con otros métodos de prueba.

Configuración

Para activar el modo navegador en la configuración de Vitest, se puede usar el flag --browser o establecer el valor true en el campo browser.enabled del archivo de configuración. A continuación, se muestra un ejemplo de configuración que usa el campo browser:

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      name: 'chrome', // el nombre del navegador es obligatorio
    },
  },
});

Opciones del Navegador:

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

• webdriverio (por defecto) soporta estos navegadores:
  • firefox
  • chrome
  • edge
  • safari
• playwright soporta estos navegadores:
  • firefox
  • webkit
  • chromium

Pruebas entre navegadores:

Cuando se especifica un navegador en la opción correspondiente, Vitest intentará ejecutarlo usando WebdriverIO de forma predeterminada, y luego ejecutará las pruebas. Esta función facilita el uso y la configuración de pruebas en varios navegadores en entornos como CI (Integración Continua). Si no se desea usar WebdriverIO, se puede configurar un proveedor de navegador personalizado mediante la opción browser.provider.

Para especificar un navegador desde la CLI, use el flag --browser seguido del nombre del navegador, de la siguiente manera:

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

NOTE

Cuando utilice la opción de navegador Safari con WebdriverIO, el safaridriver necesita ser activado ejecutando sudo safaridriver --enable en su dispositivo.

Además, al ejecutar sus pruebas, Vitest intentará instalar algunos drivers para la compatibilidad con safaridriver.

Headless (Sin interfaz gráfica)

El modo sin interfaz gráfica es otra opción disponible en el modo navegador. En el modo sin interfaz gráfica, el navegador se ejecuta en segundo plano, lo que resulta útil para ejecutar pruebas automatizadas. La opción para el modo sin interfaz gráfica en Vitest se puede establecer en un valor booleano para habilitar o deshabilitar esta función.

A continuación, se muestra un ejemplo de configuración que habilita el modo sin interfaz gráfica:

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

También se puede establecer el modo sin interfaz gráfica usando el flag --browser.headless en la CLI, de la siguiente manera:

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

En este caso, Vitest se ejecutará en modo sin interfaz gráfica usando el navegador Chrome.

Limitaciones

Diálogos que bloquean el hilo principal

Al usar el Navegador Vitest, es importante tener en cuenta que los diálogos que bloquean el hilo principal, como alert o confirm, no se pueden usar de forma nativa. Esto se debe a que bloquean la página web, impidiendo que Vitest se comunique con ella y provocando que la ejecución se detenga.

En estas situaciones, Vitest proporciona mocks predeterminados con valores de retorno predeterminados para estas APIs. Esto asegura que, si el usuario usa accidentalmente las APIs web emergentes síncronas, la ejecución no se detendrá. Sin embargo, se recomienda que el usuario cree mocks para estas APIs web para una mejor experiencia. Lea más en Mocking.