Comandos

Un comando es una función que invoca otra función en el servidor y devuelve el resultado al navegador. Vitest expone varios comandos integrados que puedes usar en tus pruebas de navegador.

Comandos integrados

Gestión de archivos

Puedes usar las APIs readFile, writeFile y removeFile para gestionar archivos en tus pruebas de navegador. Desde Vitest 3.2, todas las rutas se resuelven relativas a la raíz del proyecto (que es process.cwd(), a menos que se anule manualmente). Anteriormente, las rutas se resolvían en relación con el archivo de prueba.

Por omisión, Vitest usa codificación utf-8, pero puedes anularla utilizando opciones.

TIP

Esta API sigue las limitaciones de server.fs por razones de seguridad.

import { server } from '@vitest/browser/context';

const { readFile, writeFile, removeFile } = server.commands;

it('handles files', async () => {
  const file = './test.txt';

  await writeFile(file, 'hello world');
  const content = await readFile(file);

  expect(content).toBe('hello world');

  await removeFile(file);
});

Sesión CDP

Vitest expone acceso directo al Protocolo de DevTools de Chrome (CDP) a través del método cdp exportado desde @vitest/browser/context. Resulta especialmente útil para desarrolladores de bibliotecas que quieran construir herramientas sobre este protocolo.

import { cdp } from '@vitest/browser/context';

const input = document.createElement('input');
document.body.appendChild(input);
input.focus();

await cdp().send('Input.dispatchKeyEvent', {
  type: 'keyDown',
  text: 'a',
});

expect(input).toHaveValue('a');

WARNING

La sesión CDP funciona únicamente con el proveedor playwright y cuando se utiliza el navegador chromium. Puedes leer más sobre esto en la documentación de CDPSession de Playwright.

Comandos personalizados

También puedes agregar tus propios comandos a través de la opción de configuración browser.commands. Si desarrollas una biblioteca, puedes proporcionarlos a través de un hook config dentro de un plugin:

import type { Plugin } from 'vitest/config';
import type { BrowserCommand } from 'vitest/node';

const myCustomCommand: BrowserCommand<[arg1: string, arg2: string]> = (
  { testPath, provider },
  arg1,
  arg2
) => {
  if (provider.name === 'playwright') {
    console.log(testPath, arg1, arg2);
    return { someValue: true };
  }

  throw new Error(`provider ${provider.name} is not supported`);
};

export default function BrowserCommands(): Plugin {
  return {
    name: 'vitest:custom-commands',
    config() {
      return {
        test: {
          browser: {
            commands: {
              myCustomCommand,
            },
          },
        },
      };
    },
  };
}

Luego puedes llamarlo dentro de tu prueba importándolo desde @vitest/browser/context:

import { commands } from '@vitest/browser/context';
import { expect, test } from 'vitest';

test('custom command works correctly', async () => {
  const result = await commands.myCustomCommand('test1', 'test2');
  expect(result).toEqual({ someValue: true });
});

// si estás usando TypeScript, puedes extender el módulo
declare module '@vitest/browser/context' {
  interface BrowserCommands {
    myCustomCommand: (
      arg1: string,
      arg2: string
    ) => Promise<{
      someValue: true;
    }>;
  }
}

WARNING

Las funciones personalizadas reemplazarán a las integradas si tienen el mismo nombre.

Comandos personalizados de playwright

Vitest expone varias propiedades específicas de playwright en el contexto del comando.

• page hace referencia a la página completa que contiene el iframe de prueba. Este es el HTML del orquestador y normalmente no deberías modificarlo para evitar problemas.
• frame es un método asíncrono que resolverá el Frame del probador. Tiene una API similar a la de page, pero no soporta ciertos métodos. Si necesitas consultar un elemento, debes preferir usar context.iframe en su lugar porque es más estable y rápido.
• iframe es un FrameLocator que debe usarse para consultar otros elementos en la página.
• context se refiere al BrowserContext único.

import { BrowserCommand } from 'vitest/node';

export const myCommand: BrowserCommand<[string, number]> = async (
  ctx,
  arg1: string,
  arg2: number
) => {
  if (ctx.provider.name === 'playwright') {
    const element = await ctx.iframe.findByRole('alert');
    const screenshot = await element.screenshot();
    // realiza alguna acción con la captura de pantalla
    return difference;
  }
};

TIP

Si estás usando TypeScript, no olvides hacer referencia a @vitest/browser/providers/playwright en tu archivo de configuración o en un archivo de configuración para obtener autocompletado en la configuración y en las opciones de userEvent y page:

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

Comandos personalizados de webdriverio

Vitest expone algunas propiedades específicas de webdriverio en el objeto de contexto.

• browser es la API WebdriverIO.Browser.

Vitest cambia automáticamente el contexto de webdriver al iframe de prueba llamando a browser.switchToFrame antes de que se llame al comando, por lo que los métodos $ y $$ hacen referencia a los elementos dentro del iframe, no en el orquestador, pero las APIs que no son de webdriver seguirán refiriéndose al contexto del marco padre.

TIP

Si estás usando TypeScript, no olvides hacer referencia a @vitest/browser/providers/webdriverio en tu archivo de configuración o en un archivo de configuración para obtener autocompletado:

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