Testing

Overview

OhnePapier has no automated test suite — it is a Docker Compose orchestration project with no application source code to unit-test. Validation is entirely manual and operational: confirming services start, connect correctly, and process documents end-to-end.

Validation Philosophy

The connection chain (host Ollama → Docker network → paperless-ai → webserver) is silently brittle. Services can appear healthy while the chain is broken. Validation must be active (trigger behavior, observe output) not passive (check container status).

Pre-flight Checklist (Fresh Install)

Run before every docker compose up on a fresh machine:

# 1. Confirm secrets file exists
ls -la docker-compose.env

# 2. Confirm Ollama is running on the host
curl http://localhost:11434/api/tags | jq '.models[].name'

# 3. Confirm paperless-ai has no network_mode: bridge set
grep -i "network_mode" docker-compose.yml  # should return nothing

All three must pass before starting the stack.

Stack Startup Validation

# Start stack
docker compose up -d

# Confirm all 4 containers are running
docker compose ps

# Check webserver is healthy (may take 30-60s for initial startup)
curl -s http://localhost:8000/api/ | jq .

# Check paperless-ai is running
curl -s http://localhost:3000/  # should return some response

Integration Validation (Connection Chain)

Paperless-ngx → PostgreSQL

docker compose logs db | tail -20
# Look for: "database system is ready to accept connections"

docker exec paperless-webserver-1 python3 manage.py shell -c \
  "from django.db import connection; connection.ensure_connection(); print('DB OK')"

paperless-ai → Paperless-ngx API

docker compose logs paperless-ai | tail -30
# Look for successful API calls, not 401/404 errors
# Token must be configured — see CLAUDE.md for generation command

paperless-ai → Ollama (host machine)

docker compose logs paperless-ai | grep -i ollama
# Look for successful model calls, not connection refused

# Test connectivity from inside container
docker exec paperless-ai curl -s http://host.docker.internal:11434/api/tags | head -5

API Token Generation

docker exec paperless-webserver-1 python3 manage.py shell -c "
from rest_framework.authtoken.models import Token
from django.contrib.auth.models import User
user = User.objects.first()
token, _ = Token.objects.get_or_create(user=user)
print(f'Token: {token.key}')
"

Token must be set in paperless-ai environment config. See CLAUDE.md for full configuration.

End-to-End Document Processing Test

1. Drop a PDF into ./consume/ (the hot-folder)
2. Watch webserver logs: docker compose logs -f webserver
3. Confirm document appears in Paperless-ngx UI at http://localhost:8000
4. Wait for paperless-ai scan cycle (every 30 min by default, or trigger manually)
5. Confirm document gets auto-tagged, titled, and correspondent assigned in the UI

Health Check Commands

# All services status
docker compose ps

# Live log tail (all services)
docker compose logs -f

# Live log tail (specific service)
docker compose logs -f webserver
docker compose logs -f paperless-ai
docker compose logs -f db
docker compose logs -f broker

# Django management shell
docker exec -it paperless-webserver-1 python3 manage.py shell

Known Failure Modes

Mapped: 2026-04-17