브라우저 모드 실험적

이 페이지는 Vitest API의 실험적인 브라우저 모드 기능에 대한 정보를 제공합니다. 이 기능을 통해 브라우저 환경에서 직접 테스트를 실행하여 window 및 document와 같은 브라우저 전역 객체에 접근할 수 있습니다. 이 기능은 현재 개발 중이며, API는 향후 변경될 수 있습니다.

TIP

expect, vi 또는 테스트 프로젝트나 타입 테스트와 같은 일반 API에 대한 문서를 찾고 있다면 "시작하기" 가이드를 참조하세요.

설치

설정을 간편하게 하려면 vitest init browser 명령을 사용하여 필요한 종속성을 설치하고 브라우저 구성을 생성할 수 있습니다.

npm

npx vitest init browser

yarn

yarn exec vitest init browser

pnpm

pnpx vitest init browser

bun

bunx vitest init browser

수동 설치

패키지를 수동으로 설치할 수도 있습니다. 기본적으로 브라우저 모드는 기존 브라우저를 재사용하므로 로컬에서 테스트를 실행하기 위해 추가 E2E(End-to-End) 프로바이더가 필요 없습니다.

npm

npm install -D vitest @vitest/browser

yarn

yarn add -D vitest @vitest/browser

pnpm

pnpm add -D vitest @vitest/browser

bun

bun add -D vitest @vitest/browser

WARNING

하지만 CI(지속적 통합) 환경에서 테스트를 실행하려면 playwright 또는 webdriverio 중 하나를 설치해야 합니다. 또한 기본 preview 프로바이더는 Chrome DevTools Protocol을 사용하는 대신 이벤트를 시뮬레이션하는 방식에 의존하므로, 로컬 테스트 시에도 이들 중 하나로 전환하는 것을 권장합니다.

이 도구들 중 하나를 아직 사용하고 있지 않다면, Playwright를 사용하는 것을 권장합니다. Playwright는 병렬 실행을 지원하여 테스트를 더 빠르게 실행할 수 있습니다. 또한 Playwright는 WebDriver보다 일반적으로 빠른 Chrome DevTools Protocol을 사용합니다.

::: tabs key:provider == Playwright Playwright는 웹 테스트 및 자동화를 위한 프레임워크입니다.

npm

npm install -D vitest @vitest/browser playwright

yarn

yarn add -D vitest @vitest/browser playwright

pnpm

pnpm add -D vitest @vitest/browser playwright

bun

bun add -D vitest @vitest/browser playwright

== WebdriverIO

WebdriverIO를 사용하면 WebDriver 프로토콜을 사용하여 로컬에서 테스트를 실행할 수 있습니다.

npm

npm

npm install -D vitest @vitest/browser webdriverio

yarn

yarn add -D vitest @vitest/browser webdriverio

pnpm

pnpm add -D vitest @vitest/browser webdriverio

bun

bun add -D vitest @vitest/browser webdriverio

구성

Vitest 구성에서 브라우저 모드를 활성화하려면 Vitest 구성 파일에서 browser.enabled 필드를 true로 설정합니다. 다음은 브라우저 필드를 사용한 구성 예시입니다.

import { defineConfig } from 'vitest/config';
export default defineConfig({
  test: {
    browser: {
      provider: 'playwright', // 또는 'webdriverio'
      enabled: true,
      // 최소 하나의 인스턴스가 필요합니다.
      instances: [{ browser: 'chromium' }],
    },
  },
});

INFO

Vitest는 개발 서버와의 충돌을 피하기 위해 포트 63315를 할당하여 병렬 실행을 가능하게 합니다. 이 포트는 browser.api 옵션을 통해 변경할 수 있습니다.

Vitest 2.1.5부터 CLI는 더 이상 Vite URL을 자동으로 출력하지 않습니다. watch 모드에서 실행할 때 "b"를 눌러 URL을 출력할 수 있습니다.

Vite를 처음 사용하는 경우, 프레임워크의 플러그인이 설치되어 있고 구성에 지정되어 있는지 확인해야 합니다. 일부 프레임워크는 작동을 위해 추가 구성이 필요할 수 있으므로, 해당 Vite 관련 문서를 확인하여 확인하세요.

react

import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }],
    },
  },
});

vue

import { defineConfig } from 'vitest/config';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [vue()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }],
    },
  },
});

svelte

import { defineConfig } from 'vitest/config';
import { svelte } from '@sveltejs/vite-plugin-svelte';

export default defineConfig({
  plugins: [svelte()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }],
    },
  },
});

solid

import { defineConfig } from 'vitest/config';
import solidPlugin from 'vite-plugin-solid';

export default defineConfig({
  plugins: [solidPlugin()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }],
    },
  },
});

marko

import { defineConfig } from 'vitest/config';
import marko from '@marko/vite';

