96 lines
6.5 KiB
Markdown
96 lines
6.5 KiB
Markdown
# 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)
|
||
|
||
```powershell
|
||
# 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](https://developer.microsoft.com/microsoft-edge/webview2/).
|
||
- 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`
|