Merge pull request 'Reach 100% combined coverage with targeted unit tests' (#31) from cursor/balanced-100-coverage into main

Reviewed-on: https://gitea.lille-vemmelund.dk/brian/python-repositories/pulls/31

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -2,9 +2,11 @@
 
 If this PR changes files under `python_repositories/`, the **title must** start with one of:
 
-- `[patch]` or `[fix]` — bug fix (0.3.1 → 0.3.2)
+- `[patch]` or `[fix]` — bug fix (`1.2.3` → `1.2.4`)
-- `[minor]` or `[feat]` — new feature (0.3.1 → 0.4.0)
+- `[minor]` or `[feat]` — new feature (`1.2.3` → `1.3.0`)
-- `[major]` or `[breaking]` — breaking change (0.3.1 → 1.0.0)
+- `[major]` or `[breaking]` — breaking change (`1.2.3` → `2.0.0`)
+
+Current version: see [`pyproject.toml`](pyproject.toml) on `main`.
 
 Docs-, CI-, or test-only PRs do not need a prefix.
 

.gitea/workflows/test.yml

@@ -7,7 +7,7 @@ on:
   pull_request:
 
 jobs:
-  test:
+  unit-tests:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
@@ -26,10 +26,114 @@ jobs:
           UV_LINK_MODE: copy
         run: uv sync --all-extras
 
-      - name: Run pytest
+      - name: Run unit tests
+        run: |
+          # --cov-fail-under=0: partial coverage only; floor is checked in coverage-report.
+          uv run pytest tests/unit/ -m "not integration" \
+            --cov=python_repositories \
+            --cov-report= \
+            --cov-fail-under=0
+
+      - name: Upload unit coverage
+        uses: https://github.com/christopherHX/gitea-upload-artifact@v4
+        with:
+          name: coverage-unit
+          path: .coverage
+          retention-days: 1
+          compression-level: 0
+
+  integration-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
         env:
-          PYTHONPATH: .
+          UV_LINK_MODE: copy
-        run: uv run pytest --cov=python_repositories --cov-report=term-missing > coverage.txt
+        run: uv sync --all-extras
+
+      - name: Verify Docker
+        run: docker info
+
+      - name: Run integration tests
+        run: |
+          # --cov-fail-under=0: partial coverage only; floor is checked in coverage-report.
+          uv run pytest -m integration \
+            --cov=python_repositories \
+            --cov-report= \
+            --cov-fail-under=0
+
+      - name: Upload integration coverage
+        uses: https://github.com/christopherHX/gitea-upload-artifact@v4
+        with:
+          name: coverage-integration
+          path: .coverage
+          retention-days: 1
+          compression-level: 0
+
+  coverage-report:
+    # Merges unit + integration coverage and enforces fail_under from pyproject.toml.
+    needs: [unit-tests, integration-tests]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request' || github.event_name == 'push'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
+        env:
+          UV_LINK_MODE: copy
+        run: uv sync --all-extras
+
+      - name: Download unit coverage
+        uses: https://github.com/christopherHX/gitea-download-artifact@v4
+        with:
+          name: coverage-unit
+          path: coverage-unit
+
+      - name: Download integration coverage
+        uses: https://github.com/christopherHX/gitea-download-artifact@v4
+        with:
+          name: coverage-integration
+          path: coverage-integration
+
+      - name: Combine coverage report
+        run: |
+          # --fail-under=0 so the full report is always written before the floor check.
+          uv run coverage combine coverage-unit/.coverage coverage-integration/.coverage
+          uv run coverage report -m --include='python_repositories/*' --fail-under=0 > coverage.txt
+
+      - name: Show coverage report
+        run: cat coverage.txt
+
+      - name: Enforce coverage floor
+        run: |
+          # Reads fail_under from pyproject.toml; only combined coverage is evaluated here.
+          FAIL_UNDER=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['tool']['coverage']['report']['fail_under'])")
+          echo "Checking combined coverage against ${FAIL_UNDER}% floor..."
+          if uv run coverage report --fail-under="$FAIL_UNDER" --include='python_repositories/*'; then
+            echo "Coverage floor met."
+          else
+            echo "::error::Combined coverage is below the ${FAIL_UNDER}% floor"
+            exit 1
+          fi
 
       - name: Post coverage summary to PR
         if: github.event_name == 'pull_request'

README.md

@@ -148,6 +148,15 @@ uv run pytest -v                                      # full suite (requires Doc
 
 Integration tests are marked with `@pytest.mark.integration` and require Docker (testcontainers). Run unit tests alone for quick local feedback.
 
+CI runs unit and integration tests in parallel with coverage, then merges `.coverage` artifacts in a follow-up job (via [christopherhx/gitea-\*-artifact@v4](https://github.com/christopherHX/gitea-upload-artifact) for Gitea 1.26 compatibility). Combined coverage must be at least **90%**; the floor is set by [`fail_under` in `pyproject.toml`](pyproject.toml#L45-L48) and enforced after merging unit and integration coverage, not on unit-only runs.
+
+To check coverage locally (requires Docker for the full suite):
+
+```bash
+uv run pytest --cov=python_repositories --cov-report=
+uv run coverage report
+```
+
 `pre-commit` is included in the dev dependency group. `uv sync` installs the CLI, but git does not run hooks until you install them with `pre-commit install` (one time per clone). After that, commits run the checks defined in [`.pre-commit-config.yaml`](.pre-commit-config.yaml) (ruff, mypy, pyupgrade, prettier, and general file hygiene).
 
 To run all hooks manually without committing:
@@ -173,9 +182,9 @@ Docs-, CI-, and test-only PRs do not need a prefix and will not trigger a releas
 
 | Prefix                    | Bump       | Example               |
 | ------------------------- | ---------- | --------------------- |
-| `[patch]` or `[fix]`      | patch      | `0.3.1` → `0.3.2`     |
+| `[patch]` or `[fix]`      | patch      | `1.2.3` → `1.2.4`     |
-| `[minor]` or `[feat]`     | minor      | `0.3.1` → `0.4.0`     |
+| `[minor]` or `[feat]`     | minor      | `1.2.3` → `1.3.0`     |
-| `[major]` or `[breaking]` | major      | `0.3.1` → `1.0.0`     |
+| `[major]` or `[breaking]` | major      | `1.2.3` → `2.0.0`     |
 | _(none)_                  | no release | docs / CI / deps only |
 
 Example titles:
@@ -189,4 +198,4 @@ Release notes are generated from commits since the previous tag (see [`scripts/c
 
 ### Manual release
 
-You can still push a `v*.*.*` tag manually; `publish.yml` will build and publish. The current baseline version is **0.3.1**.
+You can still push a `v*.*.*` tag manually; `publish.yml` will build and publish. The current released version is in [`pyproject.toml`](pyproject.toml) (and on the latest `v*.*.*` tag).

pyproject.toml

@@ -39,6 +39,14 @@ markers = [
     "integration: tests requiring Docker containers (deselect with '-m \"not integration\"')",
 ]
 
+[tool.coverage.run]
+source = ["python_repositories"]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+precision = 2
+
 [tool.uv.sources]
 python-utils = { index = "gitea" }
 

tests/unit/adapters_test.py

@@ -117,3 +117,24 @@ def test_adapters_subpackage_lazy_import_succeeds() -> None:
     from python_repositories.adapters import RedisAdapter
 
     assert RedisAdapter.__name__ == "RedisAdapter"
+
+
+def test_adapters_dir_exposes_lazy_exports() -> None:
+    """dir(adapters) includes lazy adapter names for tab completion."""
+    import python_repositories.adapters as adapters
+
+    assert {"RedisAdapter", "MinioAdapter"}.issubset(set(dir(adapters)))
+
+
+def test_adapters_getattr_raises_for_unknown() -> None:
+    """Unknown adapter names raise AttributeError."""
+    import python_repositories.adapters as adapters
+
+    with pytest.raises(AttributeError, match="has no attribute 'NoSuchAdapter'"):
+        _ = adapters.NoSuchAdapter
+
+
+def test_top_level_dir_exposes_lazy_exports() -> None:
+    """dir(python_repositories) includes lazy adapter names for tab completion."""
+    assert "RedisAdapter" in dir(python_repositories)
+    assert "MinioAdapter" in dir(python_repositories)

tests/unit/minio_adapter_test.py

@@ -53,3 +53,41 @@ def test_raises_when_client_provided_without_config() -> None:
     mock_client = MagicMock(spec=Minio)
     with pytest.raises(ValueError, match="config is required"):
         MinioAdapter(client=mock_client)
+
+
+def test_connect_with_injected_client_succeeds() -> None:
+    mock_client = MagicMock(spec=Minio)
+    adapter = MinioAdapter(config=TEST_MINIO_CONFIG, client=mock_client)
+
+    adapter.connect()
+
+    mock_client.list_buckets.assert_called_once()
+
+
+def test_connect_with_injected_client_raises_on_failure() -> None:
+    mock_client = MagicMock(spec=Minio)
+    mock_client.list_buckets.side_effect = Exception("connection lost")
+    adapter = MinioAdapter(config=TEST_MINIO_CONFIG, client=mock_client)
+
+    with pytest.raises(ConnectionError, match="Could not connect to Minio"):
+        adapter.connect()
+
+
+def test_connect_disconnects_before_reconnect(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    stale_client = MagicMock(spec=Minio)
+    new_client = MagicMock(spec=Minio)
+    adapter = MinioAdapter(config=TEST_MINIO_CONFIG)
+    adapter._client = stale_client
+    adapter._bucket_name = None
+
+    monkeypatch.setattr(
+        "python_repositories.adapters.minio_adapter.minio.Minio",
+        lambda *args, **kwargs: new_client,
+    )
+
+    adapter.connect()
+
+    assert adapter._client is new_client
+    new_client.list_buckets.assert_called_once()

tests/unit/redis_adapter_test.py

@@ -69,3 +69,48 @@ def test_subclass_custom_env_var_name(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setenv("CUSTOM_REDIS_URI", "redis://custom:6379")
     adapter = CustomEnvRedisAdapter()
     assert adapter._config.uri == "redis://custom:6379"
+
+
+def test_connect_with_injected_client_succeeds_when_ping_ok() -> None:
+    mock_client = MagicMock(spec=redis.Redis)
+    mock_client.ping.return_value = True
+    adapter = RedisAdapter(config=TEST_REDIS_CONFIG, client=mock_client)
+
+    adapter.connect()
+
+    mock_client.ping.assert_called_once()
+
+
+def test_connect_with_injected_client_raises_when_ping_false() -> None:
+    mock_client = MagicMock(spec=redis.Redis)
+    mock_client.ping.return_value = False
+    adapter = RedisAdapter(config=TEST_REDIS_CONFIG, client=mock_client)
+
+    with pytest.raises(ConnectionError, match="Could not connect to Redis"):
+        adapter.connect()
+
+
+def test_connect_with_injected_client_raises_on_redis_error() -> None:
+    mock_client = MagicMock(spec=redis.Redis)
+    mock_client.ping.side_effect = redis.ConnectionError("connection lost")
+    adapter = RedisAdapter(config=TEST_REDIS_CONFIG, client=mock_client)
+
+    with pytest.raises(ConnectionError, match="Could not connect to Redis"):
+        adapter.connect()
+
+
+def test_connect_closes_existing_non_injected_client(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    stale_client = MagicMock(spec=redis.Redis)
+    new_client = MagicMock(spec=redis.Redis)
+    new_client.ping.return_value = True
+    adapter = RedisAdapter(config=TEST_REDIS_CONFIG)
+    adapter._client = stale_client
+
+    monkeypatch.setattr("redis.Redis.from_url", lambda *args, **kwargs: new_client)
+
+    adapter.connect()
+
+    stale_client.close.assert_called_once()
+    assert adapter._client is new_client