Arca E2E — profil-tabanlı, AI-destekli Playwright test motoru

Tek bir projeye bağlı değildir: proje (projects/<ad>/) ile hedef seçilir (E2E_PROFILE env). Proje-özgü HER ŞEY — profil, SRS dokümanı, sırlar (.env), üretilen senaryolar/spec'ler, oturumlar, koşum artefaktları — projects/<ad>/ altında tamamen izoledir; proje silmek/taşımak = tek klasör. Bir SRS dokümanından senaryo çıkarır, deployed uygulamaya karşı Playwright spec'leri üretir, koşar ve triyaj yapar. Tüm AI çağrıları kurulu Claude Code'u (claude -p subprocess) kullanır — ayrı API key gerekmez.

Başka bir makinede çalıştırma (tek komut)

Her şey yerelde çalışır: dosyalar/projeler senin diskinde kalır, LLM senin kendi Claude Code'unda koşar. Hiçbir kod/sır uzak bir sunucuya gitmez.

Önkoşullar (bir kez):

1. Node.js 18+ — https://nodejs.org
2. Claude Code — https://claude.com/claude-code kur, sonra claude login (üretim/triyaj bunu kullanır). Playwright tarayıcıları ilk çalıştırmada otomatik iner (~150 MB Chromium, açık internet ister — kurumsal proxy/firewall arkasında veya çevrimdışı makinede başarısız olur; o durumda elle: npx playwright install chromium).
3. (opsiyonel) PDF SRS — yalnız PDF dokümandan senaryo çıkaracaksan pdftotext (poppler) veya python + pdfminer.six gerekir. Word (.docx) Windows'ta yerleşik PowerShell ile okunur, ek araç gerekmez.

Çalıştır:

# A) Depoyu klonlayıp:
npm install
npm start            # ortam kontrolü (doctor) → server → tarayıcı http://localhost:5599

# B) (yayınlandığında) klonsuz tek komut:
npx arca-e2e

Açılışta bir doctor Node/Claude Code/Playwright'ı kontrol eder; eksikse ne yapacağını söyler. Claude Code kurulu değilse UI yine açılır (hazır örnekleri gezebilirsin), yalnız üretim/triyaj adımları beklemede kalır. Doğrudan motor (doctor'sız): node gui/server.mjs.

Hızlı başlangıç

# Rol creds'leri projects/<ad>/.env'de (GUI sihirbazı anahtarlarıyla iskeleti üretir, sen doldurursun).
# Motor seviyesi bayraklar (HEADLESS=1, APP_URL/API_URL override, SURVEY_MODEL...) kabuktan
# ya da istersen opsiyonel kök .env'den verilir (öncelik: kabuk > proje > kök).
npm install
npx playwright install chromium

# Profil seç (default: template). Örn. template'i SRS'inden test eden profil:
$env:E2E_PROFILE = "tmpl-srs"

# 1) SRS'ten senaryo çıkar (yalnız srsDoc tanımlı profilde)
npm run srs all                       # SRS → projects/<profil>/generated/_scenarios/sf-*.md + _index.md

# 2) Bu senaryolardan test üret + koştur + triyaj
npm run conformance sf-tenants 5      # SRS + kod-aware
npm run blackbox    sf-tenants 5      # SRS + kaynak-kör DOM

# GUI (tüm modlar + profil editörü + SRS çıkarma):
npm run gui                           # http://localhost:5599

Beş mod (oracle kaynağına göre)

