tests: Add endpoint-owned branch coverage for async client methods

datalogics-kam · datalogics-kam · commit 840dd88176ed · 2026-02-20T13:19:13.000-06:00
- Add non-live sync and async coverage for optional payload branches
  (output/output_prefix/pages/page_groups) in each endpoint's home
  test module
- Add async preview_redactions unit coverage in test_pdf_redaction_preview
- Keep coverage aligned with endpoint ownership instead of a shared
  cross-endpoint helper module
- Update TESTING_GUIDELINES.md to require endpoint-home tests and
  optional-branch coverage in both sync and async customization/success
  cases

Assisted-by: Codex
diff --git a/TESTING_GUIDELINES.md b/TESTING_GUIDELINES.md
@@ -19,6 +19,10 @@ iteration required.
   asserting method/path/headers/body). Optional payload branches (for example,
   `pages`, `output`, `rgb_color`, and output-prefix fields) require explicit
   tests so serialization differences are caught early.
+- **Keep endpoint tests in their home files.** When adding or restoring coverage
+  for an endpoint, place the test in that endpoint's existing test module (for
+  example, `tests/test_convert_to_excel.py`), not in a generic cross-endpoint
+  coverage file.
 - **Check client coverage regularly.** Run `uvx nox -s class-coverage` to
   enforce minimum function-level coverage for `PdfRestClient` and
   `AsyncPdfRestClient`.
@@ -95,6 +99,10 @@ iteration required.
   or `timeout`, add explicit tests (sync + async) proving those options
   propagate. Capture `request.extensions["timeout"]` and assert every component
   equals `pytest.approx(expected)`.
+- For both sync and async endpoint helpers, ensure request-customization or
+  success tests also exercise endpoint-specific optional payload branches (for
+  example `output`, `output_prefix`, `pages`, `page_groups`, redaction payloads)
+  so non-live class-function coverage does not depend on live suites.
 
 ### Validation & Payload Modeling
 
diff --git a/tests/test_blank_pdf.py b/tests/test_blank_pdf.py
@@ -668,6 +668,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             assert payload["custom_height"] == 100
             assert payload["custom_width"] == 50
             assert "page_orientation" not in payload
+            assert payload["output"] == "async-custom"
             assert payload["debug"] == "yes"
             return httpx.Response(
                 200,
@@ -695,6 +696,7 @@ def handler(request: httpx.Request) -> httpx.Response:
         response = await client.blank_pdf(
             page_size={"custom_height": 100, "custom_width": 50},
             page_count=1,
+            output="async-custom",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"debug": "yes"},
diff --git a/tests/test_convert_colors.py b/tests/test_convert_colors.py
@@ -277,6 +277,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             assert payload["color_profile"] == "custom"
             assert payload["profile_id"] == str(profile_file.id)
             assert payload["preserve_black"] == "false"
+            assert payload["output"] == "async-custom"
             return httpx.Response(
                 200,
                 json={
@@ -304,6 +305,7 @@ def handler(request: httpx.Request) -> httpx.Response:
         response = await client.convert_colors(
             input_file,
             color_profile=profile_file,
+            output="async-custom",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"debug": "yes"},
diff --git a/tests/test_convert_to_excel.py b/tests/test_convert_to_excel.py
@@ -204,6 +204,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["debug"] == "yes"
             assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-custom"
             return httpx.Response(
                 200,
                 json={
@@ -230,6 +231,7 @@ def handler(request: httpx.Request) -> httpx.Response:
     async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
         response = await client.convert_to_excel(
             input_file,
+            output="async-custom",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"debug": "yes"},
diff --git a/tests/test_convert_to_pdfa.py b/tests/test_convert_to_pdfa.py
@@ -227,6 +227,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["output_type"] == "PDF/A-2u"
             assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-custom"
             assert payload["extra"] == {"note": "async"}
             assert payload["rasterize_if_errors_encountered"] == "off"
             return httpx.Response(
@@ -251,6 +252,7 @@ def handler(request: httpx.Request) -> httpx.Response:
         response = await client.convert_to_pdfa(
             input_file,
             output_type="PDF/A-2u",
+            output="async-custom",
             rasterize_if_errors_encountered="off",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
diff --git a/tests/test_convert_to_pdfx.py b/tests/test_convert_to_pdfx.py
@@ -214,6 +214,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["output_type"] == "PDF/X-6"
             assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-custom"
             assert payload["extra"] == {"note": "async"}
             return httpx.Response(
                 200,
@@ -237,6 +238,7 @@ def handler(request: httpx.Request) -> httpx.Response:
         response = await client.convert_to_pdfx(
             input_file,
             output_type="PDF/X-6",
+            output="async-custom",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"extra": {"note": "async"}},
diff --git a/tests/test_convert_to_powerpoint.py b/tests/test_convert_to_powerpoint.py
@@ -204,6 +204,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["debug"] == "yes"
             assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-custom"
             return httpx.Response(
                 200,
                 json={
@@ -230,6 +231,7 @@ def handler(request: httpx.Request) -> httpx.Response:
     async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
         response = await client.convert_to_powerpoint(
             input_file,
+            output="async-custom",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"debug": "yes"},
diff --git a/tests/test_convert_to_word.py b/tests/test_convert_to_word.py
@@ -204,6 +204,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["debug"] == "yes"
             assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-custom"
             return httpx.Response(
                 200,
                 json={
@@ -230,6 +231,7 @@ def handler(request: httpx.Request) -> httpx.Response:
     async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
         response = await client.convert_to_word(
             input_file,
+            output="async-custom",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"debug": "yes"},
diff --git a/tests/test_convert_xfa_to_acroforms.py b/tests/test_convert_xfa_to_acroforms.py
@@ -198,6 +198,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["debug"] == "yes"
             assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-custom"
             return httpx.Response(
                 200,
                 json={
@@ -224,6 +225,7 @@ def handler(request: httpx.Request) -> httpx.Response:
     async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
         response = await client.convert_xfa_to_acroforms(
             input_file,
+            output="async-custom",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"debug": "yes"},
diff --git a/tests/test_export_form_data.py b/tests/test_export_form_data.py
@@ -262,6 +262,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["id"] == str(input_file.id)
             assert payload["data_format"] == "xml"
+            assert payload["output"] == "async-custom"
             assert payload["note"] == "details"
             return httpx.Response(
                 200,
@@ -290,6 +291,7 @@ def handler(request: httpx.Request) -> httpx.Response:
         response = await client.export_form_data(
             input_file,
             data_format="xml",
+            output="async-custom",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"note": "details"},
diff --git a/tests/test_extract_images.py b/tests/test_extract_images.py
@@ -199,7 +199,7 @@ async def test_async_extract_images_request_customization(
     input_file = make_pdf_file(PdfRestFileID.generate(2))
     output_id = str(PdfRestFileID.generate())
     payload_dump = ExtractImagesPayload.model_validate(
-        {"files": [input_file], "pages": ["1-last"]}
+        {"files": [input_file], "pages": ["1-last"], "output": "debug-async"}
     ).model_dump(mode="json", by_alias=True, exclude_none=True, exclude_unset=True)
     captured_timeout: dict[str, float | dict[str, float] | None] = {}
 
@@ -235,6 +235,7 @@ def handler(request: httpx.Request) -> httpx.Response:
         response = await client.extract_images(
             input_file,
             pages=["1-last"],
+            output="debug-async",
             extra_query={"trace": "true"},
             extra_headers={"X-Debug": "async"},
             extra_body={"debug": True},
diff --git a/tests/test_flatten_annotations.py b/tests/test_flatten_annotations.py
@@ -210,6 +210,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["debug"] == "yes"
             assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-custom"
             return httpx.Response(
                 200,
                 json={
@@ -236,6 +237,7 @@ def handler(request: httpx.Request) -> httpx.Response:
     async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
         response = await client.flatten_annotations(
             input_file,
+            output="async-custom",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"debug": "yes"},
diff --git a/tests/test_flatten_layers.py b/tests/test_flatten_layers.py
@@ -198,6 +198,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["debug"] == "yes"
             assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-custom"
             return httpx.Response(
                 200,
                 json={
@@ -224,6 +225,7 @@ def handler(request: httpx.Request) -> httpx.Response:
     async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
         response = await client.flatten_layers(
             input_file,
+            output="async-custom",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"debug": "yes"},
diff --git a/tests/test_flatten_pdf_forms.py b/tests/test_flatten_pdf_forms.py
@@ -195,6 +195,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["flags"] == ["a", "b"]
             assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-custom"
             return httpx.Response(
                 200,
                 json={
@@ -221,6 +222,7 @@ def handler(request: httpx.Request) -> httpx.Response:
     async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
         response = await client.flatten_pdf_forms(
             input_file,
+            output="async-custom",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"flags": ["a", "b"]},
diff --git a/tests/test_flatten_transparencies.py b/tests/test_flatten_transparencies.py
@@ -215,6 +215,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             assert payload["debug"] == "yes"
             assert payload["id"] == str(input_file.id)
             assert payload["quality"] == "high"
+            assert payload["output"] == "async-custom"
             return httpx.Response(
                 200,
                 json={
@@ -241,6 +242,7 @@ def handler(request: httpx.Request) -> httpx.Response:
     async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
         response = await client.flatten_transparencies(
             input_file,
+            output="async-custom",
             quality="high",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
diff --git a/tests/test_import_form_data.py b/tests/test_import_form_data.py
@@ -263,6 +263,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["id"] == str(input_file.id)
             assert payload["data_file_id"] == str(data_file.id)
+            assert payload["output"] == "async-custom"
             assert payload["note"] == "details"
             return httpx.Response(
                 200,
@@ -291,6 +292,7 @@ def handler(request: httpx.Request) -> httpx.Response:
         response = await client.import_form_data(
             input_file,
             data_file,
+            output="async-custom",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"note": "details"},
diff --git a/tests/test_linearize_pdf.py b/tests/test_linearize_pdf.py
@@ -195,6 +195,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["flags"] == ["a", "b"]
             assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-linearized-custom"
             return httpx.Response(
                 200,
                 json={
@@ -221,6 +222,7 @@ def handler(request: httpx.Request) -> httpx.Response:
     async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
         response = await client.linearize_pdf(
             input_file,
+            output="async-linearized-custom",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"flags": ["a", "b"]},
diff --git a/tests/test_ocr_pdf.py b/tests/test_ocr_pdf.py
@@ -227,7 +227,7 @@ async def test_async_ocr_pdf_request_customization(
     monkeypatch.delenv("PDFREST_API_KEY", raising=False)
     input_file = make_pdf_file(PdfRestFileID.generate(2))
     payload_dump = OcrPdfPayload.model_validate(
-        {"files": [input_file], "languages": ["English"]}
+        {"files": [input_file], "languages": ["English"], "output": "custom-async-ocr"}
     ).model_dump(mode="json", by_alias=True, exclude_none=True, exclude_unset=True)
     output_id = str(PdfRestFileID.generate())
     captured_timeout: dict[str, float | dict[str, float] | None] = {}
@@ -263,6 +263,7 @@ def handler(request: httpx.Request) -> httpx.Response:
     async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
         response = await client.ocr_pdf(
             input_file,
+            output="custom-async-ocr",
             extra_query={"trace": "true"},
             extra_headers={"X-Debug": "async"},
             extra_body={"debug": True},
diff --git a/tests/test_pdf_redaction_preview.py b/tests/test_pdf_redaction_preview.py
@@ -7,12 +7,17 @@
 from pydantic import ValidationError
 from pydantic_core import to_json
 
-from pdfrest import PdfRestClient
+from pdfrest import AsyncPdfRestClient, PdfRestClient
 from pdfrest.models import PdfRestFileBasedResponse, PdfRestFileID
 from pdfrest.models._internal import PdfRedactionPreviewPayload
 from pdfrest.types import PdfRedactionInstruction
 
-from .graphics_test_helpers import VALID_API_KEY, build_file_info_payload, make_pdf_file
+from .graphics_test_helpers import (
+    ASYNC_API_KEY,
+    VALID_API_KEY,
+    build_file_info_payload,
+    make_pdf_file,
+)
 
 
 @pytest.mark.parametrize(
@@ -124,3 +129,61 @@ def test_preview_redactions_requires_instruction(
         pytest.raises(ValidationError, match="at least 1 item"),
     ):
         client.preview_redactions(input_file, redactions=[])
+
+
+@pytest.mark.asyncio
+async def test_async_preview_redactions_success(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+    input_file = make_pdf_file(PdfRestFileID.generate(1))
+    output_id = str(PdfRestFileID.generate())
+    redactions: list[PdfRedactionInstruction] = [
+        {"type": "literal", "value": "Sensitive"}
+    ]
+
+    payload_model_dump = PdfRedactionPreviewPayload.model_validate(
+        {
+            "files": [input_file],
+            "redactions": redactions,
+            "output": "preview-output-async",
+        }
+    ).model_dump(mode="json", by_alias=True, exclude_none=True, exclude_unset=True)
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if (
+            request.method == "POST"
+            and request.url.path == "/pdf-with-redacted-text-preview"
+        ):
+            body = json.loads(request.content.decode("utf-8"))
+            assert body == payload_model_dump
+            return httpx.Response(
+                200,
+                json={
+                    "inputId": [input_file.id],
+                    "outputId": [output_id],
+                },
+            )
+        if request.method == "GET" and request.url.path == f"/resource/{output_id}":
+            return httpx.Response(
+                200,
+                json=build_file_info_payload(
+                    output_id, "preview-output-async.pdf", "application/pdf"
+                ),
+            )
+        msg = f"Unexpected request {request.method} {request.url}"
+        raise AssertionError(msg)
+
+    transport = httpx.MockTransport(handler)
+    async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
+        response = await client.preview_redactions(
+            input_file,
+            redactions=redactions,
+            output="preview-output-async",
+        )
+
+    assert isinstance(response, PdfRestFileBasedResponse)
+    assert str(response.input_id) == str(input_file.id)
+    assert response.output_files[0].name == "preview-output-async.pdf"
+    assert response.output_files[0].type == "application/pdf"
+    assert response.warning is None
diff --git a/tests/test_rasterize_pdf.py b/tests/test_rasterize_pdf.py
@@ -194,6 +194,7 @@ def handler(request: httpx.Request) -> httpx.Response:
             payload = json.loads(request.content.decode("utf-8"))
             assert payload["debug"] == "yes"
             assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-custom"
             return httpx.Response(
                 200,
                 json={
@@ -220,6 +221,7 @@ def handler(request: httpx.Request) -> httpx.Response:
     async with AsyncPdfRestClient(api_key=ASYNC_API_KEY, transport=transport) as client:
         response = await client.rasterize_pdf(
             input_file,
+            output="async-custom",
             extra_query={"trace": "async"},
             extra_headers={"X-Debug": "async"},
             extra_body={"debug": "yes"},
diff --git a/tests/test_split_pdf.py b/tests/test_split_pdf.py
