Tarayıcı Modu Deneysel

Bu sayfa, Vitest API'sindeki deneysel tarayıcı modu özelliği hakkında bilgi vermektedir. Bu özellik, testlerinizi doğrudan tarayıcıda çalıştırmanıza olanak tanır ve window ile document gibi tarayıcı genel değişkenlerine erişim sağlar. Bu özellik şu anda geliştirilme aşamasındadır ve API'leri gelecekte değişebilir.

Kurulum

Kolay kurulum için, gerekli bağımlılıkları yüklemek ve tarayıcı yapılandırması oluşturmak üzere 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 yüklemeniz de mümkündür. Varsayılan olarak Tarayıcı Modu, testleri yerel olarak çalıştırmak için ek bir E2E sağlayıcısı 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 sağlayıcısı yerine bunlardan birini kullanmanızı öneririz; çünkü bu, Chrome DevTools Protokolü yerine olayları simüle etmektedir.

Bu araçlardan birini henüz kullanmıyorsanız, testlerinizi daha hızlı çalıştıran paralel yürütmeyi desteklediği için Playwright ile başlamanızı öneririz. Ayrıca, Playwright'ın kullandığı Chrome DevTools Protokolü genellikle WebDriver'dan daha hızlıdı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 --browser bayrağını kullanabilir veya Vitest yapılandırma dosyanızda browser.enabled alanını true olarak ayarlayabilirsiniz. İşte tarayıcı alanını kullanan bir örnek yapılandırma:

export default defineConfig({
  test: {
    browser: {
      provider: 'playwright', // veya 'webdriverio'
      enabled: true,
      name: 'chromium', // tarayıcı adı gerekli
    },
  },
});

INFO

Vitest, geliştirme sunucusuyla çakışmaları önlemek amacıyla 63315 portunu atar ve her ikisini paralel çalıştırmanıza olanak tanır. 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 yazdırmak için "b" tuşuna basabilirsiniz.

Eğer daha önce Vite kullanmadıysanız, kullandığınız çerçeveye ait eklentinin 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 belgeleri kontrol edin.

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 çalışmak için bir eklenti gerektirmez, ancak preact takma adların çalışması için ek yapılandırma gerektirir.

Bazı testleri Node tabanlı çalıştırıcı kullanarak çalıştırmanız gerekiyorsa, farklı test stratejileri için ayrı yapılandırmalar içeren bir çalışma alanı dosyası tanımlayabilirsiniz:

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

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

Sağlayıcı Yapılandırması

:::tabs key:provider == Playwright Vitest'in tarayıcıyı nasıl başlattığını ve sayfa bağlamını nasıl oluşturduğunu providerOptions alanı aracılığıyla yapılandırabilirsiniz:

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

Tür tanımları için tsconfig.json dosyanızdaki compilerOptions.types'a @vitest/browser/providers/playwright ekleyin. == WebdriverIO Vitest'in bir tarayıcı başlatırken hangi seçenekleri kullanması gerektiğini providerOptions alanı aracılığıyla yapılandırabilirsiniz:

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

Tür tanımları için tsconfig.json dosyanızdaki compilerOptions.types'a @vitest/browser/providers/webdriverio ekleyin. :::

Tarayıcı Seçenek Türleri

Vitest'teki tarayıcı seçeneği sağlayıcıya bağlıdır. --browser bayrağını kullanır ve yapılandırma dosyasında tarayıcı adını belirtmezseniz Vitest başarısız olur. Kullanılabilir seçenekler:

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

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 destekleriz (varsayılan olarak esnext).

Varsayılan olarak, Vite yerel ES Modüllerini, yerel ESM dinamik içe aktarmayı ve import.meta'yı destekleyen tarayıcıları hedefler. Bunun üzerine, 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ışır ve ardından testleri orada çalıştırır. preview kullanmak istemiyorsanız, browser.provider seçeneğini kullanarak özel tarayıcı sağlayıcısını yapılandırabilirsiniz.

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

npx vitest --browser=chrome

Veya nokta notasyonu ile CLI'ya tarayıcı seçenekleri sağlayabilirsiniz:

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

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

Başsız Mod (Headless)

Başsız mod, tarayıcı modunda mevcut olan bir diğer 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ırken, Vitest kullanıcı arayüzünü otomatik olarak açmaz. Kullanıcı arayüzünü kullanmaya devam etmek ancak testleri başsız çalıştırmak istiyorsanız, @vitest/ui paketini kurabilir ve Vitest çalıştırırken --ui bayrağını geçirebilirsiniz.

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

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.name=chrome --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ından birini kullanmanız gerekir.

Örnekler

Vitest, birkaç popüler çerçeve için bileşenleri kutudan çıkar çıkmaz işlemek için paketler sağlar:

• 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

Çerçeve temsil edilmiyorsa, kendi paketinizi oluşturmaktan çekinmeyin - bu, çerçeve render'ı ve page.elementLocator API'si için basit bir sarmalayıcıdır. Bu sayfaya bir bağlantı ekleyeceğiz. Adının vitest-browser- ile başladığından emin olun.

Bileşenleri render etmek ve elementleri bulmanın yanı sıra, assertion'lar da yapmanız gerekir. Vitest, çok çeşitli DOM onaylamaları sağlamak için @testing-library/jest-dom kitaplığını paketler. Daha fazla bilgi için Onaylama API'si bölümüne bakın.

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

Vitest, testlerde size faydalı olabilecek küçük bir yardımcı program kümesiyle bir Bağlam API'si sunar. Örneğin, bir öğeye tıklama veya bir girişe 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.

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

  // Başlangıç durumunu onaylar.
  await expect
    .element(screen.getByText('Hi, my name is Alice'))
    .toBeInTheDocument();

  // İlişkili etiketi sorgulayarak giriş DOM düğümünü alın.
  const usernameInput = screen.getByLabelText(/username/i);

  // Adı girişe yazın. Bu, girişin doğru şekilde doldurulduğunu zaten doğrular,
  // değeri manuel olarak kontrol etmeye gerek yoktur.
  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 () => {
  // Bir React öğesini DOM'a işleyin
  const screen = render(<Fetch url="/greeting" />);

  await screen.getByText('Load Greeting').click();
  // bir öğe bulamazsa hata atmadan önce bekleyin
  const heading = screen.getByRole('heading');

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

Vitest tüm çerçeveleri kutudan çıkar çıkmaz 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 çekinmeyin.

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

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

WARNING

testing-library, @testing-library/user-event paketini sağlar. Bunu doğrudan kullanmanızı önermiyoruz çünkü olayları gerçekten tetiklemek yerine simüle eder - bunun yerine, altta yatan Chrome DevTools Protokolü veya Webdriver'ı (sağlayıcıya bağlı olarak) kullanan @vitest/browser/context'ten içe aktarılan userEvent'i kullanın.

preact

// @testing-library/preact örneğine dayanmaktadır
// 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() öğeyi döndürür veya bulunamazsa null döndürür.
  // .element() öğeyi döndürür veya bulunamazsa hata fırlatır.
  expect(screen.getByText(testMessage).query()).not.toBeInTheDocument();

  // Sorgular, seçicilerinizi içerik değişikliklerine karşı daha
  // dirençli hale getirmek için bir regex kabul edebilir.
  await screen.getByLabelText(/show/i).click();

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

solid

// @testing-library/solid API'sine dayanmaktadır
// 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

// @testing-library/marko API'sine dayanmaktadır
// 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>
  `);
});

Sınırlamalar

İş Parçacığını Engelleyen İletişim Kutuları

Vitest Tarayıcı kullanırken, alert veya confirm gibi iş parçacığını engelleyen iletişim kutularının yerel olarak kullanılamayacağını unutmamak önemlidir. Bunun nedeni, web sayfasını engellemeleri, yani Vitest'in sayfayla iletişim kurmaya devam edememesi ve yürütmenin takılmasıdır.

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