Команды

Команда — это функция, которая вызывает другую функцию на сервере и передает результат обратно в браузер. Vitest включает несколько встроенных команд, доступных для использования в ваших браузерных тестах.

Встроенные команды

Работа с файлами

Вы можете использовать API readFile, writeFile и removeFile для работы с файлами в ваших браузерных тестах. Начиная с Vitest 3.2, все пути разрешаются относительно корня проекта (который является process.cwd(), если не переопределен вручную). Ранее пути разрешались относительно тестового файла.

По умолчанию Vitest использует кодировку utf-8, но вы можете переопределить ее с помощью опций.

TIP

Этот API подчиняется ограничениям 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

Vitest предоставляет доступ к необработанному протоколу Chrome Devtools через метод cdp, экспортируемый из @vitest/browser/context. Он в первую очередь полезен для авторов библиотек, которые создают инструменты на его основе.

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

Сессия CDP работает только с провайдером playwright и только при использовании браузера chromium. Вы можете прочитать об этом подробнее в документации CDPSession Playwright.

Пользовательские команды

Вы также можете добавлять свои собственные команды через опцию конфигурации browser.commands. Если вы разрабатываете библиотеку, вы можете предоставить их с помощью хука config внутри плагина:

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

Затем вы можете вызвать ее внутри своего теста, импортировав из @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

Пользовательские функции переопределят встроенные, если у них одинаковое имя.

Пользовательские команды playwright

Vitest предоставляет несколько специфичных для playwright свойств в контексте команды:

• page ссылается на полную страницу, содержащую тестовый iframe. Это основная HTML-страница, и вам, скорее всего, не следует ее трогать, чтобы ничего не сломать.
• frame — это асинхронный метод, который возвращает Frame тестовой среды. У него похожий API на page, но он не поддерживает некоторые методы. Если вам нужно запросить элемент, вы должны предпочесть использование context.iframe, потому что это более надежно и быстрее.
• iframe — это FrameLocator, который следует использовать для запроса других элементов на странице.
• context ссылается на уникальный 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

Если вы используете TypeScript, не забудьте сослаться на @vitest/browser/providers/playwright в вашем файле настройки или файле конфигурации, чтобы получить автодополнение в конфигурации и в опциях userEvent и page:

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

Пользовательские команды webdriverio

Vitest предоставляет некоторые специфичные для webdriverio свойства в объекте контекста:

• browser — это API WebdriverIO.Browser.

Vitest автоматически переключает контекст webdriver на тестовый iframe, вызывая browser.switchToFrame перед вызовом команды, поэтому методы $ и $$ ссылаются на элементы внутри iframe, а не в оркестраторе, но API, не относящиеся к webdriver, по-прежнему будут ссылаться на контекст родительского фрейма.

TIP

Если вы используете TypeScript, не забудьте сослаться на @vitest/browser/providers/webdriverio в вашем файле настройки или файле конфигурации, чтобы получить автодополнение:

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