Commandes

La commande est une fonction qui invoque une autre fonction sur le serveur et renvoie 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 l’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 par des options.

Astuce

Cette API suit 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 Chrome Devtools brut via la méthode cdp exportée de @vitest/browser/context. Cela est principalement utile aux auteurs de bibliothèques pour construire des outils 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')

Attention

La session CDP fonctionne uniquement 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 via un hook config à l’intérieur 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,
            }
          }
        }
      }
    }
  }
}

Ensuite, vous pouvez l’appeler à l’intérieur de votre test en l’importation 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 })
})

// si vous utilisez TypeScript, vous pouvez augmenter le module
declare module '@vitest/browser/context' {
  interface BrowserCommands {
    myCustomCommand: (arg1: string, arg2: string) => Promise<{
      someValue: true
    }>
  }
}

Attention

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

Commandes personnalisées playwright

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. C’est l’HTML de l’orchestrateur et vous ne devriez probablement pas y toucher pour ne pas casser des choses.
• frame est une méthode asynchrone qui résoudra le Frame de test. Elle a une API similaire à celle de la page, mais ne prend pas en charge certaines méthodes. Si vous devez interroger un élément, vous devriez préférer utiliser context.iframe car il est plus stable et plus rapide.
• iframe est un FrameLocator qui doit ê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()
    // faire quelque chose avec la capture d'écran
    return difference
  }
}

Astuce

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 personnalisées webdriverio

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

• browser est l’API WebdriverIO.Browser.

Vitest passe automatiquement le contexte webdriver à l’iframe de test en appelant browser.switchToFrame avant que la commande ne soit appelée, donc les méthodes $ et $$ font référence aux éléments à l’intérieur de l’iframe, et non dans l’orchestrateur, mais les API non-webdriver continueront de faire référence au contexte de la frame parent.

Astuce

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"
    ]
  }
}