feat: Docker integration test — run snapshot test against built image in CI

[longieirl]

Summary

There is a gap between what CI validates and what users actually run.

The current integration test (pytest -m integration) runs the full extraction pipeline end-to-end in Python, verifying transaction counts, file outputs, and processing summary metrics against a committed snapshot. It is intentionally excluded from the default test run and must be triggered explicitly.

The gap: CI only smoke-tests the Docker image with a Python import check (import bankstatements_free; import bankstatements_core). It never runs the actual processing pipeline inside the container against real PDFs. This means a Docker-specific regression — a broken entrypoint, a missing volume mount, a wrong env var default, or a config that behaves differently inside the container — would pass CI and only be caught by a developer running make docker-local by hand.

---

What is currently tested

Layer	What is tested	Where
Unit	Individual services and classes	pytest (default, 1395 tests)
Integration (Python)	Full pipeline against real PDFs, snapshot comparison	pytest -m integration (manual only)
Docker (CI)	Image builds, Python imports succeed	ci.yml build-docker job
Docker (pipeline)	Not tested	—

---

What the gap looks like

A developer making a change to entrypoint.sh, docker-compose.yml, or an env-var default could:

• Break the volume mount for input/ or output/
• Set a default that silently changes filter or sort behaviour inside the container
• Introduce a startup error that the import smoke-test does not catch

None of these would fail the current CI pipeline.

---

Proposed solution

Add a docker-integration CI job (runs after build-docker) that:

1. Mounts a small set of test PDFs from packages/parser-core/tests/integration/fixtures/ (or a dedicated tests/docker/input/ directory) into the container
2. Runs the container to process them
3. Asserts the output directory contains the expected files and non-zero transaction counts

This mirrors the existing Python integration test but exercises the real Docker entrypoint, volume mounts, and env-var handling.

Minimal CI step (sketch)

- name: Run Docker integration test
  run: |
    mkdir -p /tmp/docker-test/input /tmp/docker-test/output
    cp packages/parser-core/tests/integration/fixtures/*.pdf /tmp/docker-test/input/
    docker run --rm       -v /tmp/docker-test/input:/app/input:ro       -v /tmp/docker-test/output:/app/output       bankstatementsprocessor:pr-${{ github.event.pull_request.number }}
    ls /tmp/docker-test/output/*.csv || (echo "No CSV output produced" && exit 1)
    python3 -c "
    import json, glob, sys
    files = glob.glob('/tmp/docker-test/output/*.json')
    total = sum(len(json.load(open(f))) for f in files if not f.endswith('_summary.json'))
    print(f'Transactions: {total}')
    sys.exit(0 if total > 0 else 1)
    "

Local equivalent (for developers)

# 1. Build the image
make docker-build

# 2. Run against the test fixtures
docker run --rm   -v $(pwd)/packages/parser-core/tests/integration/fixtures:/app/input:ro   -v /tmp/docker-output:/app/output   bankstatementsprocessor:latest

# 3. Inspect output
ls /tmp/docker-output/

---

Value to developers

• Catches entrypoint regressions — a broken CMD or missing PYTHONPATH shows up immediately
• Validates volume mount contract — confirms /app/input and /app/output work as documented
• Exercises env-var defaults — RECURSIVE_SCAN, COLUMN_NAMES, TABLE_TOP_Y etc. are tested in their default state
• Closes the loop between unit tests and what ships — the Docker image is what users actually run; this test validates that layer

---

Acceptance criteria

• CI runs a Docker integration test on every PR that touches Dockerfile, entrypoint.sh, docker-compose.yml, or packages/parser-core/
• Test mounts at least one real PDF, runs the container, and asserts CSV output with non-zero transaction count
• make docker-integration target added for local use
• Test fixtures committed (small, anonymised PDFs) or existing integration fixtures reused
• Job added to the ci-gate required checks

[longieirl]

Remaining work — CI job (local tooling done in PR #70)

PR #70 merged the local side: make docker-integration, docker_snapshot.py, and the committed baseline snapshot (469 transactions across 3 IBANs). What remains is wiring this into CI.

---

1. Add docker-integration job to ci.yml

Insert after build-docker:

```yaml
docker-integration:
name: Docker integration test
runs-on: ubuntu-latest
timeout-minutes: 15
needs: build-docker
if: needs.changes.outputs.docker == 'true' && github.event_name == 'pull_request'

steps:
- uses: actions/checkout@v6

- uses: docker/setup-buildx-action@v4

- name: Rebuild image (reuse layer cache from build-docker)
  uses: docker/build-push-action@v7
  with:
    context: .
    target: production
    push: false
    load: true
    tags: bankstatementsprocessor:pr-\${{ github.event.pull_request.number }}
    cache-from: type=gha
    cache-to: type=gha,mode=max

- name: Set up Python (for snapshot comparison script)
  uses: actions/setup-python@v6
  with:
    python-version: '3.12'

- name: Run Docker integration test
  run: |
    mkdir -p /tmp/docker-output
    docker run --rm           -v \$(pwd)/packages/parser-core/tests/integration/fixtures:/app/input:ro           -v /tmp/docker-output:/app/output           bankstatementsprocessor:pr-\${{ github.event.pull_request.number }}
    python3 packages/parser-core/tests/integration/docker_snapshot.py           /tmp/docker-output           packages/parser-core/tests/integration/snapshots/output_snapshot.json

```

The docker_snapshot.py script exits non-zero on any mismatch — no extra assertion step needed.

---

2. Update ci-pass gate

Add docker-integration to the needs list in the ci-pass job. The existing success/skipped logic handles non-Docker PRs automatically.

---

3. Optionally extend the docker changes filter

Consider adding docker-compose.yml if env-var default regressions are a concern:

```yaml
docker:

• 'Dockerfile'
• 'entrypoint.sh'
• 'docker-compose.yml'
  ```

---

4. Add to branch protection required checks

GitHub → Settings → Branches → main → Required status checks → add Docker integration test.

---

Gotchas

• Image reuse: build-docker tags with bankstatementsprocessor:pr-<N>. The docker-integration job rebuilds from the same GHA layer cache — fast and avoids artifact upload/download complexity.
• Fixture PDFs: The committed snapshot was generated from PDFs in tests/integration/fixtures/. Verify that path has the right PDFs before enabling the job. Re-baseline with make docker-integration (calls docker_snapshot.py --update) if extraction output ever changes.
• Trigger scope: The issue asks the job to also fire on packages/parser-core/ changes, which would rebuild Docker on every parser-core PR. Starting with docker filter only is cheaper — expand later if needed.