Sweeper (site taraması)

Sweeper sitenizi gerçek bir tarayıcıda (Chromium) sayfa sayfa açar ve linklerini izler (crawl). Her sayfada şunları kaydeder:

• status ile TTFB, yüklenme ve LCP süreleri,
• console hataları ve yakalanmamış exception'lar,
• başarısız istekler (4xx/5xx dönen ya da yüklenmeyen script, görsel, stil ya da XHR),
• kırık linkler (sayfadaki, hataya giden link),
• boş sayfalar (yüklendi ama görünen bir şey yok) ve yavaş sayfalar (taramanın sınırından yavaş).

#Ne yapmaz

• Read modunda (varsayılan) sayfaları açmak için yalnızca GET isteği yapar (istenirse başka sitelere giden linklere HEAD ya da GET). Form doldurmaz, hiçbir şeye tıklamaz, bir şey göndermez. Interactive mode ise tıklar, doldurur ve gönderir; yalnızca staging'de.
• Logout benzeri yollar (/logout, /signout, /cikis, …) her zaman atlanır; böylece oturum cookie'siyle yapılan tarama oturumda kalır.
• Başka siteleri crawl etmez: yalnızca başlangıç adresinin host'unu ve yazdığınız ek host'ları.

#Runner gereksinimi

Tarama tarayıcılı bir runner'da koşar: usespitfire/spitfire:<sürüm>-browser imajı; bu runner kendini browser: chromium etiketiyle bildirir. Her runner aynı anda bir tarama alır.

Tarayıcılı runner yoksa Sweeper sayfası uyarı gösterir ve Başlat kapalı kalır; API ve CLI no_sweep_runner yanıtı verir. Eklemek için:

1. Runner'lar sayfasını açın, Token oluştur'a tıklayın.
2. Docker sekmesinde Tarayıcı adımları için kutusunu işaretleyin.
3. Komutu kopyalayıp runner olacak makinede çalıştırın.
4. Kontrol: runner, Runner'lar sayfasında browser etiketiyle görünür; Sweeper sayfası "1 tarayıcılı runner bağlı" der.

#Tarama oluşturma

1. Menüden Sweeper'ı açın, Yeni tarama'ya tıklayın.
2. Ad (ör. Magaza) ve Başlangıç adresi (ör. https://magaza.example.com/) yazın.
3. Gerisini olduğu gibi bırakın ya da En fazla sayfa, En fazla derinlik, Aynı anda sayfa (1–4) ve Yavaş sayfa sınırını ayarlayın.
4. Oturum gerektiren sayfalar için Header'lar (Authorization: Bearer …) ya da Cookie girin. Şifreli saklanır ve yalnızca taramanın kendi host'larına gider.
5. Geçti / geçmedi altında En fazla hata'yı (0: tek hata bile geçirmez) ve yavaş sayfalar da koşuyu düşürsün istiyorsanız En fazla yavaş sayfa'yı ayarlayın.
6. Kaydet'e, sonra taramanın satırında Başlat'a tıklayın.
7. Kontrol: koşu sayfası açılır ve sayfa sayısı artar; sonunda rozet geçti ya da geçmedi der.

Hata, yavaş sayfalar dışındaki her bulgudur. Yalnızca bu yollar ve Bu yolları atla satır başına bir kalıp alır; * her şeyi tutar (/blog/*, */print*), * içermeyen kalıp önektir.

#Koşuyu okuma

• Üstteki kartlar sayfaları ve her bulgu türünü sayar; bir karta tıklayınca yalnızca o tür gösterilir.
• Tablo en az bir bulgusu olan sayfaları listeler: adres, ona link veren sayfa, status, TTFB, yüklenme süresi, LCP ve her bulgu ayrıntısıyla.
• Koşu geçmediyse nedeni rozetin altında yazar (ör. 3 errors > 0).
• Durdur süren taramayı bitirir; o ana kadar bulunanlar kalır.

#Interactive mode

Interactive mode her sayfadakileri de dener; release'i elle kontrol eden biri gibi: butonlar, menü öğeleri, tab'lar, checkbox ve radio'lar, select'ler (başka bir seçeneğe geçip geri döner) ve formlar (form değerlerinizle doldurulup gönderilir). Her etkileşimden sonra yeni bir console hatası ya da exception, sweep host'larından gelen 4xx/5xx, boş ekran ve elemana ulaşmayan tıklama arar. Her sorun bir Etkileşim başarısız bulgusudur: elemanın etiketi ve selector'ı, yapılan işlem (click, select, submit), sonuç (POST /api/cart → 500, TypeError: …) ve alınabildiyse ekran görüntüsü.

Tıklar, doldurur ve gönderir; bu yüzden yalnızca staging ya da test ortamında çalıştırın.

Güvenliği şunlar sağlar:

• Yalnızca sweep'in host'ları. Başka bir host'a giden her istek (ödeme sağlayıcı, e-posta servisi, analytics post'u) ve her sign-out isteği tarayıcıda durdurulur, koşuda dışarı gitmedi olarak listelenir. Başka host'lardan gelen görsel, script ve stiller yine yüklenir; sayfalar doğru görünür.
• Skip listesi. Metni, aria-label'ı, title'ı ya da ikon class'ı bir satırla eşleşen öğeye hiç tıklanmaz. Varsayılan liste silen, iptal eden, başlatan ya da durduran, ödeme yapan, sipariş veren ya da gönderen öğelerle gelir (pay, öde, satın al, checkout, place order, subscribe, send, gönder, …); denensin istediğiniz satırı silin. Çıkış butonlarına ve kırmızı (danger) butonlara hiç tıklanmaz.
• Gönderimden sonra 400 ve 422 sorun değildir: formun kendi doğrulaması cevap veriyordur. 5xx bulgudur.
• Onay pencereleri kapatılır (İptal), indirmeler ve yeni pencereler açılmaz.
• Staging onayı. Interactive bir sweep kaydedilirken host'ları için "… bir staging ya da test ortamıdır" kutusu işaretlenir. Kimin, ne zaman işaretlediği sweep'te saklanır; host'lar aynı kaldıkça onay geçerlidir.
• Asla canlı site. Bir testin prod, production, live, canli gibi adlı bir ortamı (Ortamlar) host'lardan birini gösteriyorsa sweep interactive modda kaydedilemez ve başlatılamaz. Bu, zamanlananlar dahil her başlatmada yeniden kontrol edilir. www. host'u için, bir staging ya da test ortamı onu göstermiyorsa ikinci bir kutu ("… canlı site değildir") gerekir.
• Her interactive başlatma audit log'a düşer (sweep.interactive_start, kim ve hangi host'lar).

#Kurulum

1. Sweep'i (ya da Yeni tarama'yı) açın, Mod altında Interactive (yalnızca staging) seçin.
2. … bir staging ya da test ortamıdır kutusunu (www. host'u için … canlı site değildir kutusunu da) işaretleyin.
3. Neler denensin altında denenmemesi gerekenlerin işaretini kaldırın.
4. Asla tıklanmasın (skip listesi) alanına bakın: her satırda bir kelime, ifade ya da CSS selector (#buy, .danger).
5. Form değerleri'ni satır satır yazın: eşleşme = değer. Eşleşme alanın name, id, label, placeholder ya da input type'ı veya bir CSS selector'dır (email = test@example.com, #qty = 2). Hiçbir satırın adlandırmadığı alanlar olduğu gibi gönderilir.
6. Gerekirse Sayfa başına etkileşim ve Etkileşim başına bekleme (ms) değerlerini ayarlayın, Kaydet'e basın.
7. Kontrol: sweep satırında Interactive (yalnızca staging) rozeti var; koşudan sonra koşu sayfasında denenen, başarısız ve atlanan sayıları ile dışarı gitmeyen istekleri gösteren Etkileşimler kartı var.

Etkileşim hataları hata sayılır; geçti/kaldı kararını diğer bulgulardaki gibi En fazla hata verir. spitfire cloud sweep aynı komuttur, çıkış kodları da aynıdır; mod sweep'ten gelir.

#GitHub Actions'ta staging kapısı

Staging'e deploy edin, interactive olarak tarayın, tarama geçerse production'a deploy edin. Buradaki sweep (Shop staging) staging adresinde interactive bir sweep'tir.

# .github/workflows/release.yml
on:
  push:
    branches: [main]
jobs:
  staging:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh staging          # sizin staging deploy'unuz
  sweep:
    needs: staging
    runs-on: ubuntu-latest
    steps:
      - env:
          SPITFIRE_URL: https://spitfire.example.com
          SPITFIRE_TOKEN: ${{ secrets.SPITFIRE_TOKEN }}
        run: docker run --rm -e SPITFIRE_URL -e SPITFIRE_TOKEN usespitfire/spitfire spitfire cloud sweep "Shop staging" --timeout 30m
  production:
    needs: sweep                          # yalnızca tarama geçtiyse (çıkış kodu 0) çalışır
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh production       # sizin production deploy'unuz

Kontrol: sweep job'unun logu sweep Shop staging: passed — … ve interactions: … tried, … failed satırıyla biter; geçmeyen tarama (çıkış kodu 99) production job'unu durdurur.

#CI'dan tarama

Tarama geçmezse komut işi düşürür (çıkış kodu 99); böylece kırık bir link ya da console hatası deploy'u durdurabilir. Her klasörden çalışır; SPITFIRE_URL ve SPITFIRE_TOKEN, CI/CD sayfasındakiyle aynı değişkenlerdir.

1. Taramayı arayüzde oluşturun (yukarıda) ve adını not edin, ör. Magaza.

2. Bir API token'ını CI'ın gizli değişkeni SPITFIRE_TOKEN'a koyun.

3. İşe şu adımı ekleyin (Docker, indirme yok):

   bashKopyala

   docker run --rm -e SPITFIRE_URL -e SPITFIRE_TOKEN usespitfire/spitfire spitfire cloud sweep "Magaza"

   Ya da CI/CD sayfasındaki CLI kuruluysa:

   bashKopyala

   spitfire cloud sweep "Magaza" --timeout 30m -o "${RUNNER_TEMP:-/tmp}/sweep.json"

4. Kontrol: işin logu sweep Magaza: passed — … pages, 0 errors … satırı ve koşunun linkiyle biter; iş yeşildir.

Çıkış kodları: 0 geçti, 99 eşikler aşıldı (izin verilenden fazla hata ya da yavaş sayfa), 1 başka bir hata (tarayıcılı runner yok, yanlış token, olmayan tarama).

Aynısı REST API ile (API referansı Spitfire'da: /api/docs, Sweeper etiketi):

curl -fsS -X POST -H "Authorization: Bearer $SPITFIRE_TOKEN" "$SPITFIRE_URL/api/v1/sweeps/Magaza/start?trigger=ci"

Yanıt koşunun kendisidir; done true olana kadar GET /api/v1/sweep-runs/{id} isteyin, sonra passed'a bakın.

#Zamanlama ve bildirimler

• Sweeper modülüyle tarama bir cron zamanlamasıyla koşabilir (pencerede Zamanlama, ör. 0 3 * * * = her gün 03:00).
• Geçmeyen (ya da koşamayan) bir koşu, sweep.failed olayına abone bildirim kanallarına gider: Entegrasyonlar'da bir Slack, Teams, e-posta ya da webhook kanalını düzenleyip işaretleyin (bkz. bildirim kanalları). Varsayılan olarak kapalıdır; SMS'e ve iş takibine gitmez.

#Lisans

Modül Enterprise planıyla ya da herhangi bir sürüme ek modül olarak gelir. Kurulum yöneticisi Sweeper ya da Lisans sayfasından 7 gün boyunca bir kez deneyebilir.

#Sık sorunlar

• "Şu an boşta, tarayıcılı runner yok": -browser imajından bir runner bağlayın (bkz. Runner gereksinimi) ya da süren taramanın bitmesini bekleyin.
• Her sayfa 401/403: oturum yok; pencerede header ya da cookie ekleyin.
• Başlatırken "interactive_not_allowed": bir testin production ortamı artık host'lardan birini gösteriyor ya da staging onayından sonra host'lar değişti. Sweep'i açın, adrese bakın, staging kutusunu işaretleyip kaydedin.
• Interactive koşu bir sayfada hiçbir şey denemedi: sayfadaki öğelerin hepsi skip listesinde, gizli ya da Sayfa başına etkileşim sınırının üstünde; Etkileşimler kartı neyin neden atlandığını listeler.
• Çok az sayfa: En fazla derinlik'i ya da En fazla sayfa'yı artırın, Yalnızca bu yollar'a bakın; modül yokken koşu 50 sayfada durur.