Befehle

Ein Befehl ist eine Funktion, die einen Aufruf an den Server sendet und das Ergebnis an den Browser zurückleitet. Vitest bietet mehrere integrierte Befehle, die Sie in Ihren Browser-Tests verwenden können.

Integrierte Befehle

Dateihandhabung

Sie können die APIs readFile, writeFile und removeFile verwenden, um Dateien in Ihren Browser-Tests zu verwalten. Seit Vitest 3.2 werden alle Pfade relativ zum Projekt-Root aufgelöst (was process.cwd() ist, sofern nicht manuell überschrieben). Zuvor wurden Pfade relativ zur Testdatei aufgelöst.

Standardmäßig verwendet Vitest die utf-8-Kodierung. Sie können diese Kodierung jedoch mit Optionen überschreiben.

TIP

Aus Sicherheitsgründen unterliegt diese API den Einschränkungen von server.fs.

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

CDP-Sitzung

Vitest ermöglicht den Zugriff auf das native Chrome DevTools Protocol (CDP) über die cdp-Methode, die aus @vitest/browser/context exportiert wird. Dies ist hauptsächlich für Bibliotheksautoren nützlich, um darauf aufbauende Tools zu entwickeln.

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

Die CDP-Sitzung funktioniert nur mit dem playwright-Provider und ausschließlich bei Verwendung des chromium-Browsers. Weitere Informationen dazu finden Sie in der CDPSession-Dokumentation von Playwright.

Benutzerdefinierte Befehle

Sie können auch Ihre eigenen Befehle über die Konfigurationsoption browser.commands hinzufügen. Wenn Sie eine Bibliothek entwickeln, können Sie diese über einen config-Hook innerhalb eines Plugins bereitstellen:

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

Anschließend können Sie ihn in Ihrem Test aufrufen, indem Sie ihn aus @vitest/browser/context importieren:

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

Benutzerdefinierte Befehle überschreiben integrierte Befehle, wenn sie denselben Namen haben.

Benutzerdefinierte playwright-Befehle

Vitest stellt mehrere playwright-spezifische Eigenschaften im Befehlskontext zur Verfügung:

• page verweist auf die vollständige Seite, die das Test-Iframe enthält. Dies ist das Orchestrator-HTML, und Sie sollten es höchstwahrscheinlich nicht manipulieren, um keine Probleme zu verursachen.
• frame ist eine asynchrone Methode, die den Tester Frame auflöst. Sie hat eine ähnliche API wie die page, unterstützt aber bestimmte Methoden nicht. Wenn Sie ein Element abfragen müssen, sollten Sie stattdessen context.iframe bevorzugen, da es stabiler und effizienter ist.
• iframe ist ein FrameLocator, der zum Abfragen anderer Elemente auf der Seite verwendet werden sollte.
• context verweist auf den eindeutigen BrowserContext.

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

Wenn Sie TypeScript verwenden, vergessen Sie nicht, @vitest/browser/providers/playwright in Ihrer Setup-Datei oder einer Konfigurationsdatei einzubinden, um die Autovervollständigung in der Konfiguration und in den Optionen userEvent und page zu erhalten:

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

Benutzerdefinierte webdriverio-Befehle

Vitest stellt einige webdriverio-spezifische Eigenschaften im Kontextobjekt zur Verfügung:

• browser ist die WebdriverIO.Browser-API.

Vitest wechselt den webdriver-Kontext automatisch in den Test-Iframe, indem es browser.switchToFrame aufruft, bevor der Befehl ausgeführt wird. Dadurch beziehen sich die Methoden $ und $$ auf die Elemente innerhalb des Iframes und nicht auf den Orchestrator. Nicht-Webdriver-APIs operieren jedoch weiterhin im übergeordneten Frame-Kontext.

TIP

Wenn Sie TypeScript verwenden, vergessen Sie nicht, @vitest/browser/providers/webdriverio in Ihrer Setup-Datei oder einer Konfigurationsdatei einzubinden, um die Autovervollständigung zu erhalten:

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