Polecenia

Polecenie to funkcja, która wywołuje inną funkcję na serwerze i przekazuje wynik z powrotem do przeglądarki. Vitest udostępnia kilka wbudowanych poleceń, których można używać w testach przeglądarkowych.

Wbudowane polecenia

Obsługa plików

Możesz używać API readFile, writeFile i removeFile do obsługi plików w testach przeglądarkowych. Od Vitest 3.2, wszystkie ścieżki są rozwiązywane względem katalogu głównego projektu (którym jest process.cwd(), chyba że zostanie ręcznie nadpisane). Wcześniej ścieżki były rozwiązywane względem pliku testowego.

Domyślnie Vitest stosuje kodowanie utf-8, ale można je nadpisać, korzystając z opcji.

TIP

To API podlega ograniczeniom server.fs ze względów bezpieczeństwa.

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

Sesja CDP

Vitest udostępnia bezpośredni dostęp do protokołu Chrome Devtools Protocol za pośrednictwem metody cdp eksportowanej z @vitest/browser/context. Jest to głównie przydatne dla autorów bibliotek, którzy budują na jego podstawie narzędzia.

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

Sesja CDP działa tylko z dostawcą playwright i tylko podczas używania przeglądarki chromium. Więcej na ten temat można przeczytać w dokumentacji CDPSession Playwrighta.

Niestandardowe polecenia

Możesz również dodawać własne polecenia za pomocą opcji konfiguracyjnej browser.commands. Jeśli rozwijasz bibliotekę, możesz je udostępnić za pomocą haka config wewnątrz wtyczki:

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

Następnie możesz je wywołać w swoim teście, importując z @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

Niestandardowe funkcje nadpiszą wbudowane funkcje, jeśli mają tę samą nazwę.

Niestandardowe polecenia playwright

Vitest udostępnia kilka właściwości specyficznych dla playwright w kontekście polecenia.

• page odnosi się do pełnej strony zawierającej iframe testowy. Jest to HTML orkiestratora, którego nie powinieneś modyfikować, aby nie zepsuć działania.
• frame to asynchroniczna metoda, która zwróci obiekt Frame testera. Ma podobne API do page, ale nie obsługuje niektórych metod. Jeśli musisz wyszukać element, powinieneś preferować użycie context.iframe, ponieważ jest bardziej stabilny i szybszy.
• iframe to FrameLocator, który powinien być używany do wyszukiwania innych elementów na stronie.
• context odnosi się do unikalnego 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

Jeśli używasz TypeScript, nie zapomnij odwołać się do @vitest/browser/providers/playwright w swoim pliku setup lub pliku konfiguracyjnym, aby uzyskać podpowiedzi w konfiguracji oraz w opcjach userEvent i page:

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

Niestandardowe polecenia webdriverio

Vitest udostępnia niektóre właściwości specyficzne dla webdriverio w obiekcie kontekstu.

• browser to API WebdriverIO.Browser.

Vitest automatycznie przełącza kontekst webdriver na iframe testowy, wywołując browser.switchToFrame przed wywołaniem polecenia, więc metody $ i $$ dotyczą elementów wewnątrz iframe, a nie w orkiestratorze, ale API nienależące do webdrivera nadal będą odnosić się do kontekstu ramki nadrzędnej.

TIP

Jeśli używasz TypeScript, nie zapomnij odwołać się do @vitest/browser/providers/webdriverio w swoim pliku setup lub pliku konfiguracyjnym, aby uzyskać podpowiedzi:

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