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 dentro de seus testes de navegador. Todos os caminhos são resolvidos em relação ao arquivo de teste, mesmo que sejam chamados em uma função auxiliar localizada em outro arquivo.

Por padrão, o Vitest usa a codificação utf-8, mas você pode substituí-la através das opções.

TIP

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

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

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

it('manipula 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 expõe acesso direto ao Chrome Devtools Protocol através do método cdp exportado de @vitest/browser/context. Isso é particularmente ú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 ao usar o navegador chromium. 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 seu teste 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 aumentar o módulo
declare module '@vitest/browser/context' {
  interface BrowserCommands {
    myCustomCommand: (
      arg1: string,
      arg2: string
    ) => Promise<{
      someValue: true;
    }>;
  }
}

WARNING

Funções personalizadas substituirão as funções integradas se tiverem o mesmo nome.

Comandos personalizados do playwright

O Vitest expõe várias propriedades específicas do playwright no contexto do comando.

• page refere-se à página completa que contém o iframe de teste. Este é o HTML do orquestrador e você provavelmente não deve modificá-lo para evitar problemas.
• frame é um método assíncrono que resolverá para o Frame do testador. Ele tem uma API similar à da page, mas não suporta alguns métodos. Se você precisar localizar um elemento, deve preferir usar context.iframe em vez disso, pois é mais estável e rápido.
• iframe é um FrameLocator que deve ser usado para consultar outros elementos na página.
• context refere-se 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();
    // faça algo com a captura de tela
    return difference;
  }
};

TIP

Se você estiver usando TypeScript, não se esqueça de adicionar @vitest/browser/providers/playwright ao campo "compilerOptions.types" do seu tsconfig para obter autocompletar na configuração e nas opções userEvent e page.

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

Comandos personalizados do webdriverio

O Vitest expõe algumas propriedades específicas do webdriverio no objeto de contexto.

• browser é a API WebdriverIO.Browser.

O Vitest muda automaticamente o contexto webdriver para o iframe de teste chamando browser.switchToFrame antes que o comando seja chamado. Assim, os métodos $ e $$ referem-se aos elementos dentro do iframe, não no orquestrador, mas as APIs não-webdriver ainda farão referência ao contexto do frame pai.

TIP

Se você estiver usando TypeScript, não se esqueça de adicionar @vitest/browser/providers/webdriverio ao campo "compilerOptions.types" do seu tsconfig para obter autocompletar.

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