Böngésző üzemmód Kísérleti

Ez az oldal a Vitest kísérleti böngésző üzemmódjáról nyújt információt, amely lehetővé teszi a tesztek natív futtatását a böngészőben, hozzáférést biztosítva a böngésző globális objektumaihoz, mint például a window és a document. Ez a funkció jelenleg fejlesztés alatt áll, és az API-k a jövőben változhatnak.

TIP

Ha az expect, vi vagy bármely általános API, például tesztprojektek vagy típusellenőrzés dokumentációját keresi, nézze meg a "Bevezetés" útmutatót.

Telepítés

Az egyszerűbb beállításhoz használhatja a vitest init browser parancsot a szükséges függőségek telepítéséhez és a böngésző konfigurációjának létrehozásához.

npm

npx vitest init browser

yarn

yarn exec vitest init browser

pnpm

pnpx vitest init browser

bun

bunx vitest init browser

Manuális telepítés

A csomagokat manuálisan is telepítheti. Alapértelmezés szerint a böngésző üzemmód nem igényel további E2E szolgáltatót a tesztek helyi futtatásához, mivel a meglévő böngészőjét használja fel.

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

Azonban a tesztek CI-ben való futtatásához telepítenie kell a playwright vagy a webdriverio egyikét. Azt is javasoljuk, hogy váltson át ezek egyikére a helyi teszteléshez az alapértelmezett preview szolgáltató helyett, mivel az események szimulációjára épül a Chrome DevTools Protocol használata helyett.

Ha még nem használja ezen eszközök egyikét sem, javasoljuk, hogy kezdje a Playwright-tal, mert támogatja a párhuzamos végrehajtást, ami felgyorsítja a teszteket. Ezenkívül a Playwright a Chrome DevTools Protocol protokollt használja, ami általában gyorsabb, mint a WebDriver.

::: tabs key:provider == Playwright A Playwright egy keretrendszer webes teszteléshez és automatizáláshoz.

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

A WebdriverIO lehetővé teszi a tesztek helyi futtatását a WebDriver protokoll használatával.

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

Konfiguráció

A böngésző üzemmód aktiválásához a Vitest konfigurációjában állítsa a browser.enabled mezőt true értékre a Vitest konfigurációs fájljában. Íme egy példa konfiguráció a browser mező használatával:

import { defineConfig } from 'vitest/config';
export default defineConfig({
  test: {
    browser: {
      provider: 'playwright', // vagy 'webdriverio'
      enabled: true,
      // legalább egy példány szükséges
      instances: [{ browser: 'chromium' }],
    },
  },
});

INFO

A Vitest a 63315 portot rendeli hozzá, hogy elkerülje a fejlesztői szerverrel való ütközéseket, lehetővé téve azok párhuzamos futtatását. Ezt a browser.api opcióval módosíthatja.

A Vitest 2.1.5 óta a CLI már nem nyomtatja ki automatikusan a Vite URL-t. A "b" megnyomásával megjelenítheti az URL-t, ha figyelő módban fut.

Ha még nem használta a Vite-et, győződjön meg róla, hogy a keretrendszeréhez tartozó bővítmény telepítve van és be van állítva a konfigurációban. Néhány keretrendszer további konfigurációt igényelhet a működéshez – erről a Vite-hez kapcsolódó dokumentációjukban tájékozódhat.

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' }],
    },
  },
});

Ha Node-alapú futtatóval kell futtatnia néhány tesztet, akkor definiálhat egy projects opciót külön konfigurációkkal a különböző tesztelési stratégiákhoz:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          // egy fájl alapú konvenció példája,
          // nem kell követnie
          include: [
            'tests/unit/**/*.{test,spec}.ts',
            'tests/**/*.unit.{test,spec}.ts',
          ],
          name: 'unit',
          environment: 'node',
        },
      },
      {
        test: {
          // egy fájl alapú konvenció példája,
          // nem kell követnie
          include: [
            'tests/browser/**/*.{test,spec}.ts',
            'tests/**/*.browser.{test,spec}.ts',
          ],
          name: 'browser',
          browser: {
            enabled: true,
            instances: [{ browser: 'chromium' }],
          },
        },
      },
    ],
  },
});

Böngésző opciótípusok

A Vitest browser opciója a szolgáltatótól függ. A Vitest hibát fog jelezni, ha --browser opciót ad át, és nem adja meg a böngésző nevét a konfigurációs fájlban. Elérhető opciók:

• A webdriverio a következő böngészőket támogatja:
  • firefox
  • chrome
  • edge
  • safari
• A playwright a következő böngészőket támogatja:
  • firefox
  • webkit
  • chromium

