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

Tato stránka popisuje experimentální funkci režimu prohlížeče v API Vitest, 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 v současné době ve vývoji a její API se mohou v budoucnu měnit.

Instalace

Pro usnadnění nastavení můžete použít příkaz vitest init browser k instalaci potřebných závislostí a vytvoření konfigurace prohlížeč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 také nainstalovat 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áš stávají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 prostředí však musíte nainstalovat buď playwright nebo webdriverio. Doporučujeme také přepnout na jednoho z nich pro lokální testování namísto použití výchozího poskytovatele preview, protože ten se spoléhá na simulaci událostí místo použití protokolu Chrome DevTools.

Pokud již jeden z těchto nástrojů nepoužíváte, doporučujeme začít s Playwright, protože podporuje paralelní spouštění, což vaše testy zrychlí. Navíc protokol Chrome DevTools, který Playwright používá, 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 můžete použít příznak --browser nebo nastavit pole browser.enabled na true ve vašem konfiguračním souboru Vitest. Zde je příklad konfigurace s použitím pole prohlížeče:

export default defineConfig({
  test: {
    browser: {
      provider: 'playwright', // nebo 'webdriverio'
      enabled: true,
      name: 'chromium', // název prohlížeče je vyžadován
    },
  },
});

INFO

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

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

Pokud jste Vite ještě nepoužívali, ujistěte se, že máte nainstalován plugin vašeho frameworku a je specifikován v konfiguraci. Některé frameworky mohou vyžadovat dodatečnou konfiguraci pro správnou funkci – zkontrolujte jejich dokumentaci související s Vite, abyste se ujistili.

vue

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

export default defineConfig({
  plugins: [vue()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      name: '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',
      name: 'chromium',
    },
  },
});

solid

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

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

marko

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

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

TIP

react nevyžaduje plugin pro funkčnost, ale preact vyžaduje dodatečnou konfiguraci, aby fungovaly aliasy.

Pokud potřebujete spouštět některé testy pomocí Node runneru, můžete definovat soubor pracovního prostoru s oddělenými konfiguracemi pro různé testovací strategie:

// vitest.workspace.ts
import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  {
    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,
        name: 'chrome',
      },
    },
  },
]);

Konfigurace poskytovatele

:::tabs key:provider == Playwright Můžete konfigurovat, jak Vitest spouští prohlížeč a vytváří kontext stránky pomocí pole providerOptions:

export default defineConfig({
  test: {
    browser: {
      providerOptions: {
        launch: {
          devtools: true,
        },
        context: {
          geolocation: {
            latitude: 45,
            longitude: -30,
          },
          reducedMotion: 'reduce',
        },
      },
    },
  },
});

Pro získání typových nápověd přidejte @vitest/browser/providers/playwright do compilerOptions.types ve vašem souboru tsconfig.json. == WebdriverIO Můžete konfigurovat, jaké možnosti by měl Vitest použít při spouštění prohlížeče pomocí pole providerOptions:

export default defineConfig({
  test: {
    browser: {
      browser: 'chrome',
      providerOptions: {
        region: 'eu',
        capabilities: {
          browserVersion: '27.0',
          platformName: 'Windows 10',
        },
      },
    },
  },
});

Pro získání typových nápověd přidejte @vitest/browser/providers/webdriverio do compilerOptions.types ve vašem souboru tsconfig.json. :::

Typy možností prohlížeče

Možnost prohlížeče ve Vitest závisí na poskytovateli. Vitest selže, pokud předáte --browser a zároveň 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

Kompatibilita prohlížeče

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

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 poté 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=chrome

Nebo můžete poskytnout možnosti prohlížeče do CLI s tečkovou notací:

npx vitest --browser.name=chrome --browser.headless

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. Zobrazení můžete konfigurovat výběrem preferovaných rozměrů, voláním page.viewport uvnitř testu nebo nastavením výchozích hodnot v konfiguraci.

Bezhlavý režim

Bezhlavý režim je další možnost 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 povolení či zakázání 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 testy spouštět bezhlavě, můžete nainstalovat balíček @vitest/ui a při spouštění Vitest předat příznak --ui.

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

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.name=chrome --browser.headless

V tomto případě Vitest poběží 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

Vitest poskytuje balíčky pro vykreslování komponent pro několik populárních frameworků přímo z krabice:

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

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

Kromě vykreslování komponent a lokalizace prvků budete také potřebovat provádět aserce. Vitest zahrnuje knihovnu @testing-library/jest-dom, která poskytuje širokou škálu DOM asercí přímo z krabice. Více informací najdete v Assertions API.

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

Vitest nabízí Context API s malou sadou utilit, které se vám mohou hodit v testech. Například, pokud potřebujete provést interakci, jako je kliknutí na prvek nebo zadání textu do vstupu, můžete použít userEvent z @vitest/browser/context. Více informací najdete 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);

  // Ověří výchozí stav.
  await expect
    .element(screen.getByText('Hi, my name is Alice'))
    .toBeInTheDocument();

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

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

  await screen.getByText('Load Greeting').click();
  // počká před vyvoláním chyby, pokud prvek nemůže najít
  const heading = screen.getByRole('heading');

  // ověří, že zpráva upozornění je správná
  await expect.element(heading).toHaveTextContent('hello there');
  await expect.element(screen.getByRole('button')).toBeDisabled();
});

Vitest nepodporuje všechny frameworky přímo z krabice, 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 nějaký 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:

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

WARNING

testing-library poskytuje balíček @testing-library/user-event. Nedoporučujeme jej používat přímo, protože simuluje události namí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).

preact

// založeno na příkladu `@testing-library/preact`
// https://testing-library.com/docs/preact-testing-library/example

import { h } from 'preact';
import { page } from '@vitest/browser/context';
import { render } from '@testing-library/preact';

import HiddenMessage from '../hidden-message';

test('shows the children when the checkbox is checked', async () => {
  const testMessage = 'Test Message';

  const { baseElement } = render(<HiddenMessage>{testMessage}</HiddenMessage>);

  const screen = page.elementLocator(baseElement);

  // .query() vrátí prvek nebo null, pokud jej nelze najít.
  // .element() vrátí prvek nebo vyvolá chybu, pokud jej nelze najít.
  expect(screen.getByText(testMessage).query()).not.toBeInTheDocument();

  // Dotazy mohou přijímat regulární výraz, aby byly vaše selektory
  // odolnější vůči úpravám a změnám obsahu.
  await screen.getByLabelText(/show/i).click();

  await expect.element(screen.getByText(testMessage)).toBeInTheDocument();
});

solid

// založeno na API `@testing-library/solid`
// 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 API `@testing-library/marko`
// 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();
  await expect.element(container.firstChild).toMatchInlineSnapshot(`
    <h1>Hello, Marko!</h1>
  `);
});

Omezení

Dialogy blokující vlákno

Při používání Vitest Browser je důležité si uvědomit, že dialogy blokující vlákno, jako jsou alert nebo confirm, nelze používat přímo. Je to proto, že blokují webovou stránku, což znamená, že Vitest nemůže pokračovat v komunikaci se stránkou, což způsobí zavěšení provádění.

V takových situacích Vitest poskytuje výchozí mocky s výchozími vrácenými hodnotami pro tato API. Tím je zajištěno, že pokud uživatel náhodně použije synchronní vyskakovací webová API, provádění se nezavěsí. Nicméně, stále se doporučuje, aby uživatel tato webová API mockoval pro lepší uživatelský zážitek. Více informací najdete v Mocking.