Comandos

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

Comandos Integrados

Manejo de Archivos

Puedes usar las API readFile, writeFile y removeFile para manejar archivos dentro de tus pruebas de navegador. Todas las rutas se resuelven en relación con el archivo de prueba, incluso si se llaman en una función auxiliar ubicada en otro archivo.

Por defecto, Vitest utiliza la codificación utf-8, pero puedes sobrescribirla con 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 el acceso directo al Protocolo de Chrome DevTools (CDP) a través del método cdp exportado desde @vitest/browser/context. Es principalmente útil para los autores de bibliotecas para construir herramientas basadas en él.

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 solo funciona con el proveedor playwright y únicamente 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 });
});

// if you are using TypeScript, you can augment the module
declare module '@vitest/browser/context' {
  interface BrowserCommands {
    myCustomCommand: (
      arg1: string,
      arg2: string
    ) => Promise<{
      someValue: true;
    }>;
  }
}

WARNING

Las funciones personalizadas sobrescribirán 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 se refiere a la página completa que contiene el iframe de prueba. Este es el HTML del orquestador y es muy probable que no debas modificarlo para no romper nada.
• frame es un método asíncrono que devolverá el Frame del probador. Su API es similar a la de page, pero no admite ciertos métodos. Si necesitas consultar un elemento, deberías 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();
    // do something with the screenshot
    return difference;
  }
};

TIP

Si estás usando TypeScript, no olvides agregar @vitest/browser/providers/playwright a tu campo "compilerOptions.types" de tsconfig para obtener autocompletado en la configuración y en las opciones de userEvent y page:

{
  "compilerOptions": {
    "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 al 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 $$ se refieren a los elementos dentro del iframe, no en el orquestador, pero las APIs no pertenecientes a webdriver seguirán refiriéndose al contexto del frame padre.

TIP

Si estás usando TypeScript, no olvides agregar @vitest/browser/providers/webdriverio a tu campo "compilerOptions.types" de tsconfig para obtener autocompletado:

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