Playwright Yapılandırma Dosyası: playwright.config.ts

Playwright Yapılandırma Dosyası: playwright.config.ts Nasıl Çalışır?

Playwright, modern web uygulamalarında uçtan uca (E2E) testler yazmak ve çalıştırmak için kullanılan bir test framework’üdür. Kullanıcının uygulamada yaptığı gerçek akışları örneğin bir sayfayı açma, form doldurma, içerik yayınlama veya giriş yapma gibi durumları browser üzerinden test etmemizi sağlıyor.

Kendi sitemde Playwright’ı özellikle admin panelindeki giriş, yazı oluşturma, kategori seçimi ve yayınlama akışlarını kontrol etmek için kullanıyorum. Bu testler, yalnızca bir butonun çalıştığını değil; içerik yönetim sürecinin kullanıcı açısından uçtan uca tamamlanabildiğini kontrol etmemi sağlıyor.

Playwright ile çalışırken ilk bakılması gereken dosyalardan biri playwright.config.ts dosyasıdır. Bu dosya; testlerin nerede bulunduğunu, hangi tarayıcılarda çalışacağını, başarısız testlerde ne toplanacağını ve CI ortamında nasıl davranacağını belirler.

Bu yazıda playwright.config.ts dosyasındaki temel ayarları ve testleri çalıştırmayı kolaylaştıran komutları inceliyorum.

Başlangıç: defineConfig ve devices

TypeScript kullanan bir projede dosya genellikle şu şekilde başlar:

import { defineConfig, devices } from '@playwright/test';

Burada iki önemli yapı kullanılır:

• defineConfig, Playwright ayarlarını daha düzenli ve TypeScript tarafından kontrol edilebilir biçimde tanımlamayı sağlar.

• devices, Playwright’ın hazır masaüstü ve mobil cihaz profillerini içerir. Böylece ekran boyutu, kullanıcı aracısı (user agent) ve benzeri ayarları tek tek yazmadan kullanabiliriz.

Örneğin devices['Desktop Chrome'], masaüstü Chrome deneyimini taklit eden hazır bir ayardır.

Temel yapılandırma örneği

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://127.0.0.1:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },

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

  webServer: {
    command: 'npm run dev',
    url: 'http://127.0.0.1:3000',
    reuseExistingServer: !process.env.CI,
  },
});

Bu dosyada yapılan bir değişiklik, tek bir testi değil, projenin tüm test çalışma biçimini etkiler. Bu yüzden ayarları bilinçli seçmek önemlidir.

Testlerin bulunduğu klasör: testDir

testDir: './tests',

Bu ayar Playwright’a test dosyalarının nerede olduğunu söyler. Örnekte testler, projenin kökündeki tests klasöründe aranır.

Proje büyüdükçe testleri amacına göre ayırmak işleri kolaylaştırır:

tests/
  e2e/
  admin/
  public/

Testleri paralel çalıştırmak: fullyParallel

Testlerin paralel çalışması süreyi kısaltır. Ancak aynı admin hesabını veya aynı içerikleri kullanan testlerde çakışma yaşanmaması için test senaryolarının birbirinden bağımsız tasarlanması gerekir.

fullyParallel: true,

Bu ayar, uygun testlerin aynı anda çalışmasına izin verir. Test süresini ciddi biçimde azaltabilir.

Ancak burada küçük bir şart vardır: Testler birbirinden bağımsız olmalıdır. Örneğin iki test aynı anda aynı kullanıcı hesabındaki aynı yazıyı düzenliyorsa çakışma yaşanabilir. Paralel test kullanırken her testin kendi verisini oluşturması ya da temizlemesi daha güvenlidir.

CI ortamında test.only hatasını önlemek

forbidOnly: !!process.env.CI,

Geliştirme sırasında bazen sadece tek bir testi çalıştırmak için test.only kullanılır:

test.only('admin yazı oluşturabilir', async ({ page }) => {
  // ...
});

Bu satır unutulursa CI ortamında yalnızca o test çalışır; diğer testler sessizce atlanır. forbidOnly ayarı, CI sırasında bunu hata kabul eder ve eksik test çalıştırılmasını engeller.

Başarısız testleri yeniden denemek: retries

retries: process.env.CI ? 2 : 0,

Bazı testler uygulama hatasından değil; yavaş ağ, geç yanıt veren bir servis veya zamanlama problemi nedeniyle arada bir başarısız olabilir.

Bu ayar:

• Yerelde test başarısız olursa yeniden deneme yapmaz.

• CI ortamında başarısız testi en fazla iki kez daha dener.

Yeniden deneme, hatayı gizlemek için değil; geçici test kararsızlıklarını ayırt etmek için kullanılmalıdır. Sürekli yeniden denemeye ihtiyaç duyan bir testin neden başarısız olduğunu ayrıca incelemek gerekir.

Worker sayısı: workers

workers: process.env.CI ? 1 : undefined,

Worker, testleri çalıştıran paralel işlem sayısıdır.

Bu örnekte CI ortamında tek worker kullanılır. Bu yaklaşım testleri daha yavaş çalıştırabilir; fakat özellikle aynı veritabanını veya aynı admin hesabını kullanan projelerde daha tutarlı sonuç verir.

Yerel ortamda undefined değeri kullanıldığında Playwright, bilgisayarın kapasitesine göre uygun varsayılanı seçer.

Test raporları: reporter

reporter: 'html',

Bu ayar test sonucu için HTML raporu üretir. Başarısız testleri, hata mesajlarını ve varsa ek dosyaları tarayıcıdan incelemeyi kolaylaştırır.

Raporu görüntülemek için genellikle şu komut kullanılır:

npx playwright show-report

CI süreçlerinde JSON veya JUnit gibi ek rapor formatları da kullanılabilir. Ancak kişisel projelerde HTML raporu başlangıç için yeterli ve pratiktir.

Ortak test ayarları: use

use alanı, tüm testlerde varsayılan olarak kullanılacak tarayıcı ayarlarını içerir.

use: {
  baseURL: 'http://127.0.0.1:3000',
  trace: 'on-first-retry',
  screenshot: 'only-on-failure',
  video: 'retain-on-failure',
},

baseURL

baseURL: 'http://127.0.0.1:3000',

Bu ayar sayesinde testlerde tam adres yazmak zorunda kalmayız.

await page.goto('/admin/login');

Playwright bunu otomatik olarak aşağıdaki adrese tamamlar:

http://127.0.0.1:3000/admin/login

Yerel, staging ve canlı ortam için farklı baseURL değerleri kullanılabilir. Bu yaklaşım test kodunu ortam adreslerinden bağımsız hâle getirir.

trace

trace: 'on-first-retry',

Trace, başarısız testleri incelemek için en faydalı Playwright özelliklerinden biridir. Test sırasında yapılan işlemleri, sayfa ekranını, ağ isteklerini ve hata anındaki durumu incelemeye yardımcı olur.

on-first-retry değeri, trace’in yalnızca test ilk kez başarısız olduktan sonra yeniden denendiğinde kaydedilmesini sağlar. Böylece her testte gereksiz büyük dosyalar oluşmaz.

Bir trace dosyasını görüntülemek için:

npx playwright show-trace trace.zip

komutu kullanılabilir.

screenshot ve video

screenshot: 'only-on-failure',
video: 'retain-on-failure',

Bu iki ayar, başarısız testleri anlamayı kolaylaştırır:

• screenshot: 'only-on-failure': Test başarısız olduğunda ekran görüntüsü alır.

• video: 'retain-on-failure': Başarısız olan testin videosunu saklar.

Özellikle admin paneli gibi çok adımlı akışlarda, “test neden başarısız oldu?” sorusuna cevap bulmayı hızlandırır.

Farklı tarayıcılarda test çalıştırmak: projects

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

projects alanı, aynı testlerin farklı tarayıcı veya cihaz profillerinde çalıştırılmasını sağlar.

Bu örnekte üç temel tarayıcı motoru test edilir:

ProjeTemsil ettiği ortamchromiumChrome ve Edge tabanlı tarayıcılarfirefoxMozilla FirefoxwebkitSafari’nin kullandığı tarayıcı motoru

Buradaki önemli ayrım şudur: Desktop Safari ayarı gerçek macOS Safari uygulamasını açmaz; Safari ile aynı motor ailesini kullanan WebKit ortamında test çalıştırır. Yine de Safari kaynaklı uyumluluk sorunlarını daha erken yakalamak için değerlidir.

Mobil görünümü de test etmek istersek ayrıca proje ekleyebiliriz:

{
  name: 'Mobile Chrome',
  use: { ...devices['Pixel 5'] },
},
{
  name: 'Mobile Safari',
  use: { ...devices['iPhone 12'] },
},

Her projeyi sürekli çalıştırmak zorunda değiliz. Örneğin günlük geliştirme sırasında yalnızca Chromium ile hızlı test çalıştırıp, yayın öncesi tüm tarayıcıları kontrol etmek mantıklı olabilir.

Geliştirme sunucusunu otomatik başlatmak: webServer

webServer: {
  command: 'npm run dev',
  url: 'http://127.0.0.1:3000',
  reuseExistingServer: !process.env.CI,
},

webServer, testler başlamadan önce uygulamanın ayağa kalkmasını sağlar.

• command: Uygulamayı çalıştıracak komuttur.

• url: Playwright’ın uygulamanın hazır olup olmadığını kontrol edeceği adrestir.

• reuseExistingServer: Yerelde zaten açık olan geliştirme sunucusunu kullanır; gereksiz ikinci bir sunucu başlatmaz.

Next.js projelerinde yerel geliştirme için npm run dev, yayın benzeri ortamı test etmek için ise çoğu zaman npm run build && npm run start tercih edilir. Ama ben kendi Next.js projemde yerelde geliştirme sırasında npm run dev kullanıyorum. Yayına daha yakın bir kontrol gerektiğinde ise build alınıp uygulamanın production modunda çalıştırılması daha güvenilir sonuç veriyor.

Ortam değişkenleri: .env

Bazı projelerde test adresi, test kullanıcısı veya parola gibi bilgiler ortam değişkenlerinden okunur. Örneğin:

import 'dotenv/config';

veya daha özel bir dosya kullanmak için:

import dotenv from 'dotenv';
import path from 'path';

dotenv.config({
  path: path.resolve(__dirname, '.env'),
});

Ancak kullanıcı adı, parola veya erişim anahtarı gibi hassas bilgiler .env dosyasında tutulsa bile Git’e eklenmemelidir. Bunun için .env dosyasının .gitignore içinde yer alması gerekir.

Kullanışlı test komutları

package.json içine anlamlı komutlar eklemek, testleri hem çalıştırmayı hem de ekip içinde anlaşılmasını kolaylaştırır:

{
  "scripts": {
    "test:e2e": "playwright test",
    "test:e2e:ui": "playwright test --ui",
    "test:e2e:headed": "playwright test --headed",
    "test:e2e:debug": "playwright test --debug",
    "test:e2e:report": "playwright show-report"
  }
}

Bu komutların kullanım amacı şöyledir:

KomutKullanım amacınpm run test:e2eTüm uçtan uca testleri çalıştırır.npm run test:e2e:uiTestleri Playwright’ın görsel arayüzünde çalıştırır.npm run test:e2e:headedTarayıcıyı görünür şekilde açarak test çalıştırır.npm run test:e2e:debugTesti adım adım incelemek için debug modunda başlatır.npm run test:e2e:reportSon HTML test raporunu açar.

Başlangıçta en çok kullandığım komutlar test:e2e:ui, test:e2e:headed ve test:e2e:debug oluyor. Bir testin neden başarısız olduğunu yalnızca hata mesajından anlamak zor olduğunda, görünür tarayıcı veya debug modu çok daha hızlı sonuç veriyor.

Sonuç

playwright.config.ts, testlerin arka plandaki çalışma kurallarını belirleyen merkezî dosyadır. Test klasörü, tarayıcılar, paralel çalışma, yeniden deneme, raporlama, ekran görüntüsü ve trace gibi ayarlar burada toplanır.

İyi bir yapılandırma yalnızca testleri çalıştırmaz; test başarısız olduğunda hatayı anlayabilmeyi de kolaylaştırır. Özellikle gerçek kullanıcı akışlarını test eden projelerde, HTML raporu, trace, ekran görüntüsü ve video ayarları zaman kazandıran araçlardır.