Comandi

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

Comandi integrati

Gestione file

Puoi utilizzare le API readFile, writeFile e removeFile per gestire i file all'interno dei tuoi test eseguiti nel browser. Tutti i percorsi vengono risolti in relazione al file di test, anche se vengono chiamati in una funzione helper situata in un altro file.

Per impostazione predefinita, Vitest utilizza la codifica utf-8, ma puoi modificarla 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 al protocollo Chrome Devtools tramite il metodo cdp esportato da @vitest/browser/context. È particolarmente utile agli sviluppatori di librerie per creare 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 è disponibile solo con il provider playwright e solo quando si utilizza il browser chromium. Puoi leggere di più a riguardo nella documentazione CDPSession di playwright.

Comandi personalizzati

Puoi anche aggiungere comandi personalizzati utilizzando l'opzione di configurazione browser.commands. Se stai sviluppando una libreria, puoi fornirli tramite un hook config in 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 });
});

// 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

Le funzioni personalizzate sostituiranno 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 dell'ambiente principale e probabilmente non dovresti toccarlo per non rompere nulla.
• frame è un metodo asincrono che risolverà il Frame del tester. Offre un'API simile a page, ma non supporta alcuni metodi. Se hai bisogno di interrogare un elemento, dovresti preferire usare context.iframe perché è più stabile e veloce.
• iframe è un FrameLocator che dovrebbe essere utilizzato per interrogare altri elementi sulla pagina.
• context fa riferimento al BrowserContext univoco.

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 stai usando TypeScript, non dimenticare di aggiungere @vitest/browser/providers/playwright al campo "compilerOptions.types" del tuo tsconfig per ottenere l'autocompletamento nella configurazione e sulle opzioni userEvent e page:

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

Comandi webdriverio personalizzati

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

• browser è l'API WebdriverIO.Browser.

Vitest imposta automaticamente il contesto webdriver sull'iframe di test chiamando browser.switchToFrame prima che il comando venga chiamato, quindi i metodi $ e $$ si riferiscono agli elementi all'interno dell'iframe, non nell'ambiente principale, ma le API non-webdriver si riferiranno comunque al contesto del frame padre.

TIP

Se stai usando TypeScript, non dimenticare di aggiungere @vitest/browser/providers/webdriverio al campo "compilerOptions.types" del tuo tsconfig per ottenere l'autocompletamento:

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