SonicForgeStudio/TEST_DEBUG_PLAN.md

TEST & DEBUG PLAN — SonicForge DAW Standalone (Windows .exe / .msi)

Áp dụng cho bản đóng gói Tauri v2 + PyInstaller (xem DESKTOP_INSTALL_PLAN.md, build_windows.ps1, engine.spec, src-tauri/).

---

0. Cổng kiểm soát TRƯỚC khi build (pre-build gates — chạy trên máy dev)

# 1. Backend tests (repo đã có 86 tests pytest)
python -m pytest tests/ -x -q

# 2. Frontend syntax + bundle
node --check app/static/js/app.precompiled.js
node build.mjs                      # rebuild app.precompiled.js từ app.jsx

# 3. Python syntax của entry + spec
python -m py_compile desktop_engine.py engine.spec app/config.py app/tasks/worker.py

# 4. Chạy thử engine độc lập (chưa cần Tauri)
python desktop_engine.py            # mở browser: http://127.0.0.1:8000/docs

Gate: tất cả PASS mới chạy build_windows.ps1.

---

1. TEST PLAN — theo 6 kịch bản của tài liệu gốc

#	Kịch bản	Cách kiểm thử	Kết quả mong đợi
1	Lifecycle & Process Spawn	Mở app → Task Manager tìm daw_engine.exe → đóng cửa sổ → kiểm tra lại	Engine xuất hiện lúc launch; BIẾN MẤT hoàn toàn khi đóng (không orphan). Engine còn có watchdog: nếu cha chết đột ngột, tự thoát ≤1s
2	Port 8000 & Fallback	Mở app → browser truy cập http://localhost:8000/docs; hoặc chiếm sẵn port 8000 (vd net stop dịch vụ khác / chạy server khác) rồi mở app	Swagger UI hiển thị. Khi 8000 bị chiếm → engine tự chuyển 8001…8010, loader page trong app tự redirect tới port đúng
3	VST3 Local Scan (Windows)	Plugin Manager → set path C:\Program Files\Common Files\VST3 → [Scan]	Phát hiện đúng VST3 đã cài (Vital, Surge XT, FabFilter…). Scan state lưu ở %APPDATA%\SonicForgeDAW\storage\sf_scan_state.json
4	Isolation & Crash Protection	Load 1 VST3 không ổn định / giả lập crash	UI hiện thông báo lỗi, cửa sổ DAW vẫn phản hồi (tiến trình engine riêng — shell không chết theo)
5	Storage Persistence (%APPDATA%)	Mở Explorer tới %APPDATA%\SonicForgeDAW\storage\	Có sonicforge.db, sf_scan_state.json, uploads/, processed/, soundfonts/ — không nằm trong thư mục cài đặt (onefile giải nén tạm sẽ bị xóa khi thoát)
6	Audio Export / Bouncing	Click Export WAV ở chế độ Standalone	File .wav render đúng (VST3 + SoundFont qua Pedalboard/FluidSynth)

1.1 Kiểm thử cài đặt (installer)

• NSIS: cài trên máy sạch (không có Python, không có VC++ redist) → app chạy được, hooks.nsh tự cài VC redist. Gỡ cài bằng Control Panel → không còn process, không còn shortcut.
• MSI: cài qua msiexec /i SonicForgeDAW_1.0.0_x64_en-US.msi (hoặc double-click) → tương đương; kiểm tra repair/uninstall.
• Nâng cấp: cài bản mới đè bản cũ → %APPDATA%\SonicForgeDAW\storage GIỮ NGUYÊN (dữ liệu người dùng không mất).
• SmartScreen/AV: lần đầu chạy có thể bị chặn ("More info → Run anyway"); bản production phải ký số (signtool + certificate DigiCert/Sectigo).

1.2 Kiểm thử hồi quy (regression — sau mỗi thay đổi code)

• pytest tests/ — 86 test hiện có (conftest fixture dùng test client).
• Smoke UI thủ công: play/pause, piano roll, FX rack, save/load project, soundfont scan.

---

2. DEBUG WORKFLOWS

2.1 Engine (Python sidecar) không start / crash âm thầm

1. Mở log: %APPDATA%\SonicForgeDAW\logs\engine.log (desktop_engine.py ghi log ra file vì console=False).
2. Chạy thủ công engine có console: sửa console=True trong engine.spec → rebuild → chạy dist\daw_engine.exe từ cmd → xem traceback trực tiếp.
3. Test độc lập không cần Tauri: python desktop_engine.py (dev) — đúng code path, có stdout.

2.2 UI (WebView2)

• F12 / Ctrl+Shift+I trong cửa sổ app: mở DevTools (đã bật "devtools": true trong tauri.conf.json) — Console, Network, Web Audio context.
• devUrl: "http://localhost:8000" — bản dev có thể chạy tauri dev với engine chạy tay.

2.3 Sidecar không spawn / không thấy engine

• Kiểm tra src-tauri\binaries\daw_engine-x86_64-pc-windows-msvc.exe có tồn tại (build script copy tự động).
• Chạy npx tauri build lần đầu: nếu thiếu sidecar → lib.rs expect("sidecar daw_engine not found") fail rõ ràng.
• Kiểm tra port bị chiếm: netstat -ano | findstr :8000.

2.4 Windows build lỗi (máy dev)

• Rust toolchain: rustup default stable-msvc (bắt buộc MSVC toolchain cho Tauri Windows).
• WebView2 runtime: Win10/11 có sẵn; máy cũ cài WebView2 Evergreen.
• Nếu tauri build lỗi NSIS/MSI riêng: build riêng từng target npx tauri build --bundles nsis / --bundles msi.

---

3. Known Gaps (đã xử lý / chấp nhận)

Vấn đề	Trạng thái
Celery cần Redis broker	Đã xử lý: SF_DESKTOP=1 → task_always_eager=True (chạy đồng bộ trong tiến trình, memory:// broker + cache+memory:// backend). Chế độ docker/cloud không đổi
Storage khi frozen (onefile giải nén tạm)	Đã xử lý: config.py freeze-aware → writable data về %APPDATA%\SonicForgeDAW\storage, assets read-only trong _MEIPASS
Port 8000 bị chiếm	Đã xử lý: probe 8000–8010 + loader page redirect tự động
engine.spec console=False → mù log	Đã xử lý: log ra file %APPDATA%\SonicForgeDAW\logs\engine.log
Soundfont scanner path /opt/daw_engine/soundfonts (Linux-only)	Chấp nhận: cần xác minh scanner bỏ qua path không tồn tại trên Windows (test scenario #5)
child.kill() = TerminateProcess (không graceful 100%)	Giảm thiểu: watchdog parent-PID trong desktop_engine.py → engine tự shutdown sạch khi cha chết

---

4. Checklist phát hành (release)

• Pre-build gates PASS (mục 0)
• build_windows.ps1 chạy sạch, đủ 6 bước
• 6 kịch bản test (mục 1) PASS trên máy sạch
• Installer NSIS + MSI cài/gỡ/nâng cấp đúng
• Ký số (production) — SmartScreen hết cảnh báo
• Commit artifacts: engine.spec, desktop_engine.py, src-tauri/, build_windows.ps1, tools/gen_icons.py