Blackbox Testing — Master Plan & Rancangan Sistem

Ruang lingkup: PT (8 fitur), PP (4 fitur), Apostille & Legalisasi (5 fitur).
Tujuan: untuk tiap fitur menghasilkan (1) dokumentasi full workflow, (2) laporan blackbox testing (semua UI yang diakses user + positive & negative case selengkapnya), (3) daftar perbaikan bila ada bug — semua dalam format yang seragam.
Keputusan yang sudah dikunci (2026-08-18): strategi Hybrid API + Playwright UI; data uji = PDF sintetis + melabeli backend/uploads/ yang ada; eksekusi via 3 sesi supervisor terpisah yang diluncurkan user; semua data uji (termasuk PDF nyata ber-PII) diunggah ke Google Drive (kepatuhan privasi di tangan user).

1. Kondisi sistem (hasil investigasi awal)

Konsekuensi penting:
- Tidak ada mock OCR/LLM — tiap flow memproses dokumen sungguhan, asinkron & lambat (timeout per-dokumen 11 menit). Uji harus berbasis polling status, bukan sinkron.
- Pipeline: UPLOADED → OCR_PROCESSING → AI_EXTRACTION → VERIFICATION_READY → IN_VERIFICATION → COMPLETED. Submission: CREATED → EXTRACTING → (AWAITING_CLASSIFICATION | AWAITING_COMPANY_SELECTION) → VALIDATING → READY → COMPLETED.

2. Model uji dua-lapis (kenapa hybrid)

"Blackbox" di sini bukan sekadar klik tombol, tapi memperlakukan sistem sebagai kotak hitam dari sudut pandang user — lewat dua lapis yang saling melengkapi:

• Lapisan API = cepat, deterministik, menutup positive & negative case aturan validasi (akta expired, NIK mismatch, dokumen kurang, kuorum, dsb). Ini tulang punggung cakupan skenario.
• Lapisan UI (Playwright) = memastikan setiap UI yang bisa diakses user benar-benar ditekan dan berperilaku benar (state tombol, navigasi, banner, drag-drop). Ini yang tidak bisa ditangkap lapisan API.

Aturan pembagian: kalau skenario menguji logika/aturan → utamakan lapisan API (murah). Kalau menguji interaksi/tampilan → wajib lewat Playwright. Fitur inti tiap flow diuji di kedua lapisan minimal untuk jalur positif utama (happy path end-to-end).

3. Struktur orkestrasi (multi-sesi)

Peran:
- Orkestrator (sesi ini): menyiapkan fondasi bersama sebelum supervisor jalan — harness Playwright + helper, template dokumentasi, katalog & pembuatan data uji, resolusi boot stack. Setelah itu menerima laporan tiap supervisor dan menyusun ringkasan lintas-domain.
- 3 Supervisor (sesi Claude Code terpisah, diluncurkan user): tiap supervisor memegang satu domain, mengeksekusi uji per fitur (boleh mendelegasikan ke sub-agent per fitur bila perlu), lalu menulis dokumentasi tiap fitur mengikuti template.

Tiap supervisor mendapat brief handoff sendiri: 02-handoff-pt.md, 03-handoff-pp.md, 04-handoff-apostille.md.

Kenapa 3 sesi terpisah, bukan Workflow tool: memungkinkan user mengerjakan hal lain sementara ketiganya jalan paralel, tiap sesi punya konteks domain penuh, dan hemat token dibanding fan-out otomatis. (Workflow tool tetap opsi bila user minta.)

4. Fondasi bersama (dibangun Orkestrator dulu — Fase 0)

Agar 3 supervisor produktif sejak menit pertama, hal berikut disiapkan lebih dulu:

4.1 Harness E2E — e2e/ di root repo

e2e/
  playwright.config.ts        # baseURL http://localhost:5173, headless, screenshot+trace on failure
  helpers/
    role.ts                   # setRole(page, "notaris") -> localStorage["userRole.v2"]
    upload.ts                 # uploadFiles(page, selector, paths[]) + drag-drop DataTransfer
    poll.ts                   # waitForStatus(apiBase, submissionId, "READY", timeoutMs)
    api.ts                    # klien HTTP tipis untuk lapisan API (upload, status, patch field, decide)
    report.ts                 # kumpulkan langkah + screenshot -> artefak per skenario
    pdf-factory.ts            # generator PDF sintetis (akta/KTP/NPWP) untuk positive/negative
  data/                       # data uji per flow (lihat 05-test-data-catalog.md)
  pt/  pp/  apostille/        # spec per domain (diisi supervisor)
  artifacts/                  # screenshot + trace + json hasil (git-ignored)

4.2 Set role (tanpa auth)

// helpers/role.ts — dijalankan sebelum page.goto route ter-gate
await page.addInitScript((r) => localStorage.setItem("userRole.v2", JSON.stringify(r)), role);

Peta role → domain: notaris/admin → PT & klasifikasi; perseroan → PP; umum → Apostille applicant; verifikator_pt / verifikator_apostille → antrean verifikator; admin → semua.

4.3 Selector strategy

data-testid/aria-label yang sudah ada dipakai lebih dulu (mis. pt-finalize-button, ktp-upload-preview, akuisisi-legal-path, tambah-dokumen-input). Bila sebuah elemen kritikal tak punya selector stabil, itu dicatat sebagai temuan (rekomendasi menambah data-testid) dan sementara dipakai selector teks Indonesia yang stabil.

4.4 Data uji

Lihat 05-test-data-catalog.md. Ringkas: PDF sintetis untuk kasus terkendali (positive + negative) + pelabelan subset backend/uploads/. Semua diunggah ke Google Drive dengan penamaan {{domain}}/{{fitur}}/{{positive|negative}}/{{deskripsi}}.pdf.

4.5 Boot stack (Fase 0)

1. Selesaikan bentrok port 3001 (identifikasi proses; jalankan dev_4 di port lain bila perlu, mis. PORT=3401, dan arahkan proxy Vite).
2. cd backend && docker compose up -d (Postgres 5433) → bunx prisma db push.
3. cd backend && bun run dev (verifikasi GET /api/health/ready).
4. cd frontend && bun run dev (5173).
5. Smoke: satu upload akta lewat UI hingga muncul halaman ekstraksi.

5. Format dokumentasi seragam (wajib)

Setiap fitur (17 total) menghasilkan satu dokumen docs/blackbox-testing/report/{domain}-{fitur}.md mengikuti 01-documentation-template.md persis, dengan bagian:
1. Ringkasan fitur & aktor/role
2. Full workflow — diagram state + sequence + peta route/UI
3. Prasyarat & data uji (tabel positive/negative)
4. Matriks skenario uji (ID, tipe, langkah, ekspektasi, hasil aktual, status, bukti)
5. Cakupan UI (tiap route/tombol yang diakses user + status uji)
6. Temuan bug (ID, severity, reproduksi, ekspektasi vs aktual, screenshot, rekomendasi perbaikan)
7. Ringkasan & rekomendasi

Keseragaman dijaga oleh template tunggal + checklist di tiap brief handoff.

6. Urutan pelaksanaan

• Fase 0 (sesi ini): ~fondasi. Blocker: resolusi port + boot stack.
• Fase 1 (paralel): tiap supervisor mengeksekusi domainnya. Estimasi didominasi latensi OCR (menit per dokumen) → utamakan lapisan API untuk volume skenario, Playwright untuk happy-path + interaksi.
• Fase 2 (sesi ini): gabungkan temuan, prioritas bug, unggah artefak & data uji ke Drive.

7. Risiko & mitigasi

8. Artefak paket ini