Režim prohlížeče Experimentální

Tato stránka popisuje experimentální funkci režimu prohlížeče v rozhraní Vitest API, která umožňuje spouštět testy přímo v prohlížeči a poskytuje přístup k globálním objektům prohlížeče, jako jsou window a document. Tato funkce je aktuálně ve vývoji a její API se mohou v budoucnu změnit.

TIP

Pokud hledáte dokumentaci k expect, vi nebo obecným API, například pro testovací projekty či testování typů, podívejte se na průvodce “Začínáme” “Getting Started” guide.

Instalace

Pro snadnější nastavení použijte příkaz vitest init browser, který nainstaluje požadované závislosti a vytvoří konfiguraci pro prohlížeč.

npm

npx vitest init browser

yarn

yarn exec vitest init browser

pnpm

pnpx vitest init browser

bun

bunx vitest init browser

Ruční instalace

Balíčky můžete nainstalovat také ručně. Ve výchozím nastavení režim prohlížeče nevyžaduje žádného dalšího poskytovatele E2E pro lokální spouštění testů, protože využívá váš existující prohlížeč.

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

Pro spouštění testů v CI však musíte nainstalovat buď playwright nebo webdriverio. Doporučujeme také přepnout na jeden z těchto nástrojů pro lokální testování namísto výchozího poskytovatele preview, který simuluje události místo protokolu Chrome DevTools.

Pokud tyto nástroje ještě nepoužíváte, doporučujeme začít s Playwright, který podporuje paralelní provádění a zrychluje tak vaše testy. Navíc Playwright používá Chrome DevTools Protocol, který je obecně rychlejší než WebDriver.

::: tabs key:provider == Playwright Playwright je framework pro webové testování a automatizaci.

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 umožňuje spouštět testy lokálně pomocí protokolu 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

Konfigurace

Pro aktivaci režimu prohlížeče ve vaší konfiguraci Vitest nastavte pole browser.enabled na true ve svém konfiguračním souboru Vitest. Zde je příklad konfigurace používající pole browser:

import { defineConfig } from 'vitest/config';
export default defineConfig({
  test: {
    browser: {
      provider: 'playwright', // nebo 'webdriverio'
      enabled: true,
      // vyžaduje se alespoň jedna instance
      instances: [{ browser: 'chromium' }],
    },
  },
});

INFO

Vitest přiřazuje port 63315, aby se předešlo konfliktům s vývojovým serverem a umožnilo vám spouštět je oba paralelně. To můžete změnit pomocí možnosti browser.api.

Od verze Vitest 2.1.5 již CLI automaticky netiskne URL Vite. URL můžete zobrazit stisknutím „b“ při spuštění v režimu sledování.

Pokud jste Vite dříve nepoužívali, ujistěte se, že máte nainstalovaný plugin vašeho frameworku a že jste jej specifikovali v konfiguraci. Některé frameworky mohou vyžadovat další konfiguraci pro správnou funkci – pro jistotu zkontrolujte jejich dokumentaci související s 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' }],
    },
  },
});

Pokud potřebujete spustit některé testy pomocí runneru založeného na Node, můžete vytvořit možnost projects s oddělenými konfiguracemi pro různé testovací strategie:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          // příklad konvence založené na souborech,
          // nemusíte ji dodržovat
          include: [
            'tests/unit/**/*.{test,spec}.ts',
            'tests/**/*.unit.{test,spec}.ts',
          ],
          name: 'unit',
          environment: 'node',
        },
      },
      {
        test: {
          // příklad konvence založené na souborech,
          // nemusíte ji dodržovat
          include: [
            'tests/browser/**/*.{test,spec}.ts',
            'tests/**/*.browser.{test,spec}.ts',
          ],
          name: 'browser',
          browser: {
            enabled: true,
            instances: [{ browser: 'chromium' }],
          },
        },
      },
    ],
  },
});

Typy možností prohlížeče

Možnost prohlížeče ve Vitest závisí na poskytovateli. Vitest selže, pokud použijete --browser a nespecifikujete jeho název v konfiguračním souboru. Dostupné možnosti:

• webdriverio podporuje tyto prohlížeče:
  • firefox
  • chrome
  • edge
  • safari
