diff --git a/README.md b/README.md index d872ff3..aa25c21 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,12 @@ The source code is available at [github.com/ChrisAdamsdevelopment/SpectraCleanse --- +## QA / Deployment Testing + +For a step-by-step manual validation flow (local, API smoke, auth, billing, upload, cleanse, Docker, and production readiness), see [`docs/manual-qa-checklist.md`](docs/manual-qa-checklist.md). + +--- + ## Contact Questions, partnerships, or enterprise enquiries: [hello@spectracleanse.com](mailto:hello@spectracleanse.com) diff --git a/docs/manual-qa-checklist.md b/docs/manual-qa-checklist.md new file mode 100644 index 0000000..b787df5 --- /dev/null +++ b/docs/manual-qa-checklist.md @@ -0,0 +1,164 @@ +# SpectraCleanseAI Manual QA Checklist + +Use this checklist before and after deployment to validate critical functionality consistently. + +## 1) Local setup + +1. Install dependencies: + ```bash + npm install + ``` +2. Build the app: + ```bash + npm run build + ``` +3. Start the server with safe local environment variables: + ```bash + NODE_ENV=development JWT_SECRET=dev_jwt_secret_change_me ENABLE_MOCK_CHECKOUT=true DB_PATH=./spectra.db FRONTEND_URL=http://localhost:5173 PORT=3001 npm start + ``` +4. Open the app in a browser: + - `http://localhost:3001` +5. Verify health endpoint: + - `GET http://localhost:3001/api/health` + - Expected: JSON response with HTTP `200`. + +## 2) API smoke tests + +Run these checks against your local server: + +1. `GET /api/health` + - Expected: JSON body, HTTP `200`. +2. `GET /api/me` without token + - Expected: JSON error, HTTP `401`. +3. `GET /api/nonexistent` + - Expected: JSON error, HTTP `404`. +4. Unknown frontend route (example: `/some/random/page`) + - Expected: app shell/index HTML loads (SPA fallback). +5. Confirm routing boundary + - Expected: `/api/*` routes are **not** swallowed by SPA fallback. + +## 3) Auth flow QA + +1. Register a new user. +2. Log in with valid credentials. +3. Refresh browser and confirm session restore works. +4. Log out and confirm protected actions require login again. +5. Attempt invalid login and verify user-facing error handling. + +## 4) Billing / Stripe / mock checkout QA + +1. With `ENABLE_MOCK_CHECKOUT=true`, trigger upgrade/checkout locally. + - Expected: mock checkout behavior (no real Stripe charge). +2. Hit free-tier limit or simulate `402` response. + - Expected: upgrade modal opens. +3. Complete local mock checkout path. + - Expected: checkout success banner appears. +4. Trigger checkout cancel flow (if available in current UI). + - Expected: checkout cancel banner/message appears. +5. Production readiness note: + - Real Stripe secret key, webhook secret, and price IDs must be configured. + +## 5) File upload QA + +1. Upload a supported MP3 file. +2. Upload another supported format (for example WAV or MP4, if available). +3. Try an unsupported file type. + - Expected: validation/rejection message. +4. Test file size limits if documented. + - Expected: behavior matches documented constraints. +5. Confirm uploaded item appears in the processing queue/list. + +## 6) Metadata analysis QA + +1. After upload, confirm metadata analysis runs automatically. +2. Verify displayed metadata includes title, artist, genre, and format (when present). +3. Verify provenance risk display is visible. +4. If file metadata includes known markers, verify detected markers list is shown. +5. Use malformed/minimal metadata sample if available. + - Expected: parse failure is handled gracefully and app does not crash. + +## 7) Generate AI SEO Payload QA + +1. Ensure file/context is present, then run SEO generation. +2. Verify generated title, description, and tags populate UI fields. +3. Test failure mode (missing `GEMINI_API_KEY` or simulated API failure). + - Expected: clear error handling/message. +4. Confirm existing SEO fields are not destructively cleared on generation failure. + +## 8) Quick Cleanse Browser QA + +1. On MP3 input, verify MP3-only quick cleanse action/button is enabled. +2. On non-MP3 input, verify quick cleanse is disabled or unavailable. +3. Run quick cleanse for supported MP3. +4. Verify a manual download link appears. +5. Confirm no auto-download is triggered. +6. Download processed MP3. +7. Re-upload or inspect resulting MP3 and confirm metadata fields changed as expected. +8. Confirm system logs show cleanse success/failure path. + +## 9) Full Server Cleanse QA + +1. Run server cleanse on a supported file. +2. Verify `/api/process` returns downloadable file response. +3. Verify usage meter/counter updates. +4. Verify forensic/report information appears when present. +5. Force or simulate `401` from protected endpoint. + - Expected: user is logged out/reauth requested. +6. Force or simulate `402`. + - Expected: upgrade modal opens. + +## 10) Object URL / download safety QA + +1. Process a file and copy/download the generated link. +2. Replace with a newly processed file. + - Expected: old object URL/link is no longer used by current UI state. +3. Remove queue item. +4. Refresh page. +5. Confirm no obvious stale/broken download UI remains. + +## 11) Docker deployment QA + +> Note: Docker was unavailable in Codex audits; run these steps manually in a Docker-capable environment. + +1. Build image: + ```bash + docker build -t spectracleanseai:test . + ``` +2. Run container (example): + ```bash + docker run --rm -p 3001:3001 \ + -e NODE_ENV=production \ + -e JWT_SECRET=replace_with_strong_secret \ + -e STRIPE_SECRET_KEY=sk_live_or_test_xxx \ + -e STRIPE_WEBHOOK_SECRET=whsec_xxx \ + -e STRIPE_CREATOR_PRICE_ID=price_xxx \ + -e STRIPE_STUDIO_PRICE_ID=price_xxx \ + -e GEMINI_API_KEY=your_gemini_api_key \ + -e FRONTEND_URL=https://your-frontend-domain.example \ + -e DB_PATH=/data/spectra.db \ + -v spectracleanse_data:/data \ + spectracleanseai:test + ``` +3. Verify app loads from container at `http://localhost:3001`. +4. Verify `GET /api/health` returns JSON `200`. +5. Verify unknown frontend route returns SPA fallback. +6. Verify `GET /api/nonexistent` returns JSON `404`. + +## 12) Production readiness checklist + +- [ ] `JWT_SECRET` is strong and unique. +- [ ] Stripe secret, webhook secret, and price IDs are configured. +- [ ] `GEMINI_API_KEY` is configured. +- [ ] `DB_PATH` points to persistent storage. +- [ ] `FRONTEND_URL` is correct for deployed frontend. +- [ ] `NODE_ENV=production`. +- [ ] No real secrets are committed to source control. +- [ ] `.env` is gitignored. +- [ ] Backup/persistence plan exists for database. +- [ ] Upload/data volume mount is configured for expected data volume. + +## 13) Known warnings + +- `npm audit` currently reports vulnerabilities and should be triaged. +- `music-metadata-browser` is deprecated; monitor and replace in a later maintenance cycle. +- Docker build/runtime validation still requires a real Docker-capable environment.