Tarayıcı Modu Deneysel

Bu sayfa, Vitest API'deki deneysel tarayıcı modu özelliği hakkında bilgi vermektedir. Bu özellik, testlerinizi doğrudan bir tarayıcı ortamında çalıştırmanıza olanak tanır ve window ile document gibi tarayıcıya özgü global değişkenlere erişim sağlar. Bu özellik halen geliştirme aşamasındadır ve API'leri gelecekte değişebilir.

TIP

expect, vi veya test projeleri ya da tür testi gibi genel API'ler hakkında dokümantasyon arıyorsanız, lütfen "Başlarken" kılavuzuna bakın.

Kurulum

Kurulumu kolaylaştırmak için, gerekli bağımlılıkları yüklemek ve tarayıcı yapılandırması oluşturmak amacıyla vitest init browser komutunu kullanabilirsiniz.

npm

npx vitest init browser

yarn

yarn exec vitest init browser

pnpm

pnpx vitest init browser

bun

bunx vitest init browser

Manuel Kurulum

Paketleri manuel olarak da yükleyebilirsiniz. Varsayılan olarak Tarayıcı Modu, yerel testler için ek E2E sağlayıcı gerektirmez çünkü mevcut tarayıcınızı yeniden kullanır.

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

Ancak, CI ortamında testleri çalıştırmak için playwright veya webdriverio kurmanız gerekmektedir. Ayrıca, yerel testler için varsayılan preview yerine bunlardan birini kullanmanızı öneririz; zira bu, Chrome DevTools Protokolü yerine olayları simüle etmeye dayanmaktadır.

Bu araçlardan birini zaten kullanmıyorsanız, Playwright ile başlamanızı öneririz çünkü paralel yürütmeyi destekler, bu da testlerinizin daha hızlı çalışmasını sağlar. Ek olarak, Playwright genellikle WebDriver'dan daha hızlı olan Chrome DevTools Protokolü'nü kullanır.

::: tabs key:provider == Playwright Playwright Web Test ve Otomasyonu için bir çerçevedir.

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 protokolünü kullanarak testleri yerel olarak çalıştırmanıza olanak tanır.

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

Yapılandırma

Vitest yapılandırmanızda tarayıcı modunu etkinleştirmek için, Vitest yapılandırma dosyanızdaki browser.enabled alanını true olarak ayarlayın. İşte tarayıcı alanının kullanıldığı bir örnek yapılandırma:

import { defineConfig } from 'vitest/config';
export default defineConfig({
  test: {
    browser: {
      provider: 'playwright', // veya 'webdriverio'
      enabled: true,
      // en az bir örnek gereklidir
      instances: [{ browser: 'chromium' }],
    },
  },
});

INFO

Vitest, geliştirme sunucusuyla çakışmaları önlemek amacıyla 63315 numaralı bağlantı noktasını atar ve her ikisini de paralel çalıştırmanıza olanak sağlar. Bunu browser.api seçeneğiyle değiştirebilirsiniz.

Vitest 2.1.5'ten beri, CLI artık Vite URL'sini otomatik olarak yazdırmaz. İzleme modunda çalışırken URL'yi görüntülemek için "b" tuşuna basabilirsiniz.

Daha önce Vite kullanmadıysanız, kullandığınız çerçeve eklentisinin kurulu olduğundan ve yapılandırmada belirtildiğinden emin olun. Bazı çerçeveler çalışmak için ek yapılandırma gerektirebilir; emin olmak için Vite ile ilgili belgelerini kontrol edin.

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

Bazı testleri Node tabanlı çalıştırıcı kullanarak çalıştırmanız gerekiyorsa, farklı test stratejileri için ayrı yapılandırmalarla bir projects seçeneği tanımlayabilirsiniz:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          // dosya tabanlı bir kural örneği,
          // bunu takip etmek zorunda değilsiniz
          include: [
            'tests/unit/**/*.{test,spec}.ts',
            'tests/**/*.unit.{test,spec}.ts',
          ],
          name: 'unit',
          environment: 'node',
        },
      },
      {
        test: {
          // dosya tabanlı bir kural örneği,
          // bunu takip etmek zorunda değilsiniz
          include: [
            'tests/browser/**/*.{test,spec}.ts',
            'tests/**/*.browser.{test,spec}.ts',
          ],
          name: 'browser',
          browser: {
            enabled: true,
            instances: [{ browser: 'chromium' }],
          },
        },
      },
    ],
  },
});

