OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
"""Unit tests for the two-phase Docling + Langflow ingestion flow.
Verifies the core architectural property: when a polling service is provided,
``LangflowFileService.upload_and_ingest_file`` must NOT invoke the Langflow
ingestion flow until Docling reports SUCCESS, and must NEVER invoke it when
Docling fails / expires / times out.
"""
from types import SimpleNamespace
from unittest.mock import AsyncMock
import pytest
from models.tasks import (
DoclingPhaseStatus,
FileTask,
IngestionPhase,
)
from services.docling_polling_service import DoclingPollResult, PollOutcome
from services.langflow_file_service import LangflowFileService
@pytest.fixture
def file_tuple():
return ("test.pdf", b"PDFDATA", "application/pdf")
@pytest.fixture
def file_task():
return FileTask(file_path="/tmp/test.pdf", filename="test.pdf")
@pytest.fixture
def mock_docling_service():
svc = AsyncMock()
svc.upload_to_docling_direct_async.return_value = "task-abc-123"
return svc
@pytest.fixture
def mock_polling_service():
return AsyncMock()
@pytest.fixture
def langflow_service(mock_docling_service):
svc = LangflowFileService(docling_service=mock_docling_service)
# Stub the actual Langflow HTTP call — those have their own coverage.
svc.run_ingestion_flow = AsyncMock(return_value={"status": "ok"})
return svc
@pytest.mark.asyncio
async def test_two_phase_success_invokes_langflow_with_task_id(
langflow_service, mock_docling_service, mock_polling_service, file_tuple, file_task
):
mock_polling_service.poll_until_ready.return_value = DoclingPollResult(
outcome=PollOutcome.SUCCESS, elapsed_seconds=2.5
)
result = await langflow_service.upload_and_ingest_file(
file_tuple=file_tuple,
docling_polling_service=mock_polling_service,
file_task=file_task,
owner="owner-123",
jwt_token="Bearer jwt-token",
)
mock_docling_service.upload_to_docling_direct_async.assert_awaited_once_with(
"test.pdf",
b"PDFDATA",
user_id="owner-123",
auth_header="Bearer jwt-token",
ocr=None,
picture_descriptions=None,
preview_mode=False,
)
# Langflow was invoked exactly once, with the docling_task_id forwarded.
assert langflow_service.run_ingestion_flow.call_count == 1
kwargs = langflow_service.run_ingestion_flow.call_args.kwargs
assert kwargs["docling_task_id"] == "task-abc-123"
# FileTask reflects full lifecycle.
assert file_task.docling_task_id == "task-abc-123"
assert file_task.docling_status == DoclingPhaseStatus.SUCCESS
assert file_task.phase == IngestionPhase.COMPLETE
# Result envelope.
assert result["status"] == "success"
assert result["docling_task_id"] == "task-abc-123"
@pytest.mark.asyncio
async def test_langflow_not_invoked_on_docling_failure(
langflow_service, mock_polling_service, file_tuple, file_task
):
mock_polling_service.poll_until_ready.return_value = DoclingPollResult(
outcome=PollOutcome.FAILED, detail="OCR engine crashed"
)
with pytest.raises(Exception, match="OCR engine crashed"):
await langflow_service.upload_and_ingest_file(
file_tuple=file_tuple,
docling_polling_service=mock_polling_service,
file_task=file_task,
)
# Crucial assertion — Langflow must never run when Docling failed.
assert langflow_service.run_ingestion_flow.call_count == 0
assert file_task.docling_status == DoclingPhaseStatus.FAILED
# Phase remains DOCLING (never advanced to LANGFLOW).
assert file_task.phase == IngestionPhase.DOCLING
@pytest.mark.asyncio
async def test_docling_load_failure_on_encrypted_pdf_names_password_protection(
langflow_service, mock_polling_service, file_task
):
"""Newer docling drops the PDFium reason; the bytes still show the PDF is encrypted."""
head = b"%PDF-1.7\n1 0 obj\n<< /Type /Catalog >>\nendobj\n"
pdf = (
head
+ b"xref\n0 1\n0000000000 65535 f \ntrailer\n<< /Root 1 0 R /Encrypt 5 0 R >>\n"
+ b"startxref\n%d\n%%%%EOF\n" % len(head)
)
encrypted = ("secret.pdf", pdf, "application/pdf")
mock_polling_service.poll_until_ready.return_value = DoclingPollResult(
outcome=PollOutcome.FAILED,
detail=(
"Docling result unavailable after SUCCESS status: Docling processing failed: "
"docling-parse could not load document 8fc525: "
"Failed to load document with key key=8fc525"
),
)
with pytest.raises(Exception) as exc_info:
await langflow_service.upload_and_ingest_file(
file_tuple=encrypted,
docling_polling_service=mock_polling_service,
file_task=file_task,
)
message = str(exc_info.value)
assert message.startswith("Docling conversion did not complete (failed): ")
assert "Incorrect password" in message
assert "with key" not in message
assert langflow_service.run_ingestion_flow.call_count == 0
@pytest.mark.asyncio
async def test_docling_load_failure_on_unencrypted_pdf_keeps_docling_detail(
langflow_service, mock_polling_service, file_tuple, file_task
):
detail = "docling-parse could not load document 8fc525: Failed to load document with key k"
mock_polling_service.poll_until_ready.return_value = DoclingPollResult(
outcome=PollOutcome.FAILED, detail=detail
)
with pytest.raises(Exception, match="Failed to load document with key k"):
await langflow_service.upload_and_ingest_file(
file_tuple=file_tuple,
docling_polling_service=mock_polling_service,
file_task=file_task,
)
@pytest.mark.asyncio
async def test_langflow_not_invoked_on_docling_expired(
langflow_service, mock_polling_service, file_tuple, file_task
):
mock_polling_service.poll_until_ready.return_value = DoclingPollResult(
outcome=PollOutcome.EXPIRED, detail="task not found"
)
with pytest.raises(Exception, match="expired"):
await langflow_service.upload_and_ingest_file(
file_tuple=file_tuple,
docling_polling_service=mock_polling_service,
file_task=file_task,
)
assert langflow_service.run_ingestion_flow.call_count == 0
assert file_task.docling_status == DoclingPhaseStatus.EXPIRED
@pytest.mark.asyncio
async def test_langflow_not_invoked_on_polling_timeout(
langflow_service, mock_polling_service, file_tuple, file_task
):
mock_polling_service.poll_until_ready.return_value = DoclingPollResult(
outcome=PollOutcome.TIMEOUT, detail="exceeded 1800s"
)
with pytest.raises(Exception, match="timeout"):
await langflow_service.upload_and_ingest_file(
file_tuple=file_tuple,
docling_polling_service=mock_polling_service,
file_task=file_task,
)
assert langflow_service.run_ingestion_flow.call_count == 0
assert file_task.docling_status == DoclingPhaseStatus.FAILED
@pytest.mark.asyncio
async def test_phase_progresses_only_after_polling_succeeds(
langflow_service, mock_polling_service, file_tuple, file_task
):
"""Phase must be DOCLING during polling, then LANGFLOW, then COMPLETE."""
observed_phases = []
async def record_then_succeed(*args, **kwargs):
observed_phases.append(file_task.phase)
return DoclingPollResult(outcome=PollOutcome.SUCCESS)
mock_polling_service.poll_until_ready.side_effect = record_then_succeed
async def record_then_run(*args, **kwargs):
observed_phases.append(file_task.phase)
return {"status": "ok"}
langflow_service.run_ingestion_flow = AsyncMock(side_effect=record_then_run)
await langflow_service.upload_and_ingest_file(
file_tuple=file_tuple,
docling_polling_service=mock_polling_service,
file_task=file_task,
)
assert observed_phases == [IngestionPhase.DOCLING, IngestionPhase.LANGFLOW]
assert file_task.phase == IngestionPhase.COMPLETE
@pytest.mark.asyncio
async def test_legacy_path_without_polling_service_calls_langflow_directly(
langflow_service, file_tuple, file_task
):
"""Backward compatibility: when no polling service is provided, Langflow
is invoked immediately after Docling submission (Langflow handles polling).
On success the file_task must end with docling_status=SUCCESS so the
status fields stay coherent — Langflow returning success implies its
DoclingRemote component consumed the task.
"""
result = await langflow_service.upload_and_ingest_file(
file_tuple=file_tuple,
docling_polling_service=None,
file_task=file_task,
)
assert langflow_service.run_ingestion_flow.call_count == 1
kwargs = langflow_service.run_ingestion_flow.call_args.kwargs
assert kwargs["docling_task_id"] == "task-abc-123"
assert result["status"] == "success"
# Status fields must not leave the task stuck in PROCESSING.
assert file_task.docling_status == DoclingPhaseStatus.SUCCESS
assert file_task.phase == IngestionPhase.COMPLETE
assert file_task.docling_task_id == "task-abc-123"
def test_processor_default_polling_service_is_none():
"""LangflowFileProcessor no longer constructs a polling service inline.
The container injects it; absent injection, the processor falls back
to the legacy single-call path.
"""
from models.processors import LangflowFileProcessor
lf_svc = LangflowFileService(docling_service=AsyncMock())
processor = LangflowFileProcessor(
langflow_file_service=lf_svc, session_manager=None, allow_anonymous_delete=True
)
assert processor.docling_polling_service is None
def test_processor_accepts_injected_polling_service():
"""The polling service is passed through unchanged when injected."""
from models.processors import LangflowFileProcessor
lf_svc = LangflowFileService(docling_service=AsyncMock())
injected = AsyncMock()
processor = LangflowFileProcessor(
langflow_file_service=lf_svc,
session_manager=None,
docling_polling_service=injected,
allow_anonymous_delete=True,
)
assert processor.docling_polling_service is injected
@pytest.mark.asyncio
async def test_langflow_preflight_detects_embedding_dimensions_with_probe(monkeypatch):
calls: list[tuple[str, list]] = []
async def fake_embeddings(body, **_kwargs):
calls.append((body["model"], body["input"]))
return {"data": [{"embedding": [0.1] * 7}]}
monkeypatch.setattr("services.llm_gateway.embeddings", fake_embeddings)
svc = LangflowFileService(docling_service=AsyncMock())
assert await svc._detect_embedding_dimensions("provider/model", "provider") == 7
assert await svc._detect_embedding_dimensions("provider/model", "provider") == 7
# One call for two invocations: the probe is cached per provider+model.
# The id is provider-tagged with `:` so the gateway routes it to the
# provider the caller named rather than to the configured default.
#
# `provider/model` is the legacy tagged spelling of the same id, so the
# tag is replaced rather than stacked. Asserting `provider:provider/model`
# here, as this did, encoded the double-tagging bug: the gateway strips
# the colon tag and would ask LiteLLM for `provider/provider/model`.
assert calls == [("provider:model", ["dimension probe"])]
@pytest.mark.asyncio
async def test_langflow_preflight_defaults_unset_embedding_provider_to_openai(monkeypatch):
class FakeIndices:
async def exists(self, *, index):
return True
fake_opensearch = SimpleNamespace(indices=FakeIndices())
monkeypatch.setattr("services.langflow_file_service.clients.opensearch", fake_opensearch)
monkeypatch.setattr(
"config.settings.get_openrag_config",
lambda: SimpleNamespace(knowledge=SimpleNamespace(embedding_provider=None)),
)
monkeypatch.setattr("config.settings.get_index_name", lambda: "documents")
ensure_field = AsyncMock()
monkeypatch.setattr("utils.embedding_fields.ensure_embedding_field_exists", ensure_field)
svc = LangflowFileService(docling_service=AsyncMock())
svc._detect_embedding_dimensions = AsyncMock(return_value=1536)
await svc._ensure_langflow_ingest_index("text-embedding-3-small")
svc._detect_embedding_dimensions.assert_awaited_once_with("text-embedding-3-small", "openai")
ensure_field.assert_awaited_once_with(
fake_opensearch,
"openai:text-embedding-3-small",
"documents",
1536,
)
@pytest.mark.asyncio
async def test_task_service_threads_polling_service_to_processor(monkeypatch):
"""TaskService.create_langflow_upload_task must forward its injected
polling service to the LangflowFileProcessor it constructs. This is the
DI contract that replaces the processor's inline construction.
"""
from services.task_service import TaskService
injected = AsyncMock()
captured: dict = {}
class FakeProcessor:
def __init__(self, **kwargs):
captured.update(kwargs)
monkeypatch.setattr("models.processors.LangflowFileProcessor", FakeProcessor)
async def fake_create_custom_task(*args, **kwargs):
return "task-id"
svc = TaskService(docling_polling_service=injected)
monkeypatch.setattr(svc, "create_custom_task", fake_create_custom_task)
await svc.create_langflow_upload_task(
user_id="u1",
file_paths=["/tmp/x.pdf"],
langflow_file_service=AsyncMock(),
session_manager=AsyncMock(),
allow_anonymous_delete=True,
)
assert captured["docling_polling_service"] is injected
@pytest.mark.asyncio
async def test_docling_submit_failure_skips_polling_and_langflow(
mock_docling_service, mock_polling_service, file_tuple, file_task
):
mock_docling_service.upload_to_docling_direct_async.side_effect = Exception(
"docling unreachable"
)
svc = LangflowFileService(docling_service=mock_docling_service)
svc.run_ingestion_flow = AsyncMock()
with pytest.raises(Exception, match="Docling upload failed"):
await svc.upload_and_ingest_file(
file_tuple=file_tuple,
docling_polling_service=mock_polling_service,
file_task=file_task,
)
assert mock_polling_service.poll_until_ready.call_count == 0
assert svc.run_ingestion_flow.call_count == 0
assert file_task.docling_task_id is None