Polecenia

Polecenie to funkcja, która jest wykonywana na serwerze i zwraca wynik 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 korzystać z API readFile, writeFile i removeFile do obsługi plików w testach przeglądarkowych. Wszystkie ścieżki są ustalane względem pliku testowego, nawet jeśli są wywoływane w funkcji pomocniczej znajdującej się w innym pliku.

Domyślnie Vitest używa kodowania utf-8, ale można je nadpisać za pomocą opcji.

TIP

To API jest ograniczone przez 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 pomocą metody cdp eksportowanej z @vitest/browser/context. Jest to przydatne głównie dla autorów bibliotek do tworzenia narzędzi opartych na tym protokole.

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 providerem playwright i tylko w przypadku użycia przeglądarki chromium. Więcej na ten temat można przeczytać w dokumentacji CDPSession Playwright.

Niestandardowe polecenia

Możesz też dodać własne polecenia przy użyciu opcji konfiguracyjnej browser.commands. Jeśli tworzysz 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 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, jeśli mają taką 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 i najprawdopodobniej nie powinieneś go modyfikować, aby niczego nie uszkodzić.
• frame to metoda asynchroniczna, która zwróci obiekt Frame. 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 dodać @vitest/browser/providers/playwright do pola "compilerOptions.types" w swoim tsconfig, aby uzyskać autouzupełnianie w konfiguracji oraz dla opcji userEvent i page:

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

Niestandardowe polecenia webdriverio

Vitest udostępnia kilka właściwości specyficznych dla webdriverio w obiekcie kontekstu.

• browser to API WebdriverIO.Browser.

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

TIP

Jeśli używasz TypeScript, nie zapomnij dodać @vitest/browser/providers/webdriverio do pola "compilerOptions.types" w swoim tsconfig, aby uzyskać autouzupełnianie:

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