Commandes

Une commande est une fonction qui exécute une autre fonction sur le serveur et transmet le résultat au navigateur. Vitest expose 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. Tous les chemins sont résolus par rapport au fichier de test, même s'ils sont appelés dans une fonction d'assistance située dans un autre fichier.

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 construire des outils basés dessus.

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 fournisseur 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 fournir au moyen d'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 à partir de @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 la commande.

• page fait référence à la page complète qui contient l'iframe de test. Il s'agit du HTML de l'orchestrateur et vous ne devriez probablement pas y toucher afin de ne pas perturber son fonctionnement.
• frame est une méthode asynchrone qui résoudra le Frame associé au test. Elle a une API similaire à celle de la page, mais elle ne prend pas en charge certaines méthodes. Si vous avez besoin d'interroger un élément, il est préférable d'utiliser context.iframe car il est plus stable et plus rapide.
• iframe est un FrameLocator qui devrait être utilisé 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 d'ajouter @vitest/browser/providers/playwright au champ "compilerOptions.types" de votre tsconfig pour obtenir l'autocomplétion dans la configuration et sur les options userEvent et page :

{
  "compilerOptions": {
    "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 commute automatiquement le contexte webdriver vers l'iframe de test en appelant browser.switchToFrame avant que la commande ne soit appelée, de sorte que les méthodes $ et $$ se réfèrent aux éléments à l'intérieur de l'iframe, et non dans l'orchestrateur, mais les API non-webdriver feront toujours référence au contexte du frame parent.

TIP

Si vous utilisez TypeScript, n'oubliez pas d'ajouter @vitest/browser/providers/webdriverio au champ "compilerOptions.types" de votre tsconfig pour obtenir l'autocomplétion :

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