Dokümantasyon browser testleri

Browser suite, doğrulanmış production dokümantasyon build’ini loopback üzerinde bir kez ayağa kaldırır ve bütün authored rotaları tek Chromium projesinde denetler.

Yerel çalışma

İlk kullanımda pinned Chromium binary’sini kurun:

make docs-browser-install

Ardından browser kalite kapısını çalıştırın:

make docs-browser-check

Normal make bootstrap browser indirmez. Bu ayrım, browser testi yapmayan veri ve backend katkılarının kurulumunu gereksiz yere ağırlaştırmaz.

Kapsam

Suite şu davranışları doğrular:

• authored kullanıcı, geliştirici ve proje sayfalarında WCAG 2 A/AA axe audit,
• skip link, release ayrıntısı, mobile menü ve tema seçicisinin klavye erişimi,
• desktop sidebar ve başlangıçta kapalı mobile navigation,
• 1440 px ve 390 px viewportlarda yatay sayfa taşmasının olmaması,
• sistem dark/light tercihi, görünür yüzey farkı ve manuel seçimin kalıcılığı.

Cross-platform font rasterization stabil bir ürün sözleşmesi olmadığı için golden pixel snapshot commit edilmez. Playwright yalnız hata halinde screenshot ve trace üretir; CI bunları docs-browser-failure-<run-id> artifact’ı olarak yedi gün saklar.

CI

Documentation browser quality job’ı locked JavaScript ortamını kurar, yalnız Chromium’u resmi Playwright installer ile yükler ve aynı make docs-browser-check hedefini çalıştırır. Browser suite DB, Supabase, Cloudflare credential’ı veya dış network servisi kullanmaz.

Web/docs entegrasyonu

Uygulamaların ayrıntılı browser suite’leri ayrı kalır. Sınır davranışı için tek odaklı senaryo fixture API, production Next reader ve production static docs sunucusunu birlikte başlatır:

pnpm --filter @munderecat/web exec playwright test \
  --config playwright.web-docs.config.mjs

Test contextual user-guide linkine Tab ile ulaşıp Enter ile açar, docs sayfasındaki dönüş linkiyle aynı chapter’a döner, dark/light semantic tokenların gerçek body/brand renklerine bağlandığını karşılaştırır ve iki tarafta WCAG A/AA axe audit çalıştırır. Aynı senaryo 390 px menüsündeki dönüş linkinin görünür ve klavyeyle erişilebilir olduğunu da doğrular; ayrı negatif senaryo dış referrer ile reader dışı path’i reddeder. Bu test, web veya docs suite’inin tamamını ikinci kez çalıştırmaz.

Sorun giderme

• Browser executable yok: make docs-browser-install komutunu yeniden çalıştırın.
• Port 4322 kullanımda: ilgili yerel süreci kapatın; suite mevcut sunucuyu tekrar kullanmaz.
• Axe ihlali: hata çıktısındaki rule ID ve hedef selector ile authored bileşeni veya Starlight override’ını düzeltin; genel rule kapatmayın.
• Responsive taşma: rapordaki route/viewport bilgisini kullanın ve sayfa seviyesinde değil taşan bileşenin kendi scroll sınırını düzeltin.
• CI browser hatası: failure artifact’ındaki trace’i Playwright trace viewer ile açın; secret veya provider logu bu artifact’a girmez.