Step 3 tested with real data. Added Step 4 implementation plan

tests/services/test_transcription_external.py

@@ -0,0 +1,70 @@
+"""Opt-in external tests for real document image transcription."""
+
+import os
+from pathlib import Path
+
+import pytest
+
+from transcription.services.transcription import transcribe_document_image
+
+
+HAS_OPENROUTER_KEY = bool(os.getenv("OPENROUTER_API_KEY"))
+
+REAL_IMAGES_DIR = Path(__file__).resolve().parents[1] / "fixtures" / "images" / "real"
+ARTIFACTS_DIR = Path(__file__).resolve().parents[1] / "artifacts" / "transcriptions"
+SUPPORTED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".tif", ".tiff", ".pdf"}
+
+pytestmark = [
+    pytest.mark.external,
+    pytest.mark.skipif(
+        not HAS_OPENROUTER_KEY,
+        reason="Set OPENROUTER_API_KEY to run external real-image tests.",
+    ),
+]
+
+
+def _real_image_paths() -> list[Path]:
+    if not REAL_IMAGES_DIR.exists():
+        return []
+    return sorted(
+        [
+            p
+            for p in REAL_IMAGES_DIR.iterdir()
+            if p.is_file() and p.suffix.lower() in SUPPORTED_EXTENSIONS
+        ]
+    )
+
+
+def _artifact_filename(image_path: Path) -> str:
+    safe_stem = image_path.stem.replace(" ", "_")
+    safe_suffix = image_path.suffix.lower().replace(".", "")
+    return f"{safe_stem}.{safe_suffix}.txt"
+
+
+class TestRealImageExternalTranscription:
+    """Validate transcription against real local fixtures via live provider."""
+
+    def test_real_image_fixture_set_exists(self):
+        """At least one supported real-image fixture exists for external tests."""
+        assert REAL_IMAGES_DIR.exists()
+        assert _real_image_paths()
+
+    @pytest.mark.parametrize("image_path", _real_image_paths(), ids=lambda p: p.name)
+    def test_transcribes_real_image_fixture(self, image_path: Path):
+        """Real fixture image produces a non-empty transcription result."""
+        result = transcribe_document_image(image_path)
+        assert result.provider == "openrouter"
+        assert isinstance(result.model, str) and result.model.strip()
+        assert isinstance(result.text, str) and result.text.strip()
+
+        ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
+        artifact_path = ARTIFACTS_DIR / _artifact_filename(image_path)
+        artifact_text = (
+            f"source: {image_path.name}\n"
+            f"provider: {result.provider}\n"
+            f"model: {result.model}\n"
+            "---\n"
+            f"{result.text}\n"
+        )
+        artifact_path.write_text(artifact_text, encoding="utf-8")
+        assert artifact_path.exists()