export default defineConfig({
  plugins: [marko()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }],
    },
  },
});

Node 기반 러너를 사용하여 일부 테스트를 실행해야 하는 경우, 다른 테스트 전략에 대한 별도의 구성으로 projects 옵션을 정의할 수 있습니다.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          // 파일 기반 규칙의 예시입니다.
          // 반드시 따를 필요는 없습니다.
          include: [
            'tests/unit/**/*.{test,spec}.ts',
            'tests/**/*.unit.{test,spec}.ts',
          ],
          name: 'unit',
          environment: 'node',
        },
      },
      {
        test: {
          // 파일 기반 규칙의 예시입니다.
          // 반드시 따를 필요는 없습니다.
          include: [
            'tests/browser/**/*.{test,spec}.ts',
            'tests/**/*.browser.{test,spec}.ts',
          ],
          name: 'browser',
          browser: {
            enabled: true,
            instances: [{ browser: 'chromium' }],
          },
        },
      },
    ],
  },
});

브라우저 옵션 타입

Vitest의 브라우저 옵션은 프로바이더에 따라 달라집니다. --browser를 전달하고 구성 파일에 이름을 지정하지 않으면 Vitest가 실패합니다. 사용 가능한 옵션:

• webdriverio는 다음 브라우저를 지원합니다:
  • firefox
  • chrome
  • edge
  • safari
• playwright는 다음 브라우저를 지원합니다:
  • firefox
  • webkit
  • chromium

TypeScript

기본적으로 TypeScript는 프로바이더 옵션과 추가 expect 속성을 인식하지 못합니다. 프로바이더를 사용하지 않는 경우, @vitest/browser/matchers가 테스트, 설정 파일 또는 구성 파일 어딘가에 참조되어 추가 expect 정의를 가져오도록 해야 합니다. 사용자 지정 프로바이더를 사용하는 경우, TypeScript가 사용자 지정 옵션에 대한 정의를 가져올 수 있도록 @vitest/browser/providers/playwright 또는 @vitest/browser/providers/webdriverio를 동일한 파일에 추가해야 합니다.

default

/// <reference types="@vitest/browser/matchers" />

playwright

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

webdriverio

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

