tests: Add validation and request customization tests for PDF conversions

- Added tests for invalid page size handling across various conversion methods:
  `convert_html_to_pdf`, `convert_url_to_pdf`, `convert_email_to_pdf`,
  `convert_image_to_pdf`, `convert_office_to_pdf`, and
  `convert_postscript_to_pdf`.
- Introduced request customization tests, including validations for custom
  query parameters, headers, body, and timeout behavior.
- Ensured comprehensive validation of async and sync client operations.

Assisted-by: Codex

Author: datalogics-kam

tests/live/test_live_convert_html_to_pdf.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from pdfrest import AsyncPdfRestClient, PdfRestClient
+from pdfrest import AsyncPdfRestClient, PdfRestApiError, PdfRestClient
 from pdfrest.models import PdfRestFile
 
 from ..resources import get_test_resource_path
@@ -71,3 +71,38 @@ async def test_live_async_convert_html_to_pdf_success(
     assert response.warning is None
     assert str(response.input_id) == str(uploaded_html_for_pdf.id)
     assert output_file.name.startswith("live-html-file-async")
+
+
+def test_live_convert_html_to_pdf_invalid_page_size(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    uploaded_html_for_pdf: PdfRestFile,
+) -> None:
+    with (
+        PdfRestClient(
+            api_key=pdfrest_api_key,
+            base_url=pdfrest_live_base_url,
+        ) as client,
+        pytest.raises(PdfRestApiError, match=r"(?i)page_size|page size"),
+    ):
+        client.convert_html_to_pdf(
+            uploaded_html_for_pdf,
+            extra_body={"page_size": "poster"},
+        )
+
+
+@pytest.mark.asyncio
+async def test_live_async_convert_html_to_pdf_invalid_page_size(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+    uploaded_html_for_pdf: PdfRestFile,
+) -> None:
+    async with AsyncPdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        with pytest.raises(PdfRestApiError, match=r"(?i)page_size|page size"):
+            await client.convert_html_to_pdf(
+                uploaded_html_for_pdf,
+                extra_body={"page_size": "poster"},
+            )

tests/live/test_live_convert_url_to_pdf.py

@@ -33,6 +33,47 @@ def test_live_convert_url_to_pdf_success(
     assert output_file.name.startswith("live-html-url")
 
 
+@pytest.mark.asyncio
+async def test_live_async_convert_url_to_pdf_success(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+) -> None:
+    async with AsyncPdfRestClient(
+        api_key=pdfrest_api_key,
+        base_url=pdfrest_live_base_url,
+    ) as client:
+        response = await client.convert_url_to_pdf(
+            LIVE_HTML_URL,
+            output="live-html-url-async",
+            page_orientation="portrait",
+        )
+
+    assert response.output_files
+    output_file = response.output_file
+    assert output_file.type == "application/pdf"
+    assert output_file.size > 0
+    assert response.warning is None
+    assert str(response.input_id)
+    assert output_file.name.startswith("live-html-url-async")
+
+
+def test_live_convert_url_to_pdf_invalid_page_size(
+    pdfrest_api_key: str,
+    pdfrest_live_base_url: str,
+) -> None:
+    with (
+        PdfRestClient(
+            api_key=pdfrest_api_key,
+            base_url=pdfrest_live_base_url,
+        ) as client,
+        pytest.raises(PdfRestApiError, match=r"(?i)page_size|page size"),
+    ):
+        client.convert_url_to_pdf(
+            LIVE_HTML_URL,
+            extra_body={"page_size": "poster"},
+        )
+
+
 @pytest.mark.asyncio
 async def test_live_async_convert_url_to_pdf_invalid_page_size(
     pdfrest_api_key: str,

tests/test_convert_email_to_pdf.py

@@ -210,3 +210,67 @@ def handler(request: httpx.Request) -> httpx.Response:
     assert response.output_file.name == "async-converted.pdf"
     assert response.output_file.type == "application/pdf"
     assert str(response.input_id) == str(input_file.id)
+
+
+@pytest.mark.asyncio
+async def test_async_convert_email_to_pdf_request_customization(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+    input_file = make_source_file(
+        str(PdfRestFileID.generate(2)),
+        "message/rfc822",
+        "async-message.eml",
+    )
+    output_id = str(PdfRestFileID.generate())
+    captured_timeout: dict[str, float | dict[str, float] | None] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST" and request.url.path == "/pdf":
+            assert request.url.params["trace"] == "async"
+            assert request.headers["X-Debug"] == "async"
+            captured_timeout["value"] = request.extensions.get("timeout")
+            payload = json.loads(request.content.decode("utf-8"))
+            assert payload["debug"] is True
+            assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-custom"
+            return httpx.Response(
+                200,
+                json={
+                    "inputId": [input_file.id],
+                    "outputId": [output_id],
+                },
+            )
+        if request.method == "GET" and request.url.path == f"/resource/{output_id}":
+            assert request.url.params["trace"] == "async"
+            assert request.headers["X-Debug"] == "async"
+            return httpx.Response(
+                200,
+                json=build_file_info_payload(
+                    output_id, "async-custom.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.convert_email_to_pdf(
+            input_file,
+            output="async-custom",
+            extra_query={"trace": "async"},
+            extra_headers={"X-Debug": "async"},
+            extra_body={"debug": True},
+            timeout=0.6,
+        )
+
+    assert isinstance(response, PdfRestFileBasedResponse)
+    assert response.output_file.name == "async-custom.pdf"
+    timeout_value = captured_timeout["value"]
+    assert timeout_value is not None
+    if isinstance(timeout_value, dict):
+        assert all(
+            component == pytest.approx(0.6) for component in timeout_value.values()
+        )
+    else:
+        assert timeout_value == pytest.approx(0.6)

tests/test_convert_html_to_pdf.py

@@ -231,3 +231,69 @@ def handler(request: httpx.Request) -> httpx.Response:
     assert response.output_file.name == "async-converted.pdf"
     assert response.output_file.type == "application/pdf"
     assert str(response.input_id) == str(input_file.id)
+
+
+@pytest.mark.asyncio
+async def test_async_convert_html_to_pdf_request_customization(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+    input_file = make_source_file(
+        str(PdfRestFileID.generate(2)),
+        "text/html",
+        "example.html",
+    )
+    output_id = str(PdfRestFileID.generate())
+    captured_timeout: dict[str, float | dict[str, float] | None] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST" and request.url.path == "/pdf":
+            assert request.url.params["trace"] == "async"
+            assert request.headers["X-Debug"] == "async"
+            captured_timeout["value"] = request.extensions.get("timeout")
+            payload = json.loads(request.content.decode("utf-8"))
+            assert payload["debug"] is True
+            assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-custom"
+            assert payload["downsample"] == 300
+            return httpx.Response(
+                200,
+                json={
+                    "inputId": [input_file.id],
+                    "outputId": [output_id],
+                },
+            )
+        if request.method == "GET" and request.url.path == f"/resource/{output_id}":
+            assert request.url.params["trace"] == "async"
+            assert request.headers["X-Debug"] == "async"
+            return httpx.Response(
+                200,
+                json=build_file_info_payload(
+                    output_id, "async-custom.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.convert_html_to_pdf(
+            input_file,
+            output="async-custom",
+            downsample=300,
+            extra_query={"trace": "async"},
+            extra_headers={"X-Debug": "async"},
+            extra_body={"debug": True},
+            timeout=0.6,
+        )
+
+    assert isinstance(response, PdfRestFileBasedResponse)
+    assert response.output_file.name == "async-custom.pdf"
+    timeout_value = captured_timeout["value"]
+    assert timeout_value is not None
+    if isinstance(timeout_value, dict):
+        assert all(
+            component == pytest.approx(0.6) for component in timeout_value.values()
+        )
+    else:
+        assert timeout_value == pytest.approx(0.6)

tests/test_convert_image_to_pdf.py

@@ -203,3 +203,67 @@ def handler(request: httpx.Request) -> httpx.Response:
     assert response.output_file.name == "async-converted.pdf"
     assert response.output_file.type == "application/pdf"
     assert str(response.input_id) == str(input_file.id)
+
+
+@pytest.mark.asyncio
+async def test_async_convert_image_to_pdf_request_customization(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+    input_file = make_source_file(
+        str(PdfRestFileID.generate(2)),
+        "image/png",
+        "async.png",
+    )
+    output_id = str(PdfRestFileID.generate())
+    captured_timeout: dict[str, float | dict[str, float] | None] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST" and request.url.path == "/pdf":
+            assert request.url.params["trace"] == "async"
+            assert request.headers["X-Debug"] == "async"
+            captured_timeout["value"] = request.extensions.get("timeout")
+            payload = json.loads(request.content.decode("utf-8"))
+            assert payload["debug"] is True
+            assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-custom"
+            return httpx.Response(
+                200,
+                json={
+                    "inputId": [input_file.id],
+                    "outputId": [output_id],
+                },
+            )
+        if request.method == "GET" and request.url.path == f"/resource/{output_id}":
+            assert request.url.params["trace"] == "async"
+            assert request.headers["X-Debug"] == "async"
+            return httpx.Response(
+                200,
+                json=build_file_info_payload(
+                    output_id, "async-custom.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.convert_image_to_pdf(
+            input_file,
+            output="async-custom",
+            extra_query={"trace": "async"},
+            extra_headers={"X-Debug": "async"},
+            extra_body={"debug": True},
+            timeout=0.6,
+        )
+
+    assert isinstance(response, PdfRestFileBasedResponse)
+    assert response.output_file.name == "async-custom.pdf"
+    timeout_value = captured_timeout["value"]
+    assert timeout_value is not None
+    if isinstance(timeout_value, dict):
+        assert all(
+            component == pytest.approx(0.6) for component in timeout_value.values()
+        )
+    else:
+        assert timeout_value == pytest.approx(0.6)

tests/test_convert_office_to_pdf.py

@@ -234,3 +234,73 @@ def handler(request: httpx.Request) -> httpx.Response:
     assert response.output_file.name == "async-converted.pdf"
     assert response.output_file.type == "application/pdf"
     assert str(response.input_id) == str(input_file.id)
+
+
+@pytest.mark.asyncio
+async def test_async_convert_office_to_pdf_request_customization(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PDFREST_API_KEY", raising=False)
+    input_file = make_source_file(
+        str(PdfRestFileID.generate(2)),
+        "application/vnd.ms-excel",
+        "sheet.xls",
+    )
+    output_id = str(PdfRestFileID.generate())
+    captured_timeout: dict[str, float | dict[str, float] | None] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST" and request.url.path == "/pdf":
+            assert request.url.params["trace"] == "async"
+            assert request.headers["X-Debug"] == "async"
+            captured_timeout["value"] = request.extensions.get("timeout")
+            payload = json.loads(request.content.decode("utf-8"))
+            assert payload["debug"] is True
+            assert payload["compression"] == "lossy"
+            assert payload["downsample"] == 600
+            assert payload["locale"] == "US"
+            assert payload["id"] == str(input_file.id)
+            assert payload["output"] == "async-custom"
+            return httpx.Response(
+                200,
+                json={
+                    "inputId": [input_file.id],
+                    "outputId": [output_id],
+                },
+            )
+        if request.method == "GET" and request.url.path == f"/resource/{output_id}":
+            assert request.url.params["trace"] == "async"
+            assert request.headers["X-Debug"] == "async"
+            return httpx.Response(
+                200,
+                json=build_file_info_payload(
+                    output_id, "async-custom.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.convert_office_to_pdf(
+            input_file,
+            output="async-custom",
+            compression="lossy",
+            downsample=600,
+            locale="US",
+            extra_query={"trace": "async"},
+            extra_headers={"X-Debug": "async"},
+            extra_body={"debug": True},
+            timeout=0.6,
+        )
+
+    assert isinstance(response, PdfRestFileBasedResponse)
+    assert response.output_file.name == "async-custom.pdf"
+    timeout_value = captured_timeout["value"]
+    assert timeout_value is not None
+    if isinstance(timeout_value, dict):
+        assert all(
+            component == pytest.approx(0.6) for component in timeout_value.values()
+        )
+    else:
+        assert timeout_value == pytest.approx(0.6)