• playwright podporuje tyto prohlížeče:
  • firefox
  • webkit
  • chromium

TypeScript

Ve výchozím nastavení TypeScript nerozpoznává možnosti pro poskytovatele a další vlastnosti expect. Pokud nepoužíváte žádné poskytovatele, ujistěte se, že odkazujete na @vitest/browser/matchers někde ve vašich testech, souboru nastavení nebo konfiguračním souboru, aby se načetly další definice expect. Pokud používáte vlastní poskytovatele, ujistěte se, že do stejného souboru přidáte @vitest/browser/providers/playwright nebo @vitest/browser/providers/webdriverio, aby TypeScript rozpoznal definice pro vlastní možnosti:

default

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

playwright

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

webdriverio

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

Alternativně je můžete také přidat do pole compilerOptions.types ve vašem souboru tsconfig.json. Všimněte si, že jakékoli zadání v tomto poli zakáže automatické načítání balíčků @types/*.

default

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

playwright

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

webdriverio

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

Kompatibilita prohlížeče

Vitest používá Vite dev server ke spouštění vašich testů, takže podporujeme pouze funkce specifikované v možnosti esbuild.target (esnext ve výchozím nastavení).

Ve výchozím nastavení Vite cílí na prohlížeče, které podporují nativní ES moduly, nativní dynamický import ESM a import.meta. Navíc využíváme BroadcastChannel pro komunikaci mezi iframy:

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

Spouštění testů

Když v možnosti prohlížeče zadáte název prohlížeče, Vitest se pokusí spustit zadaný prohlížeč ve výchozím nastavení pomocí preview a následně na něm spustí testy. Pokud nechcete používat preview, můžete nakonfigurovat vlastního poskytovatele prohlížeče pomocí možnosti browser.provider.

Chcete-li zadat prohlížeč pomocí CLI, použijte příznak --browser následovaný názvem prohlížeče, například takto:

npx vitest --browser=chromium

Nebo můžete zadávat možnosti prohlížeče do CLI pomocí tečkové notace:

npx vitest --browser.headless

WARNING

Od Vitest 3.2, pokud nemáte možnost browser ve vaší konfiguraci, ale zadáte příznak --browser, Vitest selže, protože nemůže předpokládat, že konfigurace je určena pro prohlížeč, a nikoli pro testy Node.js.

Ve výchozím nastavení Vitest automaticky otevře uživatelské rozhraní prohlížeče pro vývoj. Vaše testy se budou spouštět uvnitř iframe uprostřed obrazovky. Zobrazení můžete nakonfigurovat výběrem preferovaných rozměrů, voláním metody page.viewport uvnitř testu nebo nastavením výchozích hodnot v konfiguraci.

Bezhlavý režim

Bezhlavý režim je další možnost dostupná v režimu prohlížeče. V bezhlavém režimu běží prohlížeč na pozadí bez uživatelského rozhraní, což je užitečné pro spouštění automatizovaných testů. Možnost headless ve Vitest lze nastavit na boolean hodnotu pro zapnutí nebo vypnutí bezhlavého režimu.

Při použití bezhlavého režimu Vitest automaticky neotevře uživatelské rozhraní. Pokud chcete nadále používat uživatelské rozhraní, ale spouštět testy v bezhlavém režimu, můžete nainstalovat balíček @vitest/ui a při spuštění Vitest předat příznak --ui.

Zde je příklad konfigurace povolující bezhlavý režim:

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

Bezhlavý režim můžete také nastavit pomocí příznaku --browser.headless v CLI, například takto:

npx vitest --browser.headless

V tomto případě se Vitest spustí v bezhlavém režimu pomocí prohlížeče Chrome.

WARNING

Bezhlavý režim není ve výchozím nastavení k dispozici. Pro povolení této funkce musíte použít buď poskytovatele playwright nebo webdriverio.

Příklady

Ve výchozím nastavení nepotřebujete žádné externí balíčky k práci s režimem prohlížeče:

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(); // vykreslí DOM elementy

  // Zkontroluje počáteční stav.
  await expect
    .element(page.getByText('Hi, my name is Alice'))
    .toBeInTheDocument();

  // Získá DOM uzel vstupu pomocí dotazu na přidružený štítek.
  const usernameInput = page.getByLabelText(/username/i);

  // Zadá jméno do vstupu. Tím se již ověří, že vstup
  // je správně vyplněn, není třeba ručně kontrolovat hodnotu.
  await usernameInput.fill('Bob');

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

Vitest však také poskytuje balíčky pro vykreslování komponent pro několik populárních frameworků přímo:

• vitest-browser-vue pro vykreslování komponent vue
• vitest-browser-svelte pro vykreslování komponent svelte
• vitest-browser-react pro vykreslování komponent react

Komunitní balíčky jsou k dispozici pro další frameworky:

• vitest-browser-lit pro vykreslování komponent lit
• vitest-browser-preact pro vykreslování komponent preact

Pokud váš framework není zastoupen, neváhejte si vytvořit vlastní balíček – je to jednoduchý obal kolem rendereru frameworku a API page.elementLocator. Odkaz na něj přidáme na tuto stránku. Ujistěte se, že jeho název začíná vitest-browser-.

Kromě vykreslování komponent a vyhledávání prvků budete také muset provádět aserce. Vitest vytváří fork knihovny @testing-library/jest-dom, aby poskytl širokou škálu DOM asercí přímo. Více se dočtete v Assertions API.

import { expect } from 'vitest';
import { page } from '@vitest/browser/context';
// element je správně vykreslen
await expect.element(page.getByText('Hello World')).toBeInTheDocument();

Vitest zpřístupňuje Context API s malou sadou utilit, které mohou být užitečné v testech. Například, pokud potřebujete provést interakci, například kliknutí na prvek nebo zadání textu do vstupu, můžete použít userEvent z @vitest/browser/context. Více se dočtete v Interactivity API.

import { page, userEvent } from '@vitest/browser/context';
await userEvent.fill(page.getByLabelText(/username/i), 'Alice');
// nebo jen 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);

  // Zkontroluje počáteční stav.
  await expect
    .element(screen.getByText('Hi, my name is Alice'))
    .toBeInTheDocument();

  // Získá DOM uzel vstupu pomocí dotazu na přidružený štítek.
  const usernameInput = screen.getByLabelText(/username/i);

  // Zadá jméno do vstupu. Tím se již ověří, že vstup
  // je správně vyplněn, není třeba ručně kontrolovat hodnotu.
  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 () => {
  // Vykreslí React element do DOM
  const screen = render(<Fetch url="/greeting" />);

  await screen.getByText('Load Greeting').click();
  // počká, než vyvolá chybu, pokud nemůže najít prvek
  const heading = screen.getByRole('heading');

  // ověří, že upozornění je správné
  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 nepodporuje všechny frameworky přímo, ale můžete použít externí nástroje pro spouštění testů s těmito frameworky. Také povzbuzujeme komunitu k vytváření vlastních vitest-browser obalů – pokud takový máte, neváhejte jej přidat do výše uvedených příkladů.

Pro nepodporované frameworky doporučujeme používat balíčky testing-library:

• @solidjs/testing-library pro vykreslování komponent solid
• @marko/testing-library pro vykreslování komponent marko

Další příklady naleznete v repozitáři browser-examples.

WARNING

testing-library poskytuje balíček @testing-library/user-event. Nedoporučujeme jej používat přímo, protože simuluje události místo jejich skutečného spouštění – místo toho použijte userEvent importovaný z @vitest/browser/context, který interně používá Chrome DevTools Protocol nebo Webdriver (v závislosti na poskytovateli).

solid

// založeno na @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

// založeno na @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>
  `);
});

Omezení

Dialogy blokující vlákna

Při použití Vitest Browser je důležité si uvědomit, že dialogy, které blokují vlákna, jako alert nebo confirm, nelze používat nativně. Je to proto, že blokují webovou stránku, což znamená, že Vitest nemůže pokračovat v komunikaci se stránkou, a provádění se tak zablokuje.

V takových situacích Vitest poskytuje výchozí mocky s přednastavenými návratovými hodnotami pro tato API. Tím je zajištěno, že pokud uživatel náhodně použije synchronní vyskakovací okna webových API, provádění se nezablokuje. Přesto se však uživateli doporučuje tyto webové API mockovat pro optimální funkčnost. Více se dočtete v Mocking.