Tarayıcı Seçenek Türleri

Vitest'teki tarayıcı seçeneği sağlayıcıya bağlıdır. --browser parametresini kullanır ve yapılandırma dosyasında adını belirtmezseniz Vitest hata verecektir. Mevcut seçenekler:

• webdriverio şu tarayıcıları destekler:
  • firefox
  • chrome
  • edge
  • safari
• playwright şu tarayıcıları destekler:
  • firefox
  • webkit
  • chromium

TypeScript

Varsayılan olarak, TypeScript sağlayıcı seçeneklerini ve ek expect özelliklerini tanımaz. Herhangi bir sağlayıcı kullanmıyorsanız, @vitest/browser/matchers'ın testlerinizde, kurulum dosyanızda veya yapılandırma dosyanızda bir yerde referans gösterildiğinden emin olun, böylece ek expect tanımları yüklenebilir. Özel sağlayıcılar kullanıyorsanız, TypeScript'in özel seçenekler için tanımları algılayabilmesi amacıyla @vitest/browser/providers/playwright veya @vitest/browser/providers/webdriverio'yu aynı dosyaya eklediğinizden emin olun:

default

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

playwright

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

webdriverio

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

Alternatif olarak, bunları tsconfig.json dosyanızdaki compilerOptions.types alanına da ekleyebilirsiniz. Bu alanda herhangi bir şey belirtmenin @types/* paketlerinin otomatik yüklenmesini devre dışı bırakacağını unutmayınız.

default

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

playwright

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

webdriverio

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

Tarayıcı Uyumluluğu

Vitest, testlerinizi çalıştırmak için Vite geliştirme sunucusunu kullanır; bu nedenle yalnızca esbuild.target seçeneğinde belirtilen özellikleri (varsayılan olarak esnext) destekleriz.

Varsayılan olarak, Vite yerel ES Modüllerini, yerel ESM dinamik içe aktarmayı ve import.meta destekleyen tarayıcıları hedefler. Buna ek olarak, iframe'ler arasında iletişim kurmak için BroadcastChannel kullanırız:

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

Testleri Çalıştırma

Tarayıcı seçeneğinde bir tarayıcı adı belirttiğinizde, Vitest varsayılan olarak belirtilen tarayıcıyı preview kullanarak çalıştırmaya çalışacak ve testleri o ortamda çalıştıracaktır. preview kullanmak istemiyorsanız, browser.provider seçeneğini kullanarak özel bir tarayıcı sağlayıcısı yapılandırabilirsiniz.

CLI üzerinden bir tarayıcı belirtmek için, --browser bayrağını ve ardından tarayıcı adını kullanın, örneğin:

npx vitest --browser=chromium

Veya CLI'ya nokta gösterimiyle tarayıcı seçenekleri sunabilirsiniz:

npx vitest --browser.headless

WARNING

Vitest 3.2'den itibaren, yapılandırmanızda browser seçeneği yoksa ancak --browser bayrağını belirtirseniz, Vitest hata verecektir; çünkü yapılandırmanın tarayıcı testleri için mi yoksa Node.js testleri için mi olduğunu varsayamaz.

Varsayılan olarak, Vitest geliştirme amacıyla tarayıcı kullanıcı arayüzünü otomatik olarak açacaktır. Testleriniz ortadaki bir iframe içerisinde çalışacaktır. Tercih edilen boyutları seçerek, test içinde page.viewport çağırarak veya yapılandırmada varsayılan değerleri belirleyerek görünüm alanını yapılandırabilirsiniz.

Başsız Mod

Başsız mod, tarayıcı modunda mevcut olan başka bir seçenektir. Başsız modda, tarayıcı kullanıcı arayüzü olmadan arka planda çalışır; bu da otomatik testleri çalıştırmak için kullanışlıdır. Vitest'teki başsız seçeneği, başsız modu etkinleştirmek veya devre dışı bırakmak için bir boolean değere ayarlanabilir.

Başsız mod kullanılırken, Vitest kullanıcı arayüzünü otomatik olarak açmayacaktır. Kullanıcı arayüzünü kullanmaya devam etmek ancak testleri başsız çalıştırmak istiyorsanız, @vitest/ui paketini kurabilir ve Vitest'i çalıştırırken --ui bayrağını ekleyebilirsiniz.

İşte başsız modu etkinleştiren bir örnek yapılandırma:

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

Başsız modu CLI'da --browser.headless bayrağını kullanarak da ayarlayabilirsiniz, örneğin:

npx vitest --browser.headless

Bu durumda, Vitest Chrome tarayıcısını kullanarak başsız modda çalışacaktır.

WARNING

Başsız mod varsayılan olarak kullanılamaz. Bu özelliği etkinleştirmek için playwright veya webdriverio sağlayıcılarını kullanmanız gerekmektedir.

Örnekler

Varsayılan olarak, Tarayıcı Modu ile çalışmak için herhangi bir harici pakete ihtiyacınız bulunmamaktadır:

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

test('form girişlerini doğru şekilde yönetir', async () => {
  render(); // DOM öğelerini oluştur

  // Başlangıç durumunu doğrular.
  await expect
    .element(page.getByText('Merhaba, benim adım Alice'))
    .toBeInTheDocument();

  // İlişkili etiketi sorgulayarak giriş DOM düğümünü elde et.
  const usernameInput = page.getByLabelText(/kullanıcı adı/i);

  // Adı giriş alanına yazın. Bu işlem, girişin doğru doldurulduğunu zaten doğrular;
  // değeri manuel olarak kontrol etmeye gerek yoktur.
  await usernameInput.fill('Bob');

  await expect
    .element(page.getByText('Merhaba, benim adım Bob'))
    .toBeInTheDocument();
});

Ancak, Vitest ayrıca birkaç popüler çerçeve için bileşenleri doğrudan kullanıma hazır şekilde işlemek üzere paketler sunar:

• vue bileşenlerini işlemek için vitest-browser-vue
• svelte bileşenlerini işlemek için vitest-browser-svelte
• react bileşenlerini işlemek için vitest-browser-react

Diğer çerçeveler için topluluk paketleri mevcuttur:

• lit bileşenlerini işlemek için vitest-browser-lit
• preact bileşenlerini işlemek için vitest-browser-preact

Kullandığınız çerçeve burada temsil edilmiyorsa, kendi paketinizi oluşturmaktan çekinmeyin – bu, çerçeve işleyicisi ve page.elementLocator API'si etrafında basit bir sarmalayıcıdır. Bu sayfaya bir bağlantı eklenecektir. Adının vitest-browser- ile başladığından emin olunuz.

Bileşenleri işlemek ve öğeleri bulmak dışında, onaylamalar da yapmanız gerekecektir. Vitest, geniş bir DOM onaylama yelpazesi sunmak amacıyla @testing-library/jest-dom kütüphanesini çatallamıştır. Daha fazla bilgi için Onaylama API'si bölümüne bakınız.

import { expect } from 'vitest';
import { page } from '@vitest/browser/context';
// öğe doğru şekilde işlendi
await expect.element(page.getByText('Merhaba Dünya')).toBeInTheDocument();

Vitest, testlerde size faydalı olabilecek küçük bir yardımcı program kümesi içeren bir Bağlam API'si sunar. Örneğin, bir öğeye tıklama veya bir giriş alanına metin yazma gibi bir etkileşim yapmanız gerekiyorsa, @vitest/browser/context'ten userEvent kullanabilirsiniz. Daha fazla bilgi için Etkileşim API'si bölümüne bakınız.

import { page, userEvent } from '@vitest/browser/context';
await userEvent.fill(page.getByLabelText(/kullanıcı adı/i), 'Alice');
// veya sadece locator.fill
await page.getByLabelText(/kullanıcı adı/i).fill('Alice');

vue

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

test("v-model'i düzgün bir şekilde işler", async () => {
  const screen = render(Component);

  // Başlangıç durumunu doğrular.
  await expect
    .element(screen.getByText('Merhaba, benim adım Alice'))
    .toBeInTheDocument();

  // İlişkili etiketi sorgulayarak giriş DOM düğümünü elde et.
  const usernameInput = screen.getByLabelText(/kullanıcı adı/i);

  // Adı girişe yaz. Bu zaten girişin doğru doldurulduğunu doğrular,
  // değeri manuel olarak kontrol etmeye gerek yok.
  await usernameInput.fill('Bob');

  await expect
    .element(screen.getByText('Merhaba, benim adım Bob'))
    .toBeInTheDocument();
});

svelte

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

import Greeter from './greeter.svelte';

test('tıklamada selamlama görünür', async () => {
  const screen = render(Greeter, { name: 'World' });

  const button = screen.getByRole('button');
  await button.click();
  const greeting = screen.getByText(/merhaba dünya/iu);

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

react

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

test('selamlamayı yükler ve görüntüler', async () => {
  // Bir React öğesini DOM'a render et
  const screen = render(<Fetch url="/greeting" />);

  await screen.getByText('Selamlamayı Yükle').click();
  // bir öğe bulamazsa hata atmadan önce bekle
  const heading = screen.getByRole('heading');

  // uyarı mesajının doğru olduğunu doğrula
  await expect.element(heading).toHaveTextContent('selam');
  await expect.element(screen.getByRole('button')).toBeDisabled();
});

lit

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

test('tıklamada selamlama görünür', async () => {
  const screen = render(html`<greeter-button name="World"></greeter-button>`);

  const button = screen.getByRole('button');
  await button.click();
  const greeting = screen.getByText(/merhaba dünya/iu);

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

preact

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

test('tıklamada selamlama görünür', async () => {
  const screen = render(<Greeting />);

  const button = screen.getByRole('button');
  await button.click();
  const greeting = screen.getByText(/merhaba dünya/iu);

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

Vitest tüm çerçeveleri doğrudan kullanıma hazır şekilde desteklemez, ancak bu çerçevelerle testleri çalıştırmak için harici araçları kullanabilirsiniz. Ayrıca topluluğu kendi vitest-browser sarmalayıcılarını oluşturmaya teşvik ediyoruz; eğer bir tane varsa, yukarıdaki örneklere eklemekten çekinmeyiniz.

Desteklenmeyen çerçeveler için testing-library paketlerini kullanmanızı öneririz:

• solid bileşenlerini işlemek için @solidjs/testing-library
• marko bileşenlerini işlemek için @marko/testing-library

Daha fazla örneği browser-examples deposunda da bulabilirsiniz.

WARNING

testing-library @testing-library/user-event paketini sunar. Doğrudan kullanmanızı önermiyoruz; zira olayları gerçekten tetiklemek yerine simüle eder. Bunun yerine, arka planda Chrome DevTools Protokolü veya Webdriver (sağlayıcıya bağlı olarak) kullanan @vitest/browser/context'ten içe aktarılan userEvent kullanınız.

solid

// @testing-library/solid API'sine göre
// https://testing-library.com/docs/solid-testing-library/api

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

it('parametreleri kullanır', async () => {
  const App = () => (
    <>
      <Route
        path="/ids/:id"
        component={() => (
          <p>
            Id:
            {useParams()?.id}
          </p>
        )}
      />
      <Route path="/" component={() => <p>Başlangıç</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'sine göre
// https://testing-library.com/docs/marko-testing-library/api

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

test('bir mesajı işler', 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>Merhaba, Marko!</h1>
  `);
});

Sınırlamalar

İş Parçacığını Engelleyen Diyaloglar

Vitest Tarayıcı kullanırken, alert veya confirm gibi iş parçacığı engelleyici diyalogların doğrudan kullanılamayacağını unutmamak önemlidir. Bunun nedeni, web sayfasını engellemeleri ve bu durumun Vitest'in sayfayla iletişim kurmaya devam edememesine, dolayısıyla yürütmenin takılmasına neden olmasıdır.

Bu gibi durumlarda, Vitest bu API'ler için varsayılan döndürülen değerlerle varsayılan sahte nesneler sunar. Bu, kullanıcının yanlışlıkla senkronize açılır web API'lerini kullanması durumunda yürütmenin takılmasını önler. Ancak, daha iyi bir deneyim için kullanıcının bu web API'lerini sahte olarak kullanması yine de önerilmektedir. Daha fazla bilgi için Sahte Nesneler bölümüne bakınız.