--- name: saas-testing description: > SaaS uygulaması için test stratejisi kur. Vitest ile birim test, Playwright ile E2E test, API route testi, webhook mock, Stripe test modu ve CI entegrasyonu. Bu skill'i kullanıcı test, test yazma, E2E, birim test, Playwright, Vitest, coverage veya kalite güvencesi ile ilgili bir şey istediğinde kullan. "Test yaz", "test kur", "E2E ekle", "CI'da test çalıştır" gibi ifadeler tetikler. --- # SaaS Testing — Test Stratejisi ve Kalite Güvencesi Bu skill, bir SaaS uygulamasının test altyapısını kurar. Test olmadan "production-ready" iddiası eksiktir — ödeme webhook'unun çalıştığını, auth akışının kırılmadığını ve API'nin beklendiği gibi davrandığını sadece testlerle garanti edebilirsin. **Bağımlılık:** Bu skill **saas-launcher** orkestratör skill'inin Deployment öncesi kalite güvence adımıdır. Bağımsız olarak da kullanılabilir. **Bağlı skill'ler:** - **saas-auth** — Giriş/kayıt akışları E2E test edilir. - **saas-payments** — Webhook handler'lar ve checkout akışı test edilir. - **saas-api-security** — Rate limiting ve input validation testleri. --- ## Test Piramidi — SaaS İçin ### Hangi Test Türü Ne Zaman **Birim Test (Unit Test) — Vitest:** Tekil fonksiyonları ve utility'leri test eder. Hızlı çalışır, dış bağımlılık yok. Kullanım: fiyat hesaplama, plan kontrolü, input validation, helper fonksiyonlar. **Entegrasyon Test (Integration Test) — Vitest:** API route'larını test eder. HTTP isteği gönderir, yanıtı doğrular. Kullanım: auth endpoint'leri, checkout API, webhook handler. **Uçtan Uca Test (E2E Test) — Playwright:** Gerçek bir tarayıcıda kullanıcı akışlarını test eder. En yavaş ama en güvenilir. Kullanım: kayıt → giriş → plan satın al → dashboard erişimi. ### Başlangıç Önceliği Day 1'de her şeyi test etmeye çalışma. Öncelik sırası: 1. **Webhook handler testi** — Para alınıp plan aktifleşmezse gelir kaybı 2. **Auth akışı E2E testi** — Giriş yapılamazsa uygulama kullanılamaz 3. **Kritik API route testleri** — Plan kontrolü, kaynak oluşturma 4. **Input validation testleri** — Güvenlik katmanı --- ## Vitest Kurulumu ### Neden Vitest Jest'e alternatif, modern test runner. Avantajları: Vite tabanlı — çok hızlı, ESM desteği doğal, Jest uyumlu API (geçiş kolay), TypeScript desteği dahili, HMR ile watch mode. ### Kurulum ``` npm install -D vitest @vitejs/plugin-react ``` Proje kökünde `vitest.config.ts` oluştur. Test dosyaları için `__tests__/` klasörü veya dosya adında `.test.ts` / `.spec.ts` uzantısı kullan. `package.json`'a script ekle: - `"test": "vitest run"` — tek seferlik çalıştır - `"test:watch": "vitest"` — watch mode - `"test:coverage": "vitest run --coverage"` — coverage raporu ### API Route Testi Yaklaşımı Next.js API route'larını test etmek için route handler fonksiyonunu doğrudan import edip mock Request nesnesi ile çağır. Gerçek HTTP sunucusu ayağa kaldırmaya gerek yok. Her test: 1. Mock request oluştur (method, headers, body) 2. Route handler'ı çağır 3. Response status ve body'yi doğrula ### Webhook Handler Testi Webhook testleri en kritik testlerdir. Test stratejisi: 1. **İmza doğrulama testi:** Geçerli imza ile webhook'un işlendiğini, geçersiz imza ile reddedildiğini doğrula. 2. **Event işleme testi:** Her webhook event türü için veritabanı değişikliğini doğrula. Örnek: `checkout.session.completed` → kullanıcı planı "pro" olmalı. 3. **Idempotency testi:** Aynı event'i iki kez gönder, sonucun değişmediğini doğrula. **Stripe test modu:** Stripe CLI ile webhook'ları localhost'a yönlendir: ``` stripe listen --forward-to localhost:3000/api/stripe/webhook stripe trigger checkout.session.completed ``` ### Mock Stratejisi Dış servisleri mock'la, kendi kodunu mock'lama: - **Mock'lanması gerekenler:** Stripe API, Resend API, Supabase client (isteğe bağlı) - **Mock'lanmaması gerekenler:** Kendi utility fonksiyonların, validation şemaların — bunları gerçek çalıştır Vitest'in `vi.mock()` fonksiyonu ile modül seviyesinde mock: - Stripe SDK'yı mock'la — gerçek API çağrısı yapılmasın - Resend SDK'yı mock'la — test sırasında e-posta gönderilmesin --- ## Playwright E2E Kurulumu ### Neden Playwright Cypress'e alternatif, modern E2E test aracı. Avantajları: Çoklu tarayıcı desteği (Chromium, Firefox, WebKit), otomatik bekleme (auto-wait), trace viewer ile debugging, headless CI modu. ### Kurulum ``` npm install -D @playwright/test npx playwright install ``` `playwright.config.ts` oluştur. Temel ayarlar: - `baseURL`: `http://localhost:3000` - `webServer`: test öncesi dev server'ı otomatik başlat - `use.trace`: `on-first-retry` — sadece başarısız testlerde trace kaydet ### Temel E2E Senaryoları **Auth akışı:** 1. Landing page'e git 2. "Giriş Yap" butonuna tıkla 3. E-posta ile Magic Link giriş formunu doldur (veya test OAuth akışı) 4. Dashboard'a yönlendirildiğini doğrula 5. Korumalı sayfaya erişebildiğini doğrula **Checkout akışı:** 1. Giriş yap 2. Fiyatlandırma sayfasına git 3. Plan seç 4. Stripe Checkout'a yönlendirildiğini doğrula 5. (Test modunda ödeme yap) 6. Başarı sayfasına dönüşü doğrula **Landing page:** 1. Ana sayfanın yüklendiğini doğrula 2. Tüm bölümlerin render edildiğini doğrula 3. CTA butonlarının çalıştığını doğrula 4. Mobil görünümde navigasyonun çalıştığını doğrula ### Playwright İpuçları - **Test izolasyonu:** Her test bağımsız olmalı. Önceki testin state'ine bağımlı olma. - **Locator kullan, CSS selector değil:** `page.getByRole()`, `page.getByText()`, `page.getByTestId()` — CSS selector'lar kırılgan. - **Auto-wait'e güven:** `waitForTimeout()` kullanma — Playwright elementlerin görünmesini otomatik bekler. - **Screenshot on failure:** Başarısız testlerde otomatik screenshot al — CI'da debugging için. --- ## CI Entegrasyonu ### GitHub Actions ile Test CI pipeline'a test adımlarını ekle: 1. **Birim + entegrasyon testleri:** `vitest run` — her PR'da çalışmalı 2. **E2E testleri:** `npx playwright test` — her PR'da veya sadece main merge öncesinde 3. **Coverage raporu:** PR'a yorum olarak coverage değişimini göster ### CI'da Playwright Playwright CI'da headless modda çalışır. GitHub Actions'da `playwright install --with-deps` ile tarayıcı bağımlılıklarını kur. Başarısız testlerin trace'ini artifact olarak sakla — debugging için indir ve `npx playwright show-trace` ile aç. --- ## Test Coverage ### Hedefler - **Webhook handler: %100** — Burası para. Her event türü, her edge case test edilmeli. - **Auth middleware: %90+** — Güvenlik katmanı yüksek coverage istemeli. - **API route'ları: %80+** — Temel akışlar ve hata durumları. - **Utility fonksiyonlar: %80+** — İş mantığı. - **UI bileşenleri: %50+** — E2E testlerle dolaylı olarak test edilir, birim test önceliği düşük. **%100 genel coverage hedefleme.** Anlamsız testler yazmak, test yazmamak kadar kötüdür. Kritik yolları yüksek coverage'la koru, geri kalanı pragmatik tut. --- ## Gotchas - **Stripe webhook testi atlanırsa:** "Production'da çalışır" varsayımı en tehlikeli varsayımdır. Stripe CLI ile her event türünü ayrı ayrı test et. - **E2E testlerde flaky test sorunu:** Zamanlama bağımlı testler rastgele başarısız olur. `waitForTimeout()` yerine Playwright'ın auto-wait mekanizmasına güven. - **Test veritabanı izolasyonu:** Testler production veya development veritabanını kullanmamalı. Ayrı bir test veritabanı veya her test öncesi seed + sonrası temizleme stratejisi uygula. - **Mock'lar gerçeklikten kopar.** Mock'ladığın servisin API'si değişirse testlerin hâlâ geçer ama production'da çöker. Düzenli olarak mock'ları gerçek API ile karşılaştır. - **CI'da ortam değişkenleri.** Test ortamı için ayrı `.env.test` dosyası veya CI secret'ları kullan. Production anahtarları CI'da olmamalı. - **E2E testleri yavaştır.** Tüm E2E suite'ini her commit'te çalıştırmak CI'ı yavaşlatır. Kritik akışları her PR'da, tam suite'i main merge öncesinde çalıştır.