TypeScript

Alapértelmezés szerint a TypeScript nem ismeri fel a szolgáltatókhoz tartozó opciókat és az extra expect tulajdonságokat. Ha nem használ semmilyen szolgáltatót, győződjön meg róla, hogy az @vitest/browser/matchers hivatkozva van valahol a tesztjeiben, a beállítási fájlban vagy egy konfigurációs fájlban, hogy az extra expect definíciók elérhetővé váljanak. Ha egyéni szolgáltatókat használ, győződjön meg róla, hogy hozzáadja az @vitest/browser/providers/playwright vagy @vitest/browser/providers/webdriverio fájlt ugyanahhoz a fájlhoz, hogy a TypeScript felvehesse az egyéni opciók definícióit:

default

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

playwright

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

webdriverio

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

Alternatív megoldásként hozzáadhatja ezeket a tsconfig.json fájl compilerOptions.types mezőjéhez is. Ne feledje, hogy bármilyen érték megadása ebben a mezőben letiltja az @types/* csomagok automatikus betöltését.

default

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

playwright

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

webdriverio

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

Böngésző kompatibilitás

A Vitest a Vite fejlesztői szerverét használja a tesztek futtatásához, így csak az esbuild.target opcióban megadott célplatform funkcióit támogatjuk (esnext alapértelmezés szerint).

Alapértelmezés szerint a Vite olyan böngészőket céloz meg, amelyek támogatják a natív ES modulokat, a natív ESM dinamikus importálást és az import.meta funkciót. Ezen felül a BroadcastChannel API-t használjuk az iframe-ek közötti kommunikációhoz:

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

Tesztek futtatása

Amikor megad egy böngészőnevet a browser opcióban, a Vitest alapértelmezés szerint megpróbálja futtatni a megadott böngészőt a preview használatával, majd ott futtatja a teszteket. Ha nem szeretné használni a preview funkciót, konfigurálhatja az egyéni böngésző szolgáltatót a browser.provider opcióval.

A böngésző megadásához a CLI-n keresztül használja a --browser jelzőt, majd a böngésző nevét, például így:

npx vitest --browser=chromium

Vagy megadhatja a browser opciókat a CLI-nek pontjelöléssel:

npx vitest --browser.headless

WARNING

A Vitest 3.2 óta, ha nincs browser opció a konfigurációban, de megadja a --browser jelzőt, a Vitest hibát fog jelezni, mert nem tudja feltételezni, hogy a konfiguráció böngészőhöz, és nem Node.js tesztekhez készült.

Alapértelmezés szerint a Vitest automatikusan megnyitja a böngésző felhasználói felületét a fejlesztéshez. A tesztek egy iframe-ben futnak a felület közepén. A nézetablakot konfigurálhatja a kívánt méretek kiválasztásával, a page.viewport használatával a teszten belül, vagy alapértelmezett értékek beállításával a konfigurációban.

Headless mód

A headless mód egy másik opció, amely a böngésző módban elérhető. Headless módban a böngésző felhasználói felület nélkül fut a háttérben, ami ideálissá teszi az automatizált tesztek futtatásához. A Vitest headless opciója beállítható egy logikai értékre a headless mód engedélyezéséhez vagy letiltásához.

Headless mód használatakor a Vitest nem nyitja meg automatikusan a felhasználói felületet. Ha továbbra is használni szeretné a felhasználói felületet, de a teszteket headless módban futtatná, telepítheti az @vitest/ui csomagot, és átadhatja a --ui jelzőt a Vitest futtatásakor.

Íme egy példa konfiguráció a headless mód engedélyezésére:

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

A headless módot a CLI-ben a --browser.headless jelzővel is beállíthatja, például így:

npx vitest --browser.headless

Ebben az esetben a Vitest headless módban fut a Chrome böngészővel.

WARNING

A headless mód alapértelmezés szerint nem elérhető. Ehhez a funkcióhoz a playwright vagy a webdriverio szolgáltatók egyikét kell használnia.

Példák

Alapértelmezés szerint nincs szüksége külső csomagokra a böngésző üzemmód használatához:

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 elemek renderelése

  // Kezdeti állapot asszertálása.
  await expect
    .element(page.getByText('Hi, my name is Alice'))
    .toBeInTheDocument();

  // Az input DOM csomópont lekérése a hozzá tartozó címke alapján.
  const usernameInput = page.getByLabelText(/username/i);

  // A név beírása az inputba. Ez már ellenőrzi, hogy az input
  // helyesen van-e kitöltve, az érték manuális ellenőrzése nem szükséges.
  await usernameInput.fill('Bob');

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

A Vitest azonban csomagokat is biztosít a komponensek rendereléséhez számos népszerű keretrendszerhez, beépítetten:

• vitest-browser-vue a vue komponensek rendereléséhez
• vitest-browser-svelte a svelte komponensek rendereléséhez
• vitest-browser-react a react komponensek rendereléséhez

Közösségi csomagok is elérhetők más keretrendszerekhez:

• vitest-browser-lit a lit komponensek rendereléséhez
• vitest-browser-preact a preact komponensek rendereléséhez

Ha az Ön keretrendszere nincs képviselve, nyugodtan hozza létre saját csomagját – ez egy egyszerű burkoló a keretrendszer renderelője és a page.elementLocator API köré épül. Hozzáadunk egy linket ehhez az oldalhoz. Győződjön meg róla, hogy a neve vitest-browser- előtaggal kezdődik.

A komponensek renderelése és az elemek lokalizálása mellett állításokat is kell tennie. A Vitest a @testing-library/jest-dom könyvtárat forkolja, hogy széles körű DOM állításokat biztosítson beépítetten. További információkért olvassa el az Állítások API-t.

import { expect } from 'vitest';
import { page } from '@vitest/browser/context';
// az elem helyesen renderelődött
await expect.element(page.getByText('Hello World')).toBeInTheDocument();

A Vitest egy Context API-t tesz elérhetővé, amely néhány hasznos segédprogramot tartalmaz a tesztekhez. Például, ha interakciót kell végrehajtania, például egy elemre kattintania vagy szöveget beírnia egy beviteli mezőbe, használhatja a userEvent segédprogramot az @vitest/browser/context csomagból. További információkért olvassa el az Interaktivitás API-t.

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

  // Kezdeti állapot asszertálása.
  await expect
    .element(screen.getByText('Hi, my name is Alice'))
    .toBeInTheDocument();

  // Az input DOM csomópont lekérése a hozzá tartozó címke alapján.
  const usernameInput = screen.getByLabelText(/username/i);

  // A név beírása az inputba. Ez már ellenőrzi, hogy az input
  // helyesen van-e kitöltve, az érték manuális ellenőrzése nem szükséges.
  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 elem renderelése a DOM-ban
  const screen = render(<Fetch url="/greeting" />);

  await screen.getByText('Load Greeting').click();
  // várjon, mielőtt hibát jelezne, ha nem talál elemet
  const heading = screen.getByRole('heading');

  // ellenőrizze, hogy az üdvözlő üzenet helyes-e
  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();
});

A Vitest nem támogatja az összes keretrendszert beépítetten, de külső eszközöket használhat a tesztek futtatásához ezekkel a keretrendszerekkel. Arra is ösztönözzük a közösséget, hogy hozzanak létre saját vitest-browser burkolókat – ha rendelkezik ilyennel, nyugodtan adja hozzá a fenti példákhoz.

A nem támogatott keretrendszerekhez a testing-library csomagokat javasoljuk:

• @solidjs/testing-library a solid komponensek rendereléséhez
• @marko/testing-library a marko komponensek rendereléséhez

További példákat a browser-examples tárolóban talál.

WARNING

A testing-library biztosít egy @testing-library/user-event csomagot. Nem javasoljuk a közvetlen használatát, mert az eseményeket szimulálja ahelyett, hogy ténylegesen kiváltaná őket – ehelyett használja a @vitest/browser/context csomagból importált userEvent segédprogramot, amely a Chrome DevTools Protocolt vagy a Webdrivert (a szolgáltatótól függően) használja a háttérben.

solid

// a @testing-library/solid API alapján
// 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

// a @testing-library/marko API alapján
// 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>
  `);
});

Korlátozások

Szálat blokkoló párbeszédpanelek

A Vitest böngésző üzemmódjának használatakor fontos megjegyezni, hogy a szálat blokkoló párbeszédpanelek, mint az alert vagy a confirm nem használhatók natívan. Ennek oka, hogy blokkolják a weboldalt, ami azt jelenti, hogy a Vitest nem tudja folytatni a kommunikációt az oldallal, ami a végrehajtás leállását okozza.

Ilyen helyzetekben a Vitest alapértelmezett mockokat biztosít, amelyek alapértelmezett visszatérési értékeket adnak ezekhez az API-khoz. Ez biztosítja, hogy ha a felhasználó véletlenül szinkron felugró webes API-kat használ, a végrehajtás ne álljon le. Azonban a jobb felhasználói élmény érdekében továbbra is javasolt ezeknek a webes API-knak a mockolása. További információkért olvassa el a Mocking részt.