Справочник по настройке браузера

Вы можете изменить конфигурацию браузера, обновив поле test.browser в вашем файле конфигурации. Пример простого конфигурационного файла:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [
        {
          browser: 'chromium',
          setupFile: './chromium-setup.js',
        },
      ],
    },
  },
});

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

WARNING

Все перечисленные опции на этой странице находятся внутри свойства test в конфигурации:

export default defineConfig({
  test: {
    browser: {},
  },
});

browser.enabled

Тип: boolean
По умолчанию: false
CLI: --browser, --browser.enabled=false

По умолчанию все тесты запускаются в браузере. Обратите внимание, что --browser работает только в том случае, если у вас есть хотя бы один элемент browser.instances.

browser.instances

Тип: BrowserConfig
По умолчанию: [{ browser: name }]

Определяет несколько конфигураций браузера. Каждая конфигурация должна содержать хотя бы поле browser. Конфигурация поддерживает настройки для ваших провайдеров:

TIP

Для лучшей типобезопасности при использовании встроенных провайдеров, вам следует ссылаться на один из этих типов (для используемого вами провайдера) в вашем файле конфигурации:

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

Кроме того, вы также можете указать большинство опций проекта (за исключением отмеченных значком *) и некоторые опции browser, такие как browser.testerHtmlPath.

WARNING

Каждая конфигурация браузера наследует опции из корневой конфигурации:

export default defineConfig({
  test: {
    setupFile: ['./root-setup-file.js'],
    browser: {
      enabled: true,
      testerHtmlPath: './custom-path.html',
      instances: [
        {
          // будут использоваться оба файла настройки: "root" и "browser"
          setupFile: ['./browser-setup-file.js'],
          // неявно наследует "testerHtmlPath" из корневой конфигурации
          // testerHtmlPath: './custom-path.html',
        },
      ],
    },
  },
})

Во время разработки Vitest поддерживает только одну конфигурацию без режима headless. Вы можете запустить проект в режиме с видимым окном, указав headless: false в конфигурации, или используя флаг --browser.headless=false, или отфильтровав проекты с флагом --project=chromium.

Для получения дополнительных примеров обратитесь к руководству "Несколько настроек".

Список доступных опций browser:

browser.headless
browser.locators
browser.viewport
browser.testerHtmlPath
browser.screenshotDirectory
browser.screenshotFailures

По умолчанию Vitest создает массив с одним элементом, где поле browser.name используется как имя браузера. Обратите внимание, что это поведение будет удалено в Vitest 4.

Внутренне Vitest преобразует эти экземпляры в отдельные тестовые проекты, использующие один сервер Vite для повышения производительности кэширования.

browser.name устарело

Тип: string
CLI: --browser=safari

УСТАРЕЛО

Этот API устарел и будет удален в Vitest 4. Пожалуйста, используйте опцию browser.instances вместо него.

Запускает все тесты в указанном браузере. Возможные опции в разных провайдерах:

webdriverio: firefox, chrome, edge, safari
playwright: firefox, webkit, chromium
custom: любая строка, которая будет передана провайдеру

browser.headless

Тип: boolean
По умолчанию: process.env.CI
CLI: --browser.headless, --browser.headless=false

Запускает браузер в безголовом режиме. Если вы запускаете Vitest в CI, он будет включен по умолчанию.

browser.isolate

Тип: boolean
По умолчанию: true
CLI: --browser.isolate, --browser.isolate=false

Запускает каждый тест в отдельном iframe.

browser.testerHtmlPath

Тип: string

Путь к входному HTML-файлу. Может быть относительным к корню проекта. Этот файл будет обработан с помощью хука transformIndexHtml.

browser.api

Тип: number | { port?, strictPort?, host? }
По умолчанию: 63315
CLI: --browser.api=63315, --browser.api.port=1234, --browser.api.host=example.com

Настраивает параметры для сервера Vite, который обслуживает код в браузере. Не затрагивает опцию test.api. По умолчанию Vitest назначает порт 63315, чтобы избежать конфликтов с сервером разработки и обеспечить их параллельный запуск.

browser.provider

Тип: 'webdriverio' | 'playwright' | 'preview' | string
По умолчанию: 'preview'
CLI: --browser.provider=playwright

Указывает путь к провайдеру, который будет использоваться при запуске тестов в браузере. Vitest предоставляет три провайдера: preview (по умолчанию), webdriverio и playwright. Пользовательские провайдеры должны быть экспортированы по умолчанию (default) и соответствовать следующей структуре:

export interface BrowserProvider {
  name: string;
  supportsParallelism: boolean;
  getSupportedBrowsers: () => readonly string[];
  beforeCommand?: (command: string, args: unknown[]) => Awaitable<void>;
  afterCommand?: (command: string, args: unknown[]) => Awaitable<void>;
  getCommandsContext: (sessionId: string) => Record<string, unknown>;
  openPage: (
    sessionId: string,
    url: string,
    beforeNavigate?: () => Promise<void>
  ) => Promise<void>;
  getCDPSession?: (sessionId: string) => Promise<CDPSession>;
  close: () => Awaitable<void>;
  initialize(
    ctx: TestProject,
    options: BrowserProviderInitializationOptions
  ): Awaitable<void>;
}