또는 tsconfig.json 파일의 compilerOptions.types 필드에 추가할 수도 있습니다. 이 필드에 무언가를 지정하면 @types/* 패키지의 자동 로딩이 비활성화됩니다.

default

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

playwright

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

webdriverio

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

브라우저 호환성

Vitest는 Vite 개발 서버를 사용하여 테스트를 실행하므로, esbuild.target 옵션(기본적으로 esnext)에 지정된 기능만 지원합니다.

기본적으로 Vite는 네이티브 ES Modules, 네이티브 ESM 동적 임포트, 그리고 import.meta를 지원하는 브라우저를 대상으로 합니다. 또한, iframe 간 통신을 위해 BroadcastChannel을 활용합니다:

• Chrome >=87
• Firefox >=78
• Safari >=15.4
• Edge >=88

테스트 실행

브라우저 옵션에 브라우저 이름을 지정하면 Vitest는 기본적으로 preview를 사용하여 지정된 브라우저를 실행한 다음 해당 브라우저에서 테스트를 실행합니다. preview를 사용하고 싶지 않다면 browser.provider 옵션을 사용하여 사용자 지정 브라우저 프로바이더를 구성할 수 있습니다.

CLI를 사용하여 브라우저를 지정하려면 --browser 플래그 뒤에 브라우저 이름을 다음과 같이 사용합니다:

npx vitest --browser=chromium

또는 점 표기법으로 CLI에 브라우저 옵션을 제공할 수 있습니다:

npx vitest --browser.headless

WARNING

Vitest 3.2부터는 구성에 browser 옵션이 없지만 --browser 플래그를 지정하면 Vitest는 구성이 브라우저용인지 Node.js 테스트용인지 가정할 수 없으므로 실패합니다.

기본적으로 Vitest는 개발을 위해 브라우저 UI를 자동으로 엽니다. 테스트는 중앙의 iframe 내에서 실행됩니다. 뷰포트는 선호하는 크기를 선택하거나, 테스트 내에서 page.viewport를 호출하거나, 구성에서 기본값을 설정하여 구성할 수 있습니다.

헤드리스

헤드리스 모드는 브라우저 모드에서 사용할 수 있는 또 다른 옵션입니다. 헤드리스 모드에서는 브라우저가 사용자 인터페이스 없이 백그라운드에서 실행되므로 자동화된 테스트를 실행하는 데 유용합니다. Vitest의 헤드리스 옵션은 헤드리스 모드를 활성화하거나 비활성화하기 위해 부울 값으로 설정할 수 있습니다.

헤드리스 모드를 사용하면 Vitest는 UI를 자동으로 열지 않습니다. UI를 계속 사용하면서 테스트를 헤드리스로 실행하려면 @vitest/ui 패키지를 설치하고 Vitest를 실행할 때 --ui 플래그를 전달해야 합니다.

다음은 헤드리스 모드를 활성화하는 구성 예시입니다:

import { defineConfig } from 'vitest/config';
export default defineConfig({
  test: {
    browser: {
      provider: 'playwright',
      enabled: true,
      headless: true,
    },
  },
});

CLI에서 --browser.headless 플래그를 사용하여 헤드리스 모드를 설정할 수도 있습니다:

npx vitest --browser.headless

이 경우 Vitest는 Chrome 브라우저를 사용하여 헤드리스 모드로 실행됩니다.

WARNING

헤드리스 모드는 기본적으로 사용할 수 없습니다. 이 기능을 활성화하려면 playwright 또는 webdriverio 프로바이더 중 하나를 사용해야 합니다.

예시

기본적으로 브라우저 모드에서 작업하는 데 외부 패키지는 필요 없습니다:

import { expect, test } from 'vitest';
import { page } from '@vitest/browser/context';
import { render } from './my-render-function.js';

test('properly handles form inputs', async () => {
  render(); // DOM 요소 마운트

  // 초기 상태를 검증합니다.
  await expect
    .element(page.getByText('Hi, my name is Alice'))
    .toBeInTheDocument();

  // 연결된 레이블을 쿼리하여 입력 DOM 노드를 가져옵니다.
  const usernameInput = page.getByLabelText(/username/i);

  // 입력 필드에 이름을 입력합니다. 이는 입력이 올바르게 채워졌는지 이미 확인하므로,
  // 값을 수동으로 확인할 필요 없습니다.
  await usernameInput.fill('Bob');

  await expect
    .element(page.getByText('Hi, my name is Bob'))
    .toBeInTheDocument();
});

하지만 Vitest는 여러 인기 프레임워크를 위한 컴포넌트 렌더링 패키지를 기본적으로 제공합니다:

• vue 컴포넌트 렌더링을 위한 vitest-browser-vue
• svelte 컴포넌트 렌더링을 위한 vitest-browser-svelte
• react 컴포넌트 렌더링을 위한 vitest-browser-react

커뮤니티에서 제공하는 패키지도 있습니다:

• lit 컴포넌트 렌더링을 위한 vitest-browser-lit
• preact 컴포넌트 렌더링을 위한 vitest-browser-preact

사용하는 프레임워크가 없다면 직접 패키지를 만들 수 있습니다. 이는 프레임워크 렌더러와 page.elementLocator API를 감싸는 간단한 래퍼입니다. 해당 패키지의 링크를 이 페이지에 추가해 드리겠습니다. 패키지 이름이 vitest-browser-로 시작하도록 해주세요.

컴포넌트 렌더링 및 요소 탐색 외에도 검증을 해야 합니다. Vitest는 @testing-library/jest-dom 라이브러리를 포크하여 다양한 DOM 검증을 기본적으로 제공합니다. 자세한 내용은 검증 API에서 확인하십시오.

import { expect } from 'vitest';
import { page } from '@vitest/browser/context';
// 요소가 올바르게 렌더링되었습니다.
await expect.element(page.getByText('Hello World')).toBeInTheDocument();

Vitest는 테스트에 유용할 수 있는 작은 유틸리티 세트와 함께 Context API를 제공합니다. 예를 들어, 요소를 클릭하거나 입력 필드에 텍스트를 입력하는 것과 같은 인터랙션을 해야 하는 경우, @vitest/browser/context에서 userEvent를 사용할 수 있습니다. 자세한 내용은 인터랙션 API에서 확인하십시오.

import { page, userEvent } from '@vitest/browser/context';
await userEvent.fill(page.getByLabelText(/username/i), 'Alice');
// 또는 locator.fill
await page.getByLabelText(/username/i).fill('Alice');

vue

import { render } from 'vitest-browser-vue';
import Component from './Component.vue';

test('properly handles v-model', async () => {
  const screen = render(Component);

  // 초기 상태를 검증합니다.
  await expect
    .element(screen.getByText('Hi, my name is Alice'))
    .toBeInTheDocument();

  // 연결된 레이블을 쿼리하여 입력 DOM 노드를 가져옵니다.
  const usernameInput = screen.getByLabelText(/username/i);

  // 입력 필드에 이름을 입력합니다. 이는 입력이 올바르게 채워졌는지 이미 확인하므로,
  // 값을 수동으로 확인할 필요 없습니다.
  await usernameInput.fill('Bob');

  await expect
    .element(screen.getByText('Hi, my name is Bob'))
    .toBeInTheDocument();
});

svelte

import { render } from 'vitest-browser-svelte';
import { expect, test } from 'vitest';

import Greeter from './greeter.svelte';

test('greeting appears on click', async () => {
  const screen = render(Greeter, { name: 'World' });

  const button = screen.getByRole('button');
  await button.click();
  const greeting = screen.getByText(/hello world/iu);

  await expect.element(greeting).toBeInTheDocument();
});

react

import { render } from 'vitest-browser-react';
import Fetch from './fetch';

test('loads and displays greeting', async () => {
  // React 요소를 DOM에 렌더링합니다.
  const screen = render(<Fetch url="/greeting" />);

  await screen.getByText('Load Greeting').click();
  // 요소를 찾을 수 없는 경우 오류를 발생시키기 전에 기다립니다.
  const heading = screen.getByRole('heading');

  // 알림 메시지가 올바른지 검증합니다.
  await expect.element(heading).toHaveTextContent('hello there');
  await expect.element(screen.getByRole('button')).toBeDisabled();
});

lit

import { render } from 'vitest-browser-lit';
import { html } from 'lit';
import './greeter-button';

test('greeting appears on click', async () => {
  const screen = render(html`<greeter-button name="World"></greeter-button>`);

  const button = screen.getByRole('button');
  await button.click();
  const greeting = screen.getByText(/hello world/iu);

  await expect.element(greeting).toBeInTheDocument();
});

preact

import { render } from 'vitest-browser-preact';
import { createElement } from 'preact';
import Greeting from '.Greeting';

test('greeting appears on click', async () => {
  const screen = render(<Greeting />);

  const button = screen.getByRole('button');
  await button.click();
  const greeting = screen.getByText(/hello world/iu);

  await expect.element(greeting).toBeInTheDocument();
});

Vitest는 모든 프레임워크를 기본적으로 지원하지는 않지만, 외부 도구를 사용하여 이러한 프레임워크로 테스트를 실행할 수 있습니다. 또한 커뮤니티에서 자체 vitest-browser 래퍼를 만들도록 권장합니다. 만약 가지고 있다면 위의 예시에 추가해 주십시오.

지원되지 않는 프레임워크의 경우 testing-library 패키지를 사용하는 것을 권장합니다:

• solid 컴포넌트 렌더링을 위한 @solidjs/testing-library
• marko 컴포넌트 렌더링을 위한 @marko/testing-library

더 많은 예시는 browser-examples 저장소에서 확인할 수 있습니다.

WARNING

testing-library는 @testing-library/user-event 패키지를 제공합니다. 이 패키지는 이벤트를 실제로 트리거하는 대신 시뮬레이션하므로 직접 사용하는 것을 권장하지 않습니다. 대신, (프로바이더에 따라) Chrome DevTools Protocol 또는 Webdriver를 내부적으로 활용하는 @vitest/browser/context에서 임포트한 userEvent를 사용하세요.

solid

// @testing-library/solid API 기반
// https://testing-library.com/docs/solid-testing-library/api

import { render } from '@testing-library/solid';

it('uses params', async () => {
  const App = () => (
    <>
      <Route
        path="/ids/:id"
        component={() => (
          <p>
            Id:
            {useParams()?.id}
          </p>
        )}
      />
      <Route path="/" component={() => <p>Start</p>} />
    </>
  );
  const { baseElement } = render(() => <App />, { location: 'ids/1234' });
  const screen = page.elementLocator(baseElement);

  await expect.screen(screen.getByText('Id: 1234')).toBeInTheDocument();
});

marko

// @testing-library/marko API 기반
// https://testing-library.com/docs/marko-testing-library/api

import { render, screen } from '@marko/testing-library';
import Greeting from './greeting.marko';

test('renders a message', async () => {
  const { baseElement } = await render(Greeting, { name: 'Marko' });
  const screen = page.elementLocator(baseElement);
  await expect.element(screen.getByText(/Marko/)).toBeInTheDocument();
  expect(container.firstChild).toMatchInlineSnapshot(`
    <h1>Hello, Marko!</h1>
  `);
});

제한 사항

스레드 차단 다이얼로그

Vitest 브라우저를 사용할 때 alert 또는 confirm과 같은 스레드 차단 다이얼로그를 기본적으로 사용할 수 없다는 점에 유의해야 합니다. 이는 웹 페이지를 차단하여 Vitest가 페이지와 계속 통신할 수 없게 되고, 그 결과 실행이 중단되기 때문입니다.

이러한 상황에서 Vitest는 이러한 API에 대한 기본 반환 값을 가진 기본 목(mock)을 제공합니다. 이는 사용자가 실수로 동기 팝업 웹 API를 사용하더라도 실행이 중단되지 않도록 보장합니다. 그러나 더 나은 경험을 위해 사용자가 이러한 웹 API를 목킹하는 것이 여전히 권장됩니다. 자세한 내용은 목킹(Mocking)에서 확인하세요.