6. Test and Debug
Validate a starter change and diagnose the most common local failures.
Test and Debug
Expected time: 30 minutes
Outcome: Your change passes the owning repository's checks and you have evidence for review.
Validate in Proportion to the Change
Run the checks documented by the repository you changed. At minimum:
- reproduce the behavior manually before and after the change;
- run the narrowest relevant automated test, when one exists;
- run the repository's lint and type checks for TypeScript changes;
- run
pytestfor affected Model Server behavior; and - run a production build when the repository guidance requires it.
For this documentation app, run:
yarn lint
yarn types:checkAlso run yarn build for route, API, or component changes. Do not claim a check passed unless you ran it and saw a successful exit.
Diagnose by Job Stage
| Symptom | First place to look |
|---|---|
| The Web App does not start | Web App logs, environment-file selection, database connectivity, and dependency installation. |
| The request is rejected immediately | User authorization, request validation, paired service credentials, and relative file paths. |
| The job remains pending | The Web App's request to the Model Server and the Model Server response. |
| The job is enqueued but never starts | Redis connectivity, queue name, and the matching RQ worker logs. |
| The worker cannot find an input | The shared-data/ relative path and the common container mount. |
| Processing finishes but the UI does not update | Notification worker, callback URL/key, callback response, and stable job ID. |
| A report exists but cannot be downloaded | File-specific report directory and Web App authorization for the requested file. |
Use Evidence, Not Guesswork
Choose one stable job or file ID and follow it through recent logs. Check the service responsible for the current state before restarting the entire stack. Preserve the original error message and record the smallest reproduction.
When asking for help, share:
- what you expected and what happened;
- the exact safe reproduction steps;
- the service and job stage where it failed;
- the relevant redacted error; and
- what you already checked.
Never share environment files, authorization headers, cookies, access tokens, private prompts, uploaded data, or provider responses containing sensitive material.
Checkpoint
Your acceptance criteria pass, required validation commands exit successfully, and git diff --check reports no whitespace errors.