Kurulum

Uçtan Uca Test Nedir?

Vitest dersleri bir component'i ya da hook'u tek başına, JSDOM içinde test eder. Uçtan uca (end-to-end, E2E) test ise uygulamanın tamamını gerçek bir tarayıcıda çalıştırır: sayfa açılır, kullanıcı gibi tıklanır, yazılır ve ekranda görünen sonuç doğrulanır. Sunucu, veritabanı, yönlendirme ve cookie'ler de işin içindedir.

Martin Fowler test piramidinde uçtan uca testleri en üste koyar: en değerli güveni verirler ama en yavaş ve en kırılgan olanlardır. Bu yüzden sayıları az tutulur; her ayrıntı alttaki hızlı testlerle sınanır.¹

Playwright, Microsoft'un geliştirdiği açık kaynak test aracıdır. Chromium, Firefox ve WebKit'i tek bir API ile yönetir; testleri paralel ve varsayılan olarak görünmez (headless) tarayıcıda çalıştırır.²

Kurulum

Playwright'ın desteklediği Node.js sürümleri 22, 24 ve 26'dır.² Mevcut bir Next.js projesinin kök klasöründe şu komutu çalıştırın:

$ npm init playwright@latest

Komut birkaç soru sorar: TypeScript mi JavaScript mi, testlerin klasörü (varsayılan tests), GitHub Actions iş akışı eklensin mi, tarayıcılar indirilsin mi. Komutu daha sonra tekrar çalıştırmak mevcut testleri silmez.²

Oluşan dosyalar:

playwright.config.ts         # Yapılandırma
tests/
  example.spec.ts            # Örnek test
.github/workflows/playwright.yml   # İstediyseniz CI iş akışı

package.json'a @playwright/test eklenir. .gitignore'a test çıktıları yazılır: test-results/, playwright-report/, blob-report/, playwright/.cache/ ve playwright/.auth/.

Tarayıcıları sonradan indirmek ya da yalnızca birini kurmak için:

$ pnpm dlx playwright install chromium

playwright.config.ts

Oluşan dosyanın sadeleştirilmiş hali ve her alanın görevi:⁴

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: "html",
  use: {
    baseURL: "http://localhost:3000",
    trace: "on-first-retry",
  },
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
    { name: "webkit", use: { ...devices["Desktop Safari"] } },
  ],
});

Varsayılan olarak her test 30 saniye, her web-first assertion 5 saniye bekler.⁵

Projeler ve default: false

Her proje aynı testleri farklı bir ayarla çalıştırır. Playwright 1.64 ile bir projeyi yapılandırmada tutup varsayılan çalıştırmadan çıkarabilirsiniz. Yerelde yalnızca Chromium çalışır; CI'da hepsi:⁶

projects: [
  { name: "chromium", use: { ...devices["Desktop Chrome"] } },
  { name: "firefox", use: { ...devices["Desktop Firefox"] }, default: false },
  { name: "webkit", use: { ...devices["Desktop Safari"] }, default: false },
],

$ pnpm dlx playwright test --project="*"

webServer: Uygulamayı Playwright Başlatsın

Testler çalışan bir uygulamaya ihtiyaç duyar. webServer alanı, testlerden önce sunucuyu başlatır ve adres yanıt verene kadar bekler.⁷ Next.js dokümanı testleri production build'e karşı çalıştırmayı önerir; uygulama gerçekte nasıl çalışacaksa öyle test edilir.³

webServer: {
  command: "npm run build && npm run start",
  url: "http://localhost:3000",
  reuseExistingServer: !process.env.CI,
  timeout: 180_000,
},

reuseExistingServer yerelde zaten çalışan bir sunucu varsa onu kullanır; CI'da her zaman yenisini başlatır. Build birkaç dakika sürebileceği için timeout'u varsayılan 60 saniyeden yüksek tutun.⁷

Testleri Çalıştırmak

$ pnpm dlx playwright test

Sık kullanılan seçenekler:²⁸

HTML rapor yalnızca test başarısız olunca kendiliğinden açılır.²

VS Code kullanıyorsanız Playwright eklentisi testleri editörden çalıştırmayı, kesme noktası koymayı ve locator seçmeyi sağlar.⁹

Kendin Dene

• Bir Next.js projesine Playwright'ı ekleyin. tests/example.spec.ts'i çalıştırın, sonra npx playwright show-report ile raporu açın.

• Firefox ve WebKit projelerine default: false ekleyin. npx playwright test ve npx playwright test --project="*" çıktılarındaki test sayısını karşılaştırın.

• webServer'ı ekleyin, baseURL'i ayarlayın. Örnek testteki adresi page.goto("/") yapın.

• npx playwright test --ui ile UI Mode'u açın ve bir testi adım adım izleyin.

Detaylı Öğrenmek İçin

• Resmi doküman: Playwright, "Installation"; kurulum, oluşan dosyalar ve ilk çalıştırma.²

• Resmi doküman: Next.js, "How to set up Playwright with Next.js"; production build'e karşı test önerisi.³

• Yazı: Martin Fowler, "Test Pyramid"; uçtan uca testlerin neden az tutulduğu.¹