РАСШИРЕННЫЙ API

API пользовательских провайдеров является крайне экспериментальным и может изменяться в последующих версиях (патчах). Если вам просто нужно запустить тесты в браузере, используйте опцию browser.instances.

browser.providerOptions устарело

Тип: BrowserProviderOptions

УСТАРЕЛО

Этот API устарел и будет удален в Vitest 4. Пожалуйста, используйте опцию browser.instances вместо него.

Параметры, передаваемые провайдеру при вызове provider.initialize.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    browser: {
      providerOptions: {
        launch: {
          devtools: true,
        },
      },
    },
  },
});

TIP

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

browser.ui

Тип: boolean
По умолчанию: !isCI
CLI: --browser.ui=false

Определяет, должен ли Vitest UI быть внедрен на страницу. По умолчанию встраивает UI iframe во время разработки.

browser.viewport

Тип: { width, height }
По умолчанию: 414x896

Размер области просмотра iframe по умолчанию.

browser.locators

Настройки для встроенных локаторов браузера.

browser.locators.testIdAttribute

Тип: string
По умолчанию: data-testid

Атрибут, который используется для поиска элементов с помощью локатора getByTestId.

browser.screenshotDirectory

Тип: string
По умолчанию: __screenshots__ в каталоге тестового файла

Путь к каталогу скриншотов относительно корня проекта.

browser.screenshotFailures

Тип: boolean
По умолчанию: !browser.ui

Определяет, должен ли Vitest делать скриншоты в случае сбоя теста.

browser.orchestratorScripts

Тип: BrowserScript[]
По умолчанию: []

Пользовательские скрипты, которые будут внедрены в HTML-файл оркестратора до инициализации тестовых iframe. Этот HTML-документ только настраивает iframe и не импортирует ваш код.

Поля src и content скрипта будут обработаны плагинами Vite. Скрипт должен соответствовать следующей структуре:

export interface BrowserScript {
  /**
   * Если предоставлен "content" и тип "module", это будет его идентификатор.
   *
   * Например, если вы используете TypeScript, можно добавить расширение `.ts`.
   * @default `injected-${index}.js`
   */
  id?: string;
  /**
   * Содержимое JavaScript для встраивания. Эта строка будет обработана плагинами Vite, если тип "module".
   *
   * Вы можете использовать `id`, чтобы указать Vite на расширение файла.
   */
  content?: string;
  /**
   * Путь к скрипту. Это значение разрешается Vite, поэтому может быть модулем Node.js или путем к файлу.
   */
  src?: string;
  /**
   * Определяет, должен ли скрипт загружаться асинхронно.
   */
  async?: boolean;
  /**
   * Тип скрипта.
   * @default 'module'
   */
  type?: string;
}

browser.testerScripts

Тип: BrowserScript[]
По умолчанию: []

УСТАРЕЛО

Этот API устарел и будет удален в Vitest 4. Пожалуйста, используйте поле browser.testerHtmlPath вместо него.

Пользовательские скрипты, которые будут внедрены в HTML-файл тестера до инициализации тестовой среды. Это полезно для внедрения полифиллов, необходимых для работы Vitest в браузере. В большинстве случаев вместо этого рекомендуется использовать setupFiles.

Поля src и content скрипта будут обработаны плагинами Vite.

browser.commands

Тип: Record<string, BrowserCommand>
По умолчанию: { readFile, writeFile, ... }

Пользовательские команды, которые можно импортировать во время тестов в браузере из @vitest/browser/commands.

browser.connectTimeout

Тип: number
По умолчанию: 60_000

Время ожидания (таймаут) в миллисекундах. Если подключение к браузеру превышает указанное время, тестовый набор завершится с ошибкой.

INFO

Это время, необходимое браузеру для установки WebSocket-соединения с сервером Vitest. В обычных условиях этот таймаут, как правило, не должен быть достигнут.

Справочник по настройке браузера ​

browser.enabled ​

browser.instances ​

browser.name устарело ​

browser.headless ​

browser.isolate ​

browser.testerHtmlPath ​

browser.api ​

browser.provider ​

browser.providerOptions устарело ​

browser.ui ​

browser.viewport ​

browser.locators ​

browser.locators.testIdAttribute ​

browser.screenshotDirectory ​

browser.screenshotFailures ​

browser.orchestratorScripts ​

browser.testerScripts ​

browser.commands ​

browser.connectTimeout ​

Справочник по настройке браузера

browser.enabled

browser.instances

browser.name устарело

browser.headless

browser.isolate

browser.testerHtmlPath

browser.api

browser.provider

browser.providerOptions устарело

browser.ui

browser.viewport

browser.locators

browser.locators.testIdAttribute

browser.screenshotDirectory

browser.screenshotFailures

browser.orchestratorScripts

browser.testerScripts

browser.commands

browser.connectTimeout