Erişilebilirlik ve görsel testler

Üç Farklı Soru

Bu derste üç tür test var ve her biri farklı bir soruya cevap verir:

axe ile Tarama

axe-core motoru ve AxeBuilder Erişilebilirlik testi dersinde ayrıntılı anlatılıyor. Playwright tarafında kalıp kısadır:¹

$ pnpm add -D @axe-core/playwright

// tests/accessibility.spec.ts
import AxeBuilder from "@axe-core/playwright";
import { expect, test } from "./fixtures";

test("siparişler sayfasında erişilebilirlik ihlali yok", async ({ page, ordersPage }) => {
  await ordersPage.goto();
  await expect(ordersPage.rows).toHaveCount(6);

  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});

Taramadan önce sayfanın hazır olduğunu bekleyin. Liste yüklenmeden tararsanız yalnızca "yükleniyor" yazısını taramış olursunuz.

JSDOM'da çalışmayan renk kontrastı kuralı gerçek tarayıcıda çalışır; uçtan uca taramanın en büyük kazancı budur. Yine de Playwright dokümanının uyarısı nettir: otomatik testler yalnızca bazı yaygın sorunları bulur, birçok sorun ancak elle ve gerçek kullanıcılarla test edilerek ortaya çıkar.¹

Klavye ile Gezinme

axe'ın göremediği şeylerden biri akıştır: klavyeyle formu doldurup gönderebiliyor musunuz, odak doğru yere gidiyor mu? Bunu kullanıcı gibi test edin:

test("giriş formu klavyeyle kullanılabilir", async ({ page, loginPage }) => {
  await loginPage.goto();

  await loginPage.email.focus();
  await page.keyboard.type("yonetici@example.com");
  await page.keyboard.press("Tab");
  await expect(loginPage.password).toBeFocused();

  await page.keyboard.type("parola123");
  await page.keyboard.press("Enter");
  await expect(page).toHaveURL("/orders");
});

toBeFocused ve keyboard.press ile hata sonrası odağın ilk hatalı alana gittiğini de doğrulayabilirsiniz (bkz. Hata gösterimi ve erişilebilirlik).

Aria Snapshot

Aria snapshot, bir elementin erişilebilirlik ağacının YAML ile yazılmış halidir: roller, erişilebilir adlar, durumlar ve hiyerarşi. Ekran okuyucunun sayfayı nasıl gördüğünü tek bakışta gösterir.²

test("tablo yapısı beklenen gibi", async ({ ordersPage }) => {
  await ordersPage.goto();
  await ordersPage.filterBy("Teslim edildi");

  await expect(ordersPage.table).toMatchAriaSnapshot(`
    - table "Sipariş listesi":
      - rowgroup:
        - row "Sipariş Müşteri Tutar Durum İşlem"
      - rowgroup:
        - row /SP-1003 Zeynep Demir/:
          - cell "SP-1003"
          - cell "Zeynep Demir"
          - cell /2\\.150,00/
          - cell "Teslim edildi"
          - cell
  `);
});

Bu tek assertion tablonun bir başlığı olduğunu, sütunların sırasını, tek satır kaldığını ve her hücrenin içeriğini doğrular. Aynı şeyi toHaveText ile yazmak bir düzine satır tutardı.

Eşleştirme kuralları:²

• Şablon kısmi eşleşir: bir listenin yalnızca bazı elemanlarını yazarsanız diğerleri yok sayılır. Tam eşleşme için /children: equal kullanılır.

• Adlar /…/ arasında düzenli ifade olabilir. Para birimi gibi biçimi değişebilen değerler için idealdir. Şablon bir JavaScript dizesi olduğu için ters eğik çizgiyi iki kez yazın: /2\\.150,00/.

• Bir özelliği (checked, disabled) yazmazsanız o özellik kontrol edilmez.

Şablonu elle yazmak zorunda değilsiniz. Boş bir şablonla başlayın; Playwright ilk çalıştırmada üretir. Değişen yapıyı güncellemek için -u (--update-snapshots) kullanın; satır içi şablonlar için uygulanabilir bir yama dosyası oluşturulur:²

await expect(ordersPage.table).toMatchAriaSnapshot("");

$ pnpm dlx playwright test --update-snapshots

Aria snapshot ve assertion birbirinin yerine geçmez. Doküman ikisini birlikte önerir: yapı için snapshot, belirli bir değer ya da davranış için assertion.²

Görsel Karşılaştırma

toHaveScreenshot sayfanın ya da bir elementin ekran görüntüsünü alır ve kayıtlı referans görüntüyle piksel piksel karşılaştırır:³

// tests/orders.visual.ts
import { expect, test } from "./fixtures";

test("sipariş tablosu görünümü", async ({ ordersPage }) => {
  await ordersPage.goto();
  await expect(ordersPage.rows).toHaveCount(6);

  await expect(ordersPage.table).toHaveScreenshot("orders-table.png");
});

İlk çalıştırmada referans yoktur. Varsayılan modda Playwright görüntüyü yazar ama testi başarısız sayar; böylece yeni bir snapshot sessizce kabul edilmez. Playwright 1.64 ile --update-snapshots=missing eksik görüntüleri yazar ve testi geçirir; CI'ın yeni görüntüleri üretip mevcutları tek çalıştırmada doğrulaması için tasarlanmıştır.⁴

Referans dosyanın adı tarayıcıyı ve işletim sistemini içerir: orders-table-visual-linux.png. Yazı tipi ve çizim farkları yüzünden macOS'ta alınan görüntü Linux'takiyle eşleşmez. Doküman tutarlı sonuç için testleri referansın üretildiği ortamda çalıştırmayı söyler.³ Bu yüzden referansları CI'da ya da Playwright'ın resmi Docker imajında üretin; herkes aynı ortamı kullanmış olur.⁵

Kırılganlığı azaltan ayarlar:³

await expect(page).toHaveScreenshot({
  mask: [page.getByText(/Son güncelleme/)],
  maxDiffPixels: 100,
});

Görsel Testleri Ayrı Projede Tutmak

Görsel testler yavaştır ve platforma bağlıdır. Her npm test'te çalışmaları gerekmez. Playwright 1.64'teki default: false ile onları ayrı bir projede tutun:⁴

// playwright.config.ts
projects: [
  { name: "setup", testMatch: /.*\.setup\.ts/ },
  {
    name: "chromium",
    testIgnore: /.*\.visual\.ts/,
    use: { ...devices["Desktop Chrome"], storageState: "playwright/.auth/admin.json" },
    dependencies: ["setup"],
  },
  {
    name: "visual",
    testMatch: /.*\.visual\.ts/,
    use: { ...devices["Desktop Chrome"], storageState: "playwright/.auth/admin.json" },
    dependencies: ["setup"],
    default: false,
  },
],

$ pnpm dlx playwright test --project=visual --update-snapshots=missing

$ pnpm dlx playwright test --project=visual

Görsel test dosyalarının .visual.ts ile bitmesi, onları normal projeden testIgnore ile ayırmayı kolaylaştırır.

Hangisini Ne Zaman?

Kendin Dene

• Projenizdeki her sayfa için bir axe testi yazın. Bir butonun adını silip testin ne raporladığına bakın.

• Bir tabloya boş bir toMatchAriaSnapshot("") ekleyin ve Playwright'ın ürettiği şablonu okuyun. Bir hücreyi düzenli ifadeye çevirin.

• Görsel test için ayrı bir proje kurun, referansı --update-snapshots=missing ile oluşturun. Bir rengi değiştirip farkı HTML raporunda inceleyin.

• Giriş formunu yalnızca klavyeyle dolduran bir test yazın.

Detaylı Öğrenmek İçin

• Resmi doküman: Playwright, "Snapshot testing"; aria snapshot söz dizimi, kısmi ve tam eşleşme, güncelleme modları.²

• Resmi doküman: Playwright, "Visual comparisons"; referans görüntüler, platform adlandırması ve seçenekler.³

• Resmi doküman: Playwright, "Accessibility testing"; axe ile tarama ve otomatik testin sınırları.¹