PDFCLOUD-5595 Improve testing speed

.github/workflows/test-and-publish.yml

@@ -7,6 +7,8 @@ on:
       - main
       - develop
       - feature-*
+  schedule:
+    - cron: "0 7 * * *"
   release:
     types:
       - published
@@ -40,7 +42,6 @@ jobs:
   tests:
     name: Tests (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
-    environment: ci-live
     strategy:
       fail-fast: false
       matrix:
@@ -61,9 +62,7 @@ jobs:
           cache-suffix: test-and-publish
           cache-dependency-glob: uv.lock
       - name: Run tests with nox
-        run: uvx nox --python ${{ matrix.python-version }} --session tests -- --no-parallel
-        env:
-          PDFREST_API_KEY: ${{ secrets.PDFREST_API_KEY }}
+        run: uvx nox --python ${{ matrix.python-version }} --session tests -- -n 5 -m "not live"
       - name: Fetch base branch for diff-cover
         if: github.event_name == 'pull_request'
         run: |
@@ -96,6 +95,37 @@ jobs:
           name: coverage-${{ matrix.python-version }}
           path: coverage/py${{ matrix.python-version }}
 
+  live-tests:
+    name: Live Tests (Python 3.11)
+    if: github.event_name == 'pull_request' || github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    environment: ci-live
+    permissions:
+      id-token: write
+      contents: read
+      packages: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: 0.9.18
+          python-version: "3.11"
+          enable-cache: true
+          cache-suffix: test-and-publish
+          cache-dependency-glob: uv.lock
+      - name: Run live tests with nox
+        run: uvx nox --python 3.11 --session tests -- -n 5 -m live
+        env:
+          PDFREST_API_KEY: ${{ secrets.PDFREST_API_KEY }}
+      - name: Upload live coverage reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-live-3.11
+          path: coverage/py3.11
+
   examples:
     name: Examples (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest

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
 

pyproject.toml

@@ -45,6 +45,9 @@ dev = [
 minversion = "7.4"
 testpaths = ["tests"]
 addopts = "-ra"
+markers = [
+    "live: tests that call the live pdfRest service",
+]
 
 [tool.ruff]
 extend-include = ["*.ipynb"]

tests/conftest.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import os
+from itertools import pairwise
+from pathlib import Path
 
 import httpx
 import pytest
@@ -12,6 +14,23 @@
 )
 
 
+def _is_live_test_path(path: Path) -> bool:
+    """Return True when the collected item lives under tests/live."""
+    lowered_parts = [part.lower() for part in path.parts]
+    return any(
+        first == "tests" and second == "live"
+        for first, second in pairwise(lowered_parts)
+    )
+
+
+def pytest_collection_modifyitems(items: list[pytest.Item]) -> None:
+    """Mark all live tests so CI can include/exclude them efficiently."""
+    for item in items:
+        item_path = getattr(item, "path", Path(str(item.fspath)))
+        if _is_live_test_path(item_path) or item.name.startswith("test_live_"):
+            item.add_marker(pytest.mark.live)
+
+
 @pytest.fixture(scope="session")
 def pdfrest_api_key() -> str:
     key = os.getenv("PDFREST_API_KEY")