| name | verify |
| description | Verify a Txtify change end-to-end. Use before committing any nontrivial change, when asked to "verify", "test this", or "make sure nothing breaks", and always after touching the worker/transcription path, dependencies, or the Dockerfile. |
Verifying Txtify changes
Two tiers. Pick the cheapest one that actually exercises the change.
Tier 1 — unit/API tests (seconds, no ML stack needed)
pytest -q
Covers: format converters (incl. PDF Unicode round-trip), filename/URL/upload validation, job-id DB flow, /health, /transcribe error paths, DeepL alignment edge cases. tests/conftest.py stubs torch/stable_whisper when absent, so a light venv is enough:
grep -v -E '^(torch|stable-ts)' requirements.txt > /tmp/reqs.txt
pip install -r /tmp/reqs.txt pytest httpx pypdf
Sufficient on its own only for changes fully covered by tests (converters, validation, endpoint logic).
Tier 2 — Docker E2E (the real gate, ~5–10 min)
./scripts/docker_e2e.sh
Builds the image, boots a container, checks /health + all pages + 404s, uploads a generated clip, runs a real whisper-tiny transcription to 100%, validates preview in all four formats, downloads the zip and confirms the PDF is in it, and checks validation errors. Success is the literal line PASS: docker E2E complete.
Mandatory for changes to: requirements.txt, Dockerfile, .dockerignore, src/transcribe_process.py, src/models.py, the worker-spawn path in src/utils.py.
Reading failures
- Status stuck at 10% → worker crashed at import (classic cause: torch/torchaudio version mismatch). Reproduce inside the container:
docker exec <name> python /app/src/transcribe_process.py 99 output/<clip> en whisper_tiny none en all
- Status stuck at 30% for a long time → model download in progress; not a failure yet.
- Job errors mid-run →
docker exec <name> cat output/<job id>_logs.txt (the server log won't show worker errors).
- The E2E script's container is removed on exit; to debug interactively,
docker run -d --rm --name txtify_dbg -p 8078:8011 txtify:e2e and drive it with curl.
What "verified" means in a PR body
Paste the actual output: the pytest summary line and/or the PASS: docker E2E complete line. A claim without output doesn't count.
