Comandi

Un comando è una funzione che invoca un'altra funzione sul server e ne passa il risultato al browser. Vitest espone diversi comandi integrati che puoi utilizzare nei tuoi test browser.

Comandi Integrati

Gestione File

Puoi usare le API readFile, writeFile e removeFile per gestire i file nei tuoi test browser. A partire da Vitest 3.2, tutti i percorsi sono risolti rispetto alla root del progetto (che è process.cwd(), a meno che non venga sovrascritto manualmente). In precedenza, i percorsi erano risolti relativamente al file di test.

Per impostazione predefinita, Vitest utilizza la codifica utf-8, ma puoi sovrascriverla tramite le opzioni.

TIP

Questa API segue le limitazioni di server.fs per motivi di sicurezza.

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);
});

Sessione CDP

Vitest espone l'accesso diretto al protocollo Chrome Devtools tramite il metodo cdp esportato da @vitest/browser/context. È principalmente utile per gli autori di librerie che desiderano sviluppare strumenti basati su di esso.

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 sessione CDP funziona solo con il provider playwright e solo quando si usa il browser chromium. Puoi leggere di più a riguardo nella documentazione CDPSession di Playwright.

Comandi Personalizzati

Puoi anche aggiungere i tuoi comandi utilizzando l'opzione di configurazione browser.commands. Se sviluppi una libreria, puoi fornirli tramite un hook config all'interno di 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,
            },
          },
        },
      };
    },
  };
}

Puoi quindi chiamarlo all'interno del tuo test importandolo da @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 });
});

// se stai usando TypeScript, puoi estendere il modulo
declare module '@vitest/browser/context' {
  interface BrowserCommands {
    myCustomCommand: (
      arg1: string,
      arg2: string
    ) => Promise<{
      someValue: true;
    }>;
  }
}

WARNING

Le funzioni personalizzate sovrascriveranno quelle integrate se portano lo stesso nome.

Comandi playwright personalizzati

Vitest espone diverse proprietà specifiche di playwright sul contesto del comando.

• page fa riferimento alla pagina completa che contiene l'iframe di test. Questo è l'HTML principale e probabilmente non dovresti modificarlo per non comprometterne il funzionamento.
• frame è un metodo asincrono che restituirà il Frame del tester. Ha un'API simile a quella di page, ma non supporta alcuni metodi. Se hai bisogno di selezionare un elemento, è consigliabile utilizzare context.iframe perché è più stabile e veloce.
• iframe è un FrameLocator che dovrebbe essere usato per selezionare altri elementi sulla pagina.
• context si riferisce al BrowserContext unico.

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();
    // fai qualcosa con lo screenshot
    return difference;
  }
};

TIP

Se stai usando TypeScript, non dimenticare di fare riferimento a @vitest/browser/providers/playwright nel tuo file di setup o in un file di configurazione per ottenere l'autocompletamento nella configurazione e nelle opzioni userEvent e page:

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

Comandi webdriverio personalizzati

Vitest espone alcune proprietà specifiche di webdriverio sull'oggetto contesto.

• browser è l'API WebdriverIO.Browser.

Vitest passa automaticamente al contesto webdriver dell'iframe di test chiamando browser.switchToFrame prima che venga eseguito il comando; pertanto, i metodi $ e $$ si riferiscono agli elementi all'interno dell'iframe, non nell'orchestratore, mentre le API non-webdriver continueranno a fare riferimento al contesto del frame padre.

TIP

Se stai usando TypeScript, non dimenticare di fare riferimento a @vitest/browser/providers/webdriverio nel tuo file di setup o in un file di configurazione per ottenere l'autocompletamento:

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