브라우저 설정 참조

구성 파일의 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

이 옵션이 true로 설정되면 모든 테스트가 브라우저 환경에서 실행됩니다. --browser CLI 플래그는 browser.instances 항목이 하나 이상 정의되어 있을 때만 작동합니다.

browser.instances

유형: BrowserConfig
기본값: [{ browser: name }]

여러 브라우저 설정을 정의합니다. 각 구성 객체는 최소한 browser 필드를 포함해야 합니다. 이 구성은 다음 공급자 설정을 지원합니다:

TIP

기본 제공 공급자를 사용할 때 더 나은 타입 안전성을 위해, 구성 파일에서 사용 중인 공급자에 해당하는 다음 타입 중 하나를 참조해야 합니다:

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

또한, * 아이콘으로 표시되지 않은 대부분의 프로젝트 옵션과 browser.testerHtmlPath와 같은 일부 browser 옵션을 지정할 수 있습니다.

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: false를 지정하거나, --browser.headless=false 플래그를 제공하거나, --project=chromium 플래그로 프로젝트를 필터링하여 헤드리스가 아닌 프로젝트를 직접 제한할 수 있습니다.

더 많은 예시는 "다중 설정" 가이드를 참조하십시오.

사용 가능한 browser 옵션 목록:

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

기본적으로 Vitest는 browser.name 필드를 browser로 사용하는 단일 요소 배열을 생성합니다. 이 동작은 Vitest 4에서 제거될 예정입니다.

내부적으로 Vitest는 더 나은 캐싱 성능을 위해 이러한 인스턴스를 단일 Vite 서버를 공유하는 별도의 테스트 프로젝트로 변환합니다.

browser.name deprecated

유형: string
CLI: --browser=safari

DEPRECATED

이 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

브라우저를 headless 모드로 실행할지 여부를 결정합니다. CI 환경에서 Vitest를 실행할 경우 기본적으로 활성화됩니다.

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

ADVANCED API

사용자 정의 공급자 API는 매우 실험적이며 패치 릴리스에 따라 변경될 수 있습니다. 브라우저에서 테스트를 실행하기만 하면 되는 경우, 대신 browser.instances 옵션을 사용하십시오.

browser.providerOptions deprecated

유형: BrowserProviderOptions

DEPRECATED

이 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__

root에 상대적인 스크린샷 디렉토리의 경로입니다.

browser.screenshotFailures

유형: boolean
기본값: !browser.ui

테스트 실패 시 Vitest가 스크린샷을 찍을지 여부를 결정합니다.

browser.orchestratorScripts

유형: BrowserScript[]
기본값: []

테스트 iframe이 시작되기 전에 오케스트레이터 HTML에 주입될 사용자 정의 스크립트입니다. 이 HTML 문서는 iframe만 설정하며 실제 코드를 가져오지 않습니다.

스크립트 src 및 content는 Vite 플러그인에 의해 처리됩니다. 스크립트는 다음 형태로 제공됩니다:

export interface BrowserScript {
  /**
   * "content"가 제공되고 타입이 "module"인 경우, 이것이 식별자로 사용됩니다.
   *
   * TypeScript를 사용하는 경우, 여기에 `.ts` 확장자를 추가할 수 있습니다.
   * @default `injected-${index}.js`
   */
  id?: string;
  /**
   * 주입할 JavaScript 콘텐츠입니다. 이 문자열은 타입이 "module"인 경우 Vite 플러그인에 의해 처리됩니다.
   *
   * `id`를 사용하여 Vite에 파일 확장자에 대한 힌트를 줄 수 있습니다.
   */
  content?: string;
  /**
   * 스크립트 경로입니다. 이 값은 Vite에 의해 해석되어 노드 모듈 또는 파일 경로가 될 수 있습니다.
   */
  src?: string;
  /**
   * 스크립트가 비동기적으로 로드될지 여부입니다.
   */
  async?: boolean;
  /**
   * 스크립트 타입입니다.
   * @default 'module'
   */
  type?: string;
}

browser.testerScripts

유형: BrowserScript[]
기본값: []

DEPRECATED

이 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

이는 브라우저가 Vitest 서버와 WebSocket 연결을 설정하는 데 소요되는 시간입니다. 정상적인 상황에서는 이 타임아웃에 도달해서는 안 됩니다.

브라우저 설정 참조 ​

browser.enabled ​

browser.instances ​

browser.name deprecated ​

browser.headless ​

browser.isolate ​

browser.testerHtmlPath ​

browser.api ​

browser.provider ​

browser.providerOptions deprecated ​

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 deprecated

browser.headless

browser.isolate

browser.testerHtmlPath

browser.api

browser.provider

browser.providerOptions deprecated

browser.ui

browser.viewport

browser.locators

browser.locators.testIdAttribute

browser.screenshotDirectory

browser.screenshotFailures

browser.orchestratorScripts

browser.testerScripts

browser.commands

browser.connectTimeout