verify

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.