Commandes

Une commande est une fonction qui permet d'invoquer une autre fonction sur le serveur et de transmettre son résultat au navigateur. Vitest propose plusieurs commandes intégrées que vous pouvez utiliser dans vos tests de navigateur.

Commandes intégrées

Gestion des fichiers

Vous pouvez utiliser les API readFile, writeFile et removeFile pour gérer les fichiers dans vos tests de navigateur. Depuis Vitest 3.2, tous les chemins sont résolus par rapport à la racine du projet (qui est process.cwd(), sauf remplacement manuel). Auparavant, les chemins étaient résolus par rapport au fichier de test.

Par défaut, Vitest utilise l'encodage utf-8, mais vous pouvez le remplacer via les options.

TIP

Cette API respecte les limitations de server.fs pour des raisons de sécurité.

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

Session CDP

Vitest expose l'accès au protocole brut Chrome DevTools via la méthode cdp exportée depuis @vitest/browser/context. Elle est principalement utile aux auteurs de bibliothèques pour développer des outils basés sur ce protocole.

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 session CDP ne fonctionne qu'avec le provider playwright et uniquement lors de l'utilisation du navigateur chromium. Vous pouvez en savoir plus à ce sujet dans la documentation CDPSession de Playwright.

Commandes personnalisées

Vous pouvez également ajouter vos propres commandes via l'option de configuration browser.commands. Si vous développez une bibliothèque, vous pouvez les rendre disponibles via un hook config au sein d'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,
            },
          },
        },
      };
    },
  };
}

Vous pouvez ensuite l'appeler dans votre test en l'important depuis @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

Les fonctions personnalisées remplaceront les fonctions intégrées si elles ont le même nom.

Commandes playwright personnalisées

Vitest expose plusieurs propriétés spécifiques à playwright sur le contexte de commande.

• page fait référence à la page complète qui contient l'iframe de test. C'est le HTML de l'orchestrateur et il est préférable de ne pas y toucher pour éviter de causer des problèmes.
• frame est une méthode asynchrone qui résoudra le Frame du test. Elle a une API similaire à la page, mais elle ne supporte pas certaines méthodes. Si vous avez besoin de sélectionner un élément, il est préférable d'utiliser context.iframe car il est plus stable et plus rapide.
• iframe est un FrameLocator à utiliser pour interroger d'autres éléments sur la page.
• context fait référence au BrowserContext unique.

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 vous utilisez TypeScript, n'oubliez pas de référencer @vitest/browser/providers/playwright dans votre fichier de configuration initiale ou un fichier de configuration pour obtenir l'autocomplétion dans la configuration et dans les options userEvent et page :

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

Commandes webdriverio personnalisées

Vitest expose certaines propriétés spécifiques à webdriverio sur l'objet de contexte.

• browser est l'API WebdriverIO.Browser.

Vitest change automatiquement le contexte webdriver vers l'iframe de test en appelant browser.switchToFrame avant l'exécution de la commande. Ainsi, les méthodes $ et $$ font référence aux éléments à l'intérieur de l'iframe, et non à ceux de l'orchestrateur. Cependant, les API non-webdriver continueront de faire référence au contexte du frame parent.

TIP

Si vous utilisez TypeScript, n'oubliez pas de référencer @vitest/browser/providers/webdriverio dans votre fichier de configuration initiale ou un fichier de configuration pour obtenir l'autocomplétion :

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