| Mod | Komut | Oracle | Ne zaman | Kılavuz | |-----|-------|--------|----------|---------| | srs | npm run srs <feature\|all> | — (SRS'ten üretir) | Elde sadece SRS var, senaryo yok (yeni proje bootstrap) | guide/SRS-GUIDE.md | | conformance | npm run conformance <feature> [N] | SRS + kod | Şartname + kaynak erişimi var | guide/CONFORMANCE-GUIDE.md | | blackbox | npm run blackbox <feature> [N] | SRS (kaynak-kör) | SRS var, kaynak paylaşılmadı | guide/BLACKBOX-GUIDE.md | | survey | npm run survey <alan> [N] | Sitenin kendisi | SRS yok, sadece URL+kimlik | guide/SURVEY-GUIDE.md | | pwagents | npm run pwagents <alan> | Plan (Playwright Agents) | Resmî planner→generator→healer akışı | guide/PWAGENTS-GUIDE.md |

srs diğerlerinin TERSİ: conformance/blackbox docs/scenarios/*.md'yi okur; srs onları yazar. Akış: SRS dokümanı → /srs → senaryolar → /conformance veya /blackbox → testler.

Yetenek katmanları (proje neye sahipse o modlar açılır — GUI kullanılamayanı soluklaştırır): kod + SRS → hepsi · yalnız SRS (repo.rootRelToE2e: null) → srs/blackbox + survey/pwagents · yalnız URL → survey/pwagents. Code-aware modlar kod tabanı olmayan profilde dostça hata verip çıkar. Profil türetme (🧬 npm run bootstrap): kod varsa koddan, yoksa SRS'ten; ikisi de yoksa ⚙ elle.

Projeler (projects/<ad>/)

Motorun proje-özgü TÜM verisi profilden gelir (URL/auth/rol/alan/UI/ID önekleri); kod proje-bağımsız. generator/profile.ts projects/<ad>/profile.json'u yükler, E2E_PROFILE env seçer. Klasör adı TEK proje anahtarıdır — project.name onunla aynı olmak zorundadır (yükleyici doğrular).

projects/<ad>/
├─ profile.json      # profil (URL/auth/rol/alan/UI)
├─ .env              # proje sırları (rol creds) — kök .env'i ezer, gitignore'lu
├─ srs/              # SRS dokümanı (docs.srsDoc buna relatif: "srs/SRS.md")
├─ generated/        # _scenarios oracle + mod-başına spec/rapor/çalışma dizinleri
├─ specs/            # pwagents plan dosyaları
├─ _auth/            # oturum state'leri (gitignore)
├─ test-results/     # playwright koşum artefaktları (gitignore)
└─ report/           # playwright HTML raporu (gitignore)

Örnek: tmpl-srs — template'in SRS'ini (docs.srsDoc: "srs/SRS.md") + canlı app'ini kullanır; senaryolar SRS'ten çıkarılır (scenarioSource: "extracted").

Yeni proje (Evo2 vb.): GUI ＋ sihirbazı kullan; ya da elle projects/<ad>/profile.json + projects/<ad>/srs/<dosya> koy, docs.srsDoc+scenarioSource:"extracted" ayarla → npm run srs all.

GUI (npm run gui)

Sıfır-bağımlılık yerel panel (yalnız 127.0.0.1'e bind). Tüm modları spawn eder, canlı log + slot panelleri + raporu gösterir. ⛏ SRS çıkar (profilde srsDoc varsa) ve ⚙ Profil görüntüle/düzenle butonları; model PIN düzenleyici (models.json). Sol explorer: senaryo başına ▶ çalıştır / ✎ düzelt / 🔍 kaynak / 📋 senaryo.

Determinizm + güvenlik

• Model PIN'li (generator/models.json, gen/run/primer/explore rolleri) — model değişimi oracle sözleşmesi değişimidir; npm run golden check ile drift doğrula.
• Çıktı izolasyonu: projects/<profil>/... (çok-proje çakışmaz; çıplak npx playwright test bile yalnız aktif projenin spec'lerini toplar). Oracle = _scenarios/*.md+_index.md (git'e commit); koşum artefaktları (_LIVE.log/_state.json/*-REPORT.md/_srs-source.md) gitignore'lu.
• srs ajanları --allowedTools Read,Write,Edit,Glob,Grep ile koşar (Bash yok → yazma blast-radius'u sınırlı).
• Uyarı: conformance/blackbox toplu koşum, profil creds'iyle canlı uygulamaya gider; mutasyon-senaryoları prod veriyi değiştirebilir → staging tercih et.

Yapı (motor ↔ proje ayrımı)

projects/<ad>/            # PROJE-ÖZGÜ her şey (profil, .env, srs, generated, _auth, test-results, report)
generator/                # üretici CLI'lar: profile.ts, models.ts, srs.ts, conformance.ts, blackbox.ts, survey.ts, pwagents.ts, cli.ts, analyze.ts, golden.ts, bootstrap.ts
generator/lib/            # ortak çekirdek: agent.ts (tek headless-Claude çağrısı — spawn/timeout/kill/stream-parse)
runtime/                  # testlerin koşum anında import ettiği kod: auth.ts, seed.spec.ts, blackbox/{discover,fixtures}, survey/{crawl,fixtures}
gui/                      # server.mjs + index.html (yerel panel)
guide/                    # her modun kılavuzu (*-GUIDE.md)
.claude/skills/srs/       # /srs skill (diğer mod skill'leri henüz template'te)

Captcha (template profili)

Login formu Turnstile gösterir ama deployed backend'de captcha API-seviyesinde devre dışı (test-mode); spec'ler loginViaApi/loginAndGoTo ile API üzerinden auth olur, forma dokunmaz. Doğrula: curl -X POST https://apitemplate.arcacloud.com.tr/api/auth/login -H "Content-Type: application/json" -d '{"emailOrUserName":"x","password":"y"}' → {"errorMessage":"..."} (captcha aktif olsa Auth.CaptchaRequired dönerdi).