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

Ez az oldal a Vitest kísérleti böngésző mód funkciójá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.

Telepítés

A könnyebb beállításhoz használhatja a vitest init browser parancsot a szükséges függőségek telepítésére és a böngésző konfigurációjának létrehozására.

npm

npx vitest init browser

yarn

yarn exec vitest init browser

pnpm

pnpx vitest init browser

bun

bunx vitest init browser

Kézi telepítés

A csomagokat manuálisan is telepítheti. Alapértelmezés szerint a böngésző mód nem igényel további E2E (End-to-End) szolgáltatót a tesztek helyi futtatásához, mivel felhasználja a meglévő böngészőjét.

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 (Continuous Integration) környezetben való futtatásához telepítenie kell a playwright vagy a webdriverio csomagot. Azt is javasoljuk, hogy válasszon ezen eszközök egyikére a helyi teszteléshez az alapértelmezett preview szolgáltató helyett, mivel az események szimulálására alapszik a Chrome DevTools Protocol használata helyett.

Ha még nem használja ezeket az eszközöket, javasoljuk, hogy kezdje a Playwright-tal, mert támogatja a párhuzamos végrehajtást, ami gyorsabbá teszi a teszteket. Ezenkívül a Playwright által használt Chrome DevTools Protocol általában gyorsabb, mint a WebDriver.

::: tabs key:provider == Playwright A Playwright egy keretrendszer a 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ő mód aktiválásához a Vitest konfigurációjában használhatja a --browser jelzőt, vagy beállíthatja 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:

export default defineConfig({
  test: {
    browser: {
      provider: 'playwright', // vagy 'webdriverio'
      enabled: true,
      name: 'chromium', // böngésző neve kötelező
    },
  },
});

INFO

A Vitest a 63315 portot rendeli hozzá, hogy elkerülje a fejlesztői szerverrel való ütközéseket, lehetővé téve mindkettő 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 írja ki automatikusan a Vite URL-t. A "b" megnyomásával kiírhatja az URL-t, ha figyelő módban fut.

Ha még nem használta a Vite-ot, győződjön meg róla, hogy a keretrendszeréhez tartozó bővítmény telepítve van és meg van adva a konfigurációban. Néhány keretrendszer extra konfigurációt igényelhet a működéshez – ellenőrizze a Vite-hoz kapcsolódó dokumentációjukat a biztonság kedvéért.

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

A react nem igényel bővítményt a működéshez, de a preact extra konfigurációt igényel az aliasok működéséhez.

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

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

export default defineWorkspace([
  {
    test: {
      // egy példa fájlalapú konvencióra,
      // nem kell követnie
      include: [
        'tests/unit/**/*.{test,spec}.ts',
        'tests/**/*.unit.{test,spec}.ts',
      ],
      name: 'unit',
      environment: 'node',
    },
  },
  {
    test: {
      // egy példa fájlalapú konvencióra,
      // nem kell követnie
      include: [
        'tests/browser/**/*.{test,spec}.ts',
        'tests/**/*.browser.{test,spec}.ts',
      ],
      name: 'browser',
      browser: {
        enabled: true,
        name: 'chrome',
      },
    },
  },
]);

Szolgáltató konfigurációja

:::tabs key:provider == Playwright Konfigurálhatja, hogy a Vitest hogyan indítja el a böngészőt és hogyan hozza létre az oldal kontextust a providerOptions mezőn keresztül:

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

A típusjavaslatokhoz adja hozzá az @vitest/browser/providers/playwright értéket a compilerOptions.types mezőhöz a tsconfig.json fájlban. == WebdriverIO Konfigurálhatja, hogy a Vitest milyen opciókat használjon a böngésző indításakor a providerOptions mezőn keresztül:

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

A típusjavaslatokhoz adja hozzá az @vitest/browser/providers/webdriverio értéket a compilerOptions.types mezőhöz a tsconfig.json fájlban. :::

Böngésző opciótípusok

A Vitest böngésző opciója a szolgáltatótól függ. A Vitest hibát fog jelezni, ha átadja a --browser opciót, és nem adja meg a 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

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 funkciókat 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 funkció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 böngésző opcióban, a Vitest alapértelmezés szerint megpróbálja futtatni a megadott böngészőt a preview segítségével, 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ó használatával.

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

Vagy megadhatja a böngésző opciókat a CLI-nek pontos jelöléssel:

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

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 középen. A nézetablakot konfigurálhatja a kívánt méretek kiválasztásával, a page.viewport meghívásá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 elérhető a böngésző módjában. Headless módban a böngésző a háttérben fut felhasználói felület nélkül, ami hasznos lehet 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 a @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:

export default defineConfig({
  test: {
    browser: {
      provider: 'playwright',
      enabled: true,
      headless: true,
    },
  },
});

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

npx vitest --browser.name=chrome --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 érhető el. Ehhez a playwright vagy a webdriverio szolgáltatókat kell használnia.

Példák

A Vitest csomagokat biztosít a komponensek rendereléséhez számos népszerű keretrendszerhez, gyárilag:

• 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

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ül. Hivatkozást adunk hozzá ezen az oldalon. 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 tartalmazza a @testing-library/jest-dom könyvtárat, hogy széles körű DOM állításokat biztosítson gyárilag. További információt az Állítások API-ban talál.

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

A Vitest egy Context API-t tesz közzé, amely egy kis segédprogramkészletet tartalmaz, amelyek hasznosak lehetnek a tesztekben. 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 funkciót a @vitest/browser/context csomagból. További információt az Interaktivitás API-ban talál.

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

  // Ellenőrzi a kezdeti állapotot.
  await expect
    .element(screen.getByText('Hi, my name is Alice'))
    .toBeInTheDocument();

  // Lekéri az input DOM csomópontot a hozzá tartozó címke lekérdezésével.
  const usernameInput = screen.getByLabelText(/username/i);

  // Beírja a nevet az inputba. Ez már ellenőrzi, hogy az input
  // helyesen van-e kitöltve, nem kell manuálisan ellenőrizni az értéket.
  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-ba
  const screen = render(<Fetch url="/greeting" />);

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

  // ellenőrizze, hogy a figyelmeztető üzenet helyes-e
  await expect.element(heading).toHaveTextContent('hello there');
  await expect.element(screen.getByRole('button')).toBeDisabled();
});

A Vitest nem támogatja az összes keretrendszert alapértelmezés szerint, 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 van ilyenje, nyugodtan adja hozzá a fenti példákhoz.

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

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

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 userEvent funkciót a @vitest/browser/context csomagból, amely a Chrome DevTools Protocolt vagy a Webdrivert (a szolgáltatótól függően) használja a háttérben.

preact

// a @testing-library/preact példa alapján
// 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);

  // A .query() visszaadja az elemet, vagy null-t, ha nem található.
  // A .element() visszaadja az elemet, vagy hibát dob, ha nem található.
  expect(screen.getByText(testMessage).query()).not.toBeInTheDocument();

  // A lekérdezések elfogadhatnak reguláris kifejezést, hogy a szelektorok
  // ellenállóbbak legyenek a tartalom módosításokkal és változásokkal szemben.
  await screen.getByLabelText(/show/i).click();

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

solid

// baed on @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

// 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();
  await expect.element(container.firstChild).toMatchInlineSnapshot(`
    <h1>Hello, Marko!</h1>
  `);
});

Korlátozások

Szálblokkoló párbeszédpanelek

A Vitest böngésző használatakor fontos megjegyezni, hogy a szálblokkoló 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 lefagyását okozza.

Ilyen helyzetekben a Vitest alapértelmezett mockokat biztosít alapértelmezett visszatérési értékekkel ezekhez az API-khoz. Ez biztosítja, hogy ha a felhasználó véletlenül szinkron felugró ablakos webes API-kat használ, a végrehajtás ne fagyjon le. Azonban továbbra is javasolt, hogy a felhasználó mockolja ezeket a webes API-kat a jobb élmény érdekében. További információt a Mocking részben talál.