Trace ile hata ayıklama

Önce Hata Mesajını Okuyun

Başarısız bir testin çıktısı çoğu zaman sorunu söyler. Bu rehberin projesinde sipariş sayısını bilerek yanlış yazınca çıkan hata:

Error: expect(locator).toHaveCount(expected) failed

Locator:  getByRole('table', { name: 'Sipariş listesi' }).getByRole('row').filter({ has: getByRole('cell') })
Expected: 7
Received: 6
Timeout:  2000ms

Call log:
  - waiting for getByRole('table', { name: 'Sipariş listesi' }).getByRole('row')...
    6 × locator resolved to 0 elements
    14 × locator resolved to 6 elements

Call log hikâyeyi anlatır: tablo önce boştu (liste yükleniyordu), sonra 6 satır geldi ve hiç 7 olmadı. Locator doğru, beklenti yanlış. "0 element" satırı hiç bitmeseydi locator'ı sorgulardınız.

Hata ayrıca bir error-context dosyası üretir: test-results/<test>/error-context.md. İçinde testin adı, hata ve sayfanın o anki aria snapshot'ı vardır. Dosya bir yapay zekâ asistanına "neden düştü, düzeltmesi ne" diye sorulacak biçimde yazılmıştır; kendiniz okurken de sayfada neyin göründüğünü hızlıca gösterir.

UI Mode

Test yazarken en verimli araç UI Mode'dur:¹

$ pnpm dlx playwright test --ui

• Testleri listeden seçip çalıştırırsınız; dosya değişince yeniden çalıştıran izleme modu vardır.

• Her adım zaman çizelgesinde görünür. Bir adıma tıklayınca sayfanın o anki halini görürsünüz.

• "Pick locator" ile sayfadaki bir elementin locator'ını alırsınız.

• Konsol, ağ istekleri ve hata aynı ekrandadır.

Inspector ile Adım Adım

--debug testi görünür tarayıcıda başlatır ve Playwright Inspector'ı açar. Her eylemden önce durur; adım adım ilerler, locator'ı canlı düzenler ve hangi elementlere uyduğunu görürsünüz.²

$ pnpm dlx playwright test tests/orders.spec.ts:13 --debug

Dosya adından sonraki :13 yalnızca o satırdaki testi çalıştırır. Testin belirli bir yerinde durmak için koda await page.pause() ekleyin. VS Code eklentisi aynı şeyi kesme noktalarıyla yapar.²

Inspector'daki actionability log bir eylemin neden beklediğini söyler: "element is not visible", "element is not enabled", "another element would receive the click" gibi (bkz. Assertion ve bekleme).²

Trace Nedir?

Trace, bir test çalıştırmasının tam kaydıdır: her eylem, öncesi ve sonrasındaki DOM, ağ istekleri, konsol mesajları, kaynak kod satırı. CI'da düşen bir testi kendi makinenizde yeniden çalıştırmadan incelemenizi sağlar. Playwright dokümanı CI hataları için video ve ekran görüntüsü yerine trace önerir.³

Trace Kaydetmek

use.trace hangi çalıştırmada trace kaydedileceğini belirler:⁴

Oluşturulan yapılandırma "on-first-retry" kullanır. CI'da retries: 2 olduğu için düşen test bir kez daha çalışır ve o çalıştırma kaydedilir. Doküman "on"'u her test için önermez; trace kaydetmek testleri yavaşlatır.³

$ pnpm dlx playwright test --trace on

Trace'ler HTML rapordan açılır ya da doğrudan:⁵

$ pnpm dlx playwright show-trace test-results/orders-duruma-göre-filtreler-chromium/trace.zip

trace.playwright.dev aynı görüntüleyicinin web sürümüdür. Dosyayı sürükleyip bırakırsınız; trace tamamen tarayıcınızda açılır, hiçbir yere gönderilmez.⁵

Trace Viewer'da Neye Bakılır?

Snapshot'lar ekran görüntüsü değil, DOM kopyasıdır. Geliştirici araçlarıyla inceleyebilir, locator deneyebilirsiniz.⁵

Playwright 1.63 ile trace'e aria snapshot ve ekran görüntüsü de eklenebilir. "Display Aria" modu ekran görüntüsünü ve erişilebilirlik ağacını yan yana gösterir:⁶

use: {
  trace: {
    mode: "retain-on-failure",
    snapshots: { dom: true, aria: true, screen: true },
  },
},

Kendi Adımlarınız

Uzun testlerde test.step raporu ve trace'i okunur kılar. Adımlar raporda ve Trace Viewer'da başlıklarıyla görünür.⁷

test("yönetici siparişi iptal eder", async ({ loginPage, ordersPage }) => {
  await test.step("giriş yap", async () => {
    await loginPage.goto();
    await loginPage.login("yonetici@example.com");
  });

  await test.step("SP-1001'i iptal et", async () => {
    await ordersPage.cancel("SP-1001");
  });
});

Kırılgan Testi Yakalamak

Bazen düşen, bazen geçen teste kırılgan (flaky) denir. Bir kez çalıştırarak yakalanmaz. İki seçenek işe yarar:⁸⁹

$ pnpm dlx playwright test --repeat-each=10

$ pnpm dlx playwright test --shuffle

--repeat-each her testi N kez çalıştırır; zamanlamaya bağlı hatalar ortaya çıkar. --shuffle (1.64) testleri rastgele sırayla çalıştırır ve birbirine gizlice bağımlı testleri bulur. Çıktıdaki tohum değerini --shuffle 271828182 gibi verip aynı sırayı tekrar üretebilirsiniz.⁹

Bu rehberin projesinde --shuffle --repeat-each=3 --workers=4 bir testi düşürdü: önceki bir beforeEach sayfayı /orders'a yönlendirirken test /login'e gidiyordu ve iki gezinme çakışıyordu. Hata yalnızca belirli bir sırada çıkıyordu. Düzeltme, veriyi değiştiren testi ortak beforeEach'i olmayan kendi dosyasına taşımaktı.

Son düşen testleri tekrar çalıştırmak için:⁸

$ pnpm dlx playwright test --last-failed

Kendin Dene

• Bir assertion'ı bilerek yanlış yazın. Call log'u okuyun, sonra error-context.md dosyasını açın.

• npx playwright test --trace on ile çalıştırın, raporu açıp bir testin trace'ine girin. Network sekmesinde /api/orders isteğinin yanıtını bulun.

• Bir teste await page.pause() ekleyip --headed ile çalıştırın. Inspector'da locator'ı değiştirip hangi elementlere uyduğuna bakın.

• Test paketinizi --shuffle --repeat-each=5 ile çalıştırın. Düşen test var mı?

Detaylı Öğrenmek İçin

• Resmi doküman: Playwright, "Trace viewer"; trace kaydetme, açma ve tüm sekmeler.⁵

• Resmi doküman: Playwright, "Debugging Tests"; Inspector, VS Code ve ayrıntılı API logları.²

• Resmi doküman: Playwright, "UI Mode"; izleme modu ve zaman çizelgesi.¹