Befehle

Ein Befehl ist eine Funktion, die eine andere Funktion auf dem Server aufruft und das Ergebnis an den Browser zurücksendet. Vitest stellt mehrere integrierte Befehle zur Verfügung, die Sie in Ihren Browser-Tests verwenden können.

Integrierte Befehle

Dateiverwaltung

Sie können die Funktionen readFile, writeFile und removeFile verwenden, um Dateien in Ihren Browser-Tests zu verwalten. Alle Pfade werden relativ zur Testdatei aufgelöst, auch wenn sie in einer Hilfsfunktion in einer anderen Datei aufgerufen werden.

Standardmäßig verwendet Vitest die Codierung utf-8, aber Sie können dies durch Optionen anpassen.

TIP

Diese API unterliegt aus Sicherheitsgründen 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 direkten Zugriff auf das Chrome Devtools Protocol über die Methode cdp, die von @vitest/browser/context exportiert wird. Dies ist hauptsächlich für Bibliotheksentwickler nützlich, um darauf Tools aufzubauen.

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 nur, wenn der chromium-Browser verwendet wird. 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 hinzufügen:

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 den Befehl in Ihrem Test aufrufen, indem Sie ihn von @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 ersetzen integrierte Befehle, wenn sie denselben Namen haben.

Benutzerdefinierte playwright-Befehle

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

• page bezieht sich auf die vollständige Seite, die das Test-Iframe enthält. Dies ist das Orchestrator-HTML, und Sie sollten es höchstwahrscheinlich nicht verändern, um keine Probleme zu verursachen.
• frame ist eine asynchrone Methode, die das Tester Frame zurückgibt. Sie hat eine ähnliche API wie page, unterstützt aber bestimmte Methoden nicht. Wenn Sie ein Element abfragen müssen, sollten Sie stattdessen context.iframe bevorzugen, da dessen Verwendung zuverlässiger und effizienter ist.
• iframe ist ein FrameLocator, der verwendet werden sollte, um andere Elemente auf der Seite abzufragen.
• context bezieht sich 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 zu Ihrem tsconfig-Feld "compilerOptions.types" hinzuzufügen, um Autovervollständigung in der Konfiguration und bei der Verwendung von userEvent und page zu erhalten:

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

Benutzerdefinierte webdriverio-Befehle

Vitest bietet einige webdriverio-spezifische Eigenschaften im Kontextobjekt.

• browser ist die WebdriverIO.Browser-API.

Vitest schaltet den webdriver-Kontext automatisch auf das Test-Iframe um, 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 beziehen sich jedoch weiterhin auf den übergeordneten Frame-Kontext.

TIP

Wenn Sie TypeScript verwenden, vergessen Sie nicht, @vitest/browser/providers/webdriverio zu Ihrem tsconfig-Feld "compilerOptions.types" hinzuzufügen, um die Autovervollständigung zu aktivieren:

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