Comandos

Um comando é uma função que invoca outra função no servidor e retorna o resultado para o navegador. O Vitest oferece vários comandos integrados que você pode usar em seus testes de navegador.

Comandos Integrados

Manipulação de Arquivos

Você pode usar as APIs readFile, writeFile e removeFile para manipular arquivos em seus testes de navegador. A partir do Vitest 3.2, todos os caminhos são resolvidos em relação à raiz do projeto (que é process.cwd(), a menos que seja sobrescrito manualmente). Anteriormente, os caminhos eram resolvidos em relação ao arquivo de teste.

Por padrão, o Vitest usa a codificação utf-8, mas você pode sobrescrevê-la com opções.

TIP

Esta API segue as limitações de server.fs por motivos de segurança.

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

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

it('lida com arquivos', async () => {
  const file = './test.txt';

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

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

  await removeFile(file);
});

Sessão CDP

O Vitest fornece acesso ao Protocolo de Ferramentas do Desenvolvedor do Chrome (CDP) bruto através do método cdp exportado de @vitest/browser/context. É principalmente útil para autores de bibliotecas que desejam construir ferramentas sobre ele.

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

A sessão CDP funciona apenas com o provedor playwright e somente quando o navegador chromium é utilizado. Você pode ler mais sobre isso na documentação CDPSession do Playwright.

Comandos Personalizados

Você também pode adicionar seus próprios comandos através da opção de configuração browser.commands. Se você estiver desenvolvendo uma biblioteca, pode fornecê-los através de um hook config dentro de um 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(`o provedor ${provider.name} não é suportado`);
};

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

Então você pode chamá-lo em seus testes importando-o de @vitest/browser/context:

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

test('comando personalizado funciona corretamente', async () => {
  const result = await commands.myCustomCommand('test1', 'test2');
  expect(result).toEqual({ someValue: true });
});

// se você estiver usando TypeScript, pode estender o módulo
declare module '@vitest/browser/context' {
  interface BrowserCommands {
    myCustomCommand: (
      arg1: string,
      arg2: string
    ) => Promise<{
      someValue: true;
    }>;
  }
}

WARNING

Funções personalizadas sobrescreverão as embutidas se tiverem o mesmo nome.

Comandos playwright personalizados

O Vitest disponibiliza várias propriedades específicas do playwright no contexto do comando:

• page se refere à página completa que contém o iframe de teste. Este é o HTML do orquestrador e você provavelmente não deve modificá-lo para não causar problemas.
• frame é um método assíncrono que retornará o Frame do testador. Ele tem uma API semelhante à page, mas não oferece suporte a alguns métodos. Se você precisar consultar um elemento, deve preferir usar context.iframe, pois é mais estável e rápido.
• iframe é um FrameLocator que deve ser usado para consultar outros elementos na página.
• context se refere ao 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

Se você estiver usando TypeScript, não se esqueça de referenciar @vitest/browser/providers/playwright em seu arquivo de inicialização ou em um arquivo de configuração para obter autocompletar na configuração e nas opções userEvent e page:

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

Comandos webdriverio personalizados

O Vitest disponibiliza algumas propriedades específicas do webdriverio no objeto de contexto:

• browser é a API WebdriverIO.Browser.

O Vitest alterna automaticamente o contexto do webdriver para o iframe de teste, chamando browser.switchToFrame antes da execução do comando. Dessa forma, os métodos $ e $$ se referem aos elementos dentro do iframe, e não no orquestrador. No entanto, as APIs que não são do webdriver ainda farão referência ao contexto do frame pai.

TIP

Se você estiver usando TypeScript, não se esqueça de referenciar @vitest/browser/providers/webdriverio em seu arquivo de configuração ou em um arquivo de configuração para obter autocompletar:

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