@ngocsangairvds/vsaf 4.0.5 → 4.0.7

package/skills/vds-skill/vds-scripts/platform_core/tests/test_errors.py

@@ -0,0 +1,201 @@
+"""Tests for vds_platform_core.errors — TDD RED phase.
+
+Run before implementation to ensure all assertions fail.
+"""
+
+from vds_platform_core.errors import (
+    AuthError,
+    ClientPermissionError,
+    ClientTimeoutError,
+    ConflictError,
+    NotFoundError,
+    RateLimitError,
+    ResponseError,
+    RetryError,
+    SettingsError,
+    TransportError,
+    VDSClientError,
+    VDSError,
+)
+
+# ---------------------------------------------------------------------------
+# isinstance / hierarchy tests
+# ---------------------------------------------------------------------------
+
+
+class TestIsinstanceChain:
+    def test_vds_error_is_runtime_error(self) -> None:
+        e = VDSError("boom")
+        assert isinstance(e, RuntimeError)
+
+    def test_vds_client_error_chain(self) -> None:
+        e = VDSClientError("x")
+        assert isinstance(e, VDSClientError)
+        assert isinstance(e, VDSError)
+        assert isinstance(e, RuntimeError)
+
+    def test_auth_error_chain(self) -> None:
+        e = AuthError("no auth")
+        assert isinstance(e, AuthError)
+        assert isinstance(e, VDSClientError)
+        assert isinstance(e, VDSError)
+        assert isinstance(e, RuntimeError)
+
+    def test_client_permission_error_chain(self) -> None:
+        e = ClientPermissionError("forbidden")
+        assert isinstance(e, ClientPermissionError)
+        assert isinstance(e, VDSClientError)
+        assert isinstance(e, VDSError)
+        assert isinstance(e, RuntimeError)
+        # Must NOT be stdlib PermissionError
+        assert not isinstance(e, PermissionError)
+
+    def test_transport_error_chain(self) -> None:
+        e = TransportError("conn refused")
+        assert isinstance(e, TransportError)
+        assert isinstance(e, VDSClientError)
+        assert isinstance(e, VDSError)
+        assert isinstance(e, RuntimeError)
+
+    def test_client_timeout_error_chain(self) -> None:
+        e = ClientTimeoutError("timed out")
+        assert isinstance(e, ClientTimeoutError)
+        assert isinstance(e, TransportError)
+        assert isinstance(e, VDSClientError)
+        assert isinstance(e, VDSError)
+        assert isinstance(e, RuntimeError)
+        # Must NOT be stdlib TimeoutError
+        assert not isinstance(e, TimeoutError)
+
+    def test_retry_error_chain(self) -> None:
+        e = RetryError("retries exhausted")
+        assert isinstance(e, RetryError)
+        assert isinstance(e, VDSClientError)
+        assert isinstance(e, VDSError)
+        assert isinstance(e, RuntimeError)
+
+    def test_response_error_chain(self) -> None:
+        e = ResponseError("bad response")
+        assert isinstance(e, ResponseError)
+        assert isinstance(e, VDSClientError)
+        assert isinstance(e, VDSError)
+        assert isinstance(e, RuntimeError)
+
+    def test_not_found_error_chain(self) -> None:
+        e = NotFoundError("not found")
+        assert isinstance(e, NotFoundError)
+        assert isinstance(e, VDSClientError)
+        assert isinstance(e, VDSError)
+        assert isinstance(e, RuntimeError)
+
+    def test_rate_limit_error_chain(self) -> None:
+        e = RateLimitError("rate limited")
+        assert isinstance(e, RateLimitError)
+        assert isinstance(e, VDSClientError)
+        assert isinstance(e, VDSError)
+        assert isinstance(e, RuntimeError)
+
+    def test_conflict_error_chain(self) -> None:
+        e = ConflictError("conflict")
+        assert isinstance(e, ConflictError)
+        assert isinstance(e, VDSClientError)
+        assert isinstance(e, VDSError)
+        assert isinstance(e, RuntimeError)
+
+    def test_settings_error_chain(self) -> None:
+        e = SettingsError("bad config")
+        assert isinstance(e, SettingsError)
+        assert isinstance(e, VDSError)
+        assert isinstance(e, RuntimeError)
+        # NOT a VDSClientError
+        assert not isinstance(e, VDSClientError)
+
+
+# ---------------------------------------------------------------------------
+# MRO diamond test
+# ---------------------------------------------------------------------------
+
+
+class SonarqubeClientError(VDSClientError):
+    """Simulated Sonarqube domain error base."""
+
+
+class SonarqubeAuthError(SonarqubeClientError, AuthError):
+    """Diamond: SonarqubeClientError + AuthError both inherit VDSClientError."""
+
+
+class TestDiamondMRO:
+    def test_sonarqube_auth_error_isinstance_both_bases(self) -> None:
+        e = SonarqubeAuthError("sonarqube auth failed")
+        assert isinstance(e, SonarqubeClientError)
+        assert isinstance(e, AuthError)
+        assert isinstance(e, VDSClientError)
+        assert isinstance(e, VDSError)
+        assert isinstance(e, RuntimeError)
+
+    def test_diamond_mro_does_not_raise(self) -> None:
+        """Constructing the diamond class must not raise TypeError."""
+        # If cooperative MRO breaks, Python raises TypeError at construction time.
+        e = SonarqubeAuthError("ok")
+        assert str(e) == "ok"
+
+
+# ---------------------------------------------------------------------------
+# context dict tests
+# ---------------------------------------------------------------------------
+
+
+class TestContextDict:
+    def test_default_context_is_empty_dict(self) -> None:
+        e = VDSError("msg")
+        assert e.context == {}
+
+    def test_context_is_stored(self) -> None:
+        ctx = {"repo": "my-repo", "attempt": 3}
+        e = VDSError("msg", context=ctx)
+        assert e.context == ctx
+
+    def test_context_on_subclass(self) -> None:
+        e = AuthError("denied", context={"user": "alice"})
+        assert e.context["user"] == "alice"
+
+    def test_context_not_mutated(self) -> None:
+        """Stored context dict is the same object (immutable-ish test)."""
+        ctx: dict[str, object] = {"key": "val"}
+        e = VDSError("m", context=ctx)
+        # context stored as-is (not deep-copied); this is expected behaviour
+        assert e.context is ctx
+
+
+# ---------------------------------------------------------------------------
+# repr / str tests
+# ---------------------------------------------------------------------------
+
+
+class TestReprStr:
+    def test_str_is_message(self) -> None:
+        e = VDSError("something went wrong")
+        assert str(e) == "something went wrong"
+
+    def test_message_propagates_through_hierarchy(self) -> None:
+        e = NotFoundError("page 42 not found")
+        assert "page 42 not found" in str(e)
+
+
+# ---------------------------------------------------------------------------
+# **kwargs MRO forwarding
+# ---------------------------------------------------------------------------
+
+
+class TestKwargsForwarding:
+    def test_no_unexpected_kwargs_error(self) -> None:
+        """VDSError must accept and pass through extra kwargs up the MRO."""
+        # RuntimeError accepts no kwargs beyond args — kwargs should NOT break it.
+        # If **kwargs is missing, cooperative MRO with multiple bases will raise.
+        e = VDSError("msg")
+        assert isinstance(e, RuntimeError)
+
+    def test_subclass_init_with_context_keyword(self) -> None:
+        """Subclasses should accept context= keyword without TypeError."""
+        e = TransportError("transport failed", context={"host": "localhost"})
+        assert e.context["host"] == "localhost"

package/skills/vds-skill/vds-scripts/platform_core/tests/test_errors_http.py

@@ -0,0 +1,74 @@
+"""Tests for vds_platform_core.http.errors — TSK-7.4."""
+
+from __future__ import annotations
+
+import pytest
+import vds_platform_core.http.errors as _err_mod
+from vds_platform_core.errors import (
+    AuthError,
+    ClientPermissionError,
+    ConflictError,
+    NotFoundError,
+    RateLimitError,
+    TransportError,
+    VDSClientError,
+)
+from vds_platform_core.http.errors import map_http_error, register_http_error_mapping
+
+
+@pytest.fixture(autouse=True)
+def _reset_service_map() -> None:
+    """Isolate _SERVICE_MAP between tests."""
+    _err_mod._SERVICE_MAP.clear()
+
+
+def test_map_401_returns_auth_error() -> None:
+    assert isinstance(map_http_error(401, "Unauthorized"), AuthError)
+
+
+def test_map_403_returns_permission_error() -> None:
+    assert isinstance(map_http_error(403, "Forbidden"), ClientPermissionError)
+
+
+def test_map_404_returns_not_found_error() -> None:
+    assert isinstance(map_http_error(404, "Not Found"), NotFoundError)
+
+
+def test_map_409_returns_conflict_error() -> None:
+    assert isinstance(map_http_error(409, "Conflict"), ConflictError)
+
+
+def test_map_429_returns_rate_limit_error() -> None:
+    assert isinstance(map_http_error(429, "Too Many Requests"), RateLimitError)
+
+
+def test_map_500_returns_transport_error() -> None:
+    assert isinstance(map_http_error(500, "Internal Server Error"), TransportError)
+
+
+def test_map_503_returns_transport_error() -> None:
+    """All 5xx statuses map to TransportError."""
+    assert isinstance(map_http_error(503, "Service Unavailable"), TransportError)
+
+
+def test_map_unknown_status_returns_vds_client_error() -> None:
+    """Unmapped statuses fall back to generic VDSClientError."""
+    err = map_http_error(418, "I'm a teapot")
+    assert type(err) is VDSClientError
+
+
+def test_service_override_beats_default() -> None:
+    """A registered service override takes precedence over the default map."""
+    register_http_error_mapping("my-service", 404, TransportError)
+    assert isinstance(map_http_error(404, "not found", service="my-service"), TransportError)
+
+
+def test_service_override_does_not_affect_other_services() -> None:
+    """A service-specific override does not leak to other services."""
+    register_http_error_mapping("svc-a", 404, ConflictError)
+    assert isinstance(map_http_error(404, "not found", service="svc-b"), NotFoundError)
+
+
+def test_error_body_stored_in_message() -> None:
+    """The response body is surfaced in the exception message."""
+    assert "token expired" in str(map_http_error(401, "token expired"))

package/skills/vds-skill/vds-scripts/platform_core/tests/test_http_settings.py

@@ -0,0 +1,116 @@
+"""Tests for HTTPClientSettings mixin — TSK-7.15."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from vds_platform_core.config import VDS_BASE_SETTINGS_CONFIG, HTTPClientSettings
+from vds_platform_core.protocols import RetryPolicy
+
+
+class TestHTTPClientSettingsDefaults:
+    def test_connect_timeout_default(self) -> None:
+        assert HTTPClientSettings().connect_timeout == 5.0
+
+    def test_read_timeout_default(self) -> None:
+        assert HTTPClientSettings().read_timeout == 30.0
+
+    def test_write_timeout_default(self) -> None:
+        assert HTTPClientSettings().write_timeout == 30.0
+
+    def test_pool_timeout_default(self) -> None:
+        assert HTTPClientSettings().pool_timeout == 5.0
+
+    def test_max_retries_default(self) -> None:
+        assert HTTPClientSettings().max_retries == 3
+
+    def test_retry_backoff_initial_default(self) -> None:
+        assert HTTPClientSettings().retry_backoff_initial == 0.5
+
+    def test_retry_backoff_multiplier_default(self) -> None:
+        assert HTTPClientSettings().retry_backoff_multiplier == 2.0
+
+    def test_retry_max_wait_default(self) -> None:
+        assert HTTPClientSettings().retry_max_wait == 60.0
+
+    def test_rate_limit_aware_default(self) -> None:
+        assert HTTPClientSettings().rate_limit_aware is True
+
+
+class TestHTTPClientSettingsValidation:
+    def test_negative_connect_timeout_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            HTTPClientSettings(connect_timeout=-1.0)
+
+    def test_negative_read_timeout_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            HTTPClientSettings(read_timeout=-0.1)
+
+    def test_max_retries_above_20_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            HTTPClientSettings(max_retries=21)
+
+    def test_max_retries_negative_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            HTTPClientSettings(max_retries=-1)
+
+    def test_retry_backoff_multiplier_below_1_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            HTTPClientSettings(retry_backoff_multiplier=0.5)
+
+
+class TestToRetryPolicy:
+    def test_returns_retry_policy_protocol(self) -> None:
+        policy = HTTPClientSettings().to_retry_policy()
+        assert isinstance(policy, RetryPolicy)
+
+    def test_max_attempts_matches_max_retries(self) -> None:
+        settings = HTTPClientSettings(max_retries=7)
+        policy = settings.to_retry_policy()
+        assert policy.can_retry(0, Exception()) or True  # can_retry is callable
+        assert getattr(policy, "max_attempts", None) == 7
+
+    def test_initial_wait_matches_backoff_initial(self) -> None:
+        settings = HTTPClientSettings(retry_backoff_initial=1.5)
+        policy = settings.to_retry_policy()
+        assert getattr(policy, "initial_wait", None) == 1.5
+
+    def test_max_wait_matches_retry_max_wait(self) -> None:
+        settings = HTTPClientSettings(retry_max_wait=120.0)
+        policy = settings.to_retry_policy()
+        assert getattr(policy, "max_wait", None) == 120.0
+
+
+class TestEnvVarOverride:
+    def test_connect_timeout_env_override(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("CONNECT_TIMEOUT", "99.0")
+        assert HTTPClientSettings().connect_timeout == 99.0
+
+    def test_max_retries_env_override(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("MAX_RETRIES", "10")
+        assert HTTPClientSettings().max_retries == 10
+
+
+class TestInheritanceComposition:
+    def test_subclass_combines_with_basesettings(self) -> None:
+        class _TestSettings(HTTPClientSettings, BaseSettings):
+            model_config = SettingsConfigDict(**VDS_BASE_SETTINGS_CONFIG, env_prefix="TST__")
+            extra_field: str = "hello"
+
+        s = _TestSettings()
+        assert s.connect_timeout == 5.0
+        assert s.extra_field == "hello"
+
+    def test_subclass_env_prefix_scopes_overrides(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        class _PrefixSettings(HTTPClientSettings, BaseSettings):
+            model_config = SettingsConfigDict(**VDS_BASE_SETTINGS_CONFIG, env_prefix="TST2__")
+
+        monkeypatch.setenv("TST2__CONNECT_TIMEOUT", "42.0")
+        assert _PrefixSettings().connect_timeout == 42.0
+
+    def test_to_retry_policy_available_on_subclass(self) -> None:
+        class _SubSettings(HTTPClientSettings, BaseSettings):
+            model_config = SettingsConfigDict(**VDS_BASE_SETTINGS_CONFIG, env_prefix="SUB__")
+
+        assert isinstance(_SubSettings().to_retry_policy(), RetryPolicy)

package/skills/vds-skill/vds-scripts/platform_core/tests/test_logging.py

@@ -0,0 +1,148 @@
+"""Tests for vds_platform_core.logging — TDD RED phase."""
+
+import json
+import logging
+import tempfile
+from pathlib import Path
+
+import structlog
+from vds_platform_core.logging import configure_structlog
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _processor_types(config: dict) -> list[str]:
+    """Return list of class names for processors in structlog config."""
+    procs = config.get("processors", [])
+    return [type(p).__name__ for p in procs]
+
+
+def _payload_for_event(stderr: str, event: str) -> dict:
+    """Extract JSON payload for a given event from stderr lines."""
+    for line in stderr.splitlines():
+        if event not in line:
+            continue
+        start = line.find("{")
+        if start == -1:
+            continue
+        try:
+            payload = json.loads(line[start:])
+        except json.JSONDecodeError:
+            continue
+        if payload.get("event") == event:
+            return payload
+    raise AssertionError(f"Event '{event}' not found in stderr")
+
+
+# ---------------------------------------------------------------------------
+# Log level mapping
+# ---------------------------------------------------------------------------
+
+
+class TestLogLevelMapping:
+    def test_default_sets_info(self) -> None:
+        configure_structlog()
+        assert logging.root.level == logging.INFO
+
+    def test_quiet_sets_warning(self) -> None:
+        configure_structlog(quiet=True)
+        assert logging.root.level == logging.WARNING
+
+    def test_verbose_sets_debug(self) -> None:
+        configure_structlog(verbose=True)
+        assert logging.root.level == logging.DEBUG
+
+    def test_verbose_overrides_quiet(self) -> None:
+        """When both are set, verbose wins (DEBUG < WARNING)."""
+        configure_structlog(quiet=True, verbose=True)
+        assert logging.root.level == logging.DEBUG
+
+
+# ---------------------------------------------------------------------------
+# Renderer selection
+# ---------------------------------------------------------------------------
+
+
+class TestRendererSelection:
+    def test_default_uses_console_renderer(self) -> None:
+        configure_structlog()
+        config = structlog.get_config()
+        proc_names = _processor_types(config)
+        assert "ConsoleRenderer" in proc_names
+
+    def test_json_mode_uses_json_renderer(self) -> None:
+        configure_structlog(json_logs=True)
+        config = structlog.get_config()
+        proc_names = _processor_types(config)
+        assert "JSONRenderer" in proc_names
+
+    def test_json_mode_not_console_renderer(self) -> None:
+        configure_structlog(json_logs=True)
+        config = structlog.get_config()
+        proc_names = _processor_types(config)
+        assert "ConsoleRenderer" not in proc_names
+
+    def test_json_mode_includes_logger_key(self, capsys) -> None:
+        configure_structlog(json_logs=True)
+        structlog.get_logger("platform_core.test").info("logger-key-check")
+
+        stderr = capsys.readouterr().err
+        payload = _payload_for_event(stderr, "logger-key-check")
+        assert payload["logger"] == "platform_core.test"
+
+
+# ---------------------------------------------------------------------------
+# File logging
+# ---------------------------------------------------------------------------
+
+
+class TestFileLogging:
+    def test_log_file_creates_handler(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            log_path = Path(tmpdir) / "test.log"
+            configure_structlog(log_file=log_path)
+            # The root logger should have a FileHandler pointing to log_path.
+            # Use .resolve() for symlink-safe comparison (macOS /tmp → /private/tmp).
+            file_handlers = [h for h in logging.root.handlers if isinstance(h, logging.FileHandler)]
+            assert any(Path(h.baseFilename).resolve() == log_path.resolve() for h in file_handlers)
+
+
+# ---------------------------------------------------------------------------
+# Idempotency / multiple calls
+# ---------------------------------------------------------------------------
+
+
+class TestIdempotency:
+    def test_multiple_calls_do_not_raise(self) -> None:
+        """configure_structlog must be callable multiple times without error."""
+        configure_structlog()
+        configure_structlog(quiet=True)
+        configure_structlog(verbose=True, json_logs=True)
+        # No assertion needed — just must not raise
+
+
+class TestExtendedApi:
+    def test_default_logger_factory_is_stdlib(self) -> None:
+        configure_structlog()
+        assert isinstance(structlog.get_config()["logger_factory"], structlog.stdlib.LoggerFactory)
+
+    def test_custom_processors_are_applied(self, capsys) -> None:
+        def inject_wave(_logger, _method_name, event_dict):
+            event_dict["wave"] = "w1"
+            return event_dict
+
+        configure_structlog(json_logs=True, custom_processors=[inject_wave])
+        structlog.get_logger("platform_core.test").info("custom-processor-check")
+
+        stderr = capsys.readouterr().err
+        payload = _payload_for_event(stderr, "custom-processor-check")
+        assert payload["wave"] == "w1"
+
+    def test_logger_factory_override_and_cache_flag(self) -> None:
+        factory = structlog.stdlib.LoggerFactory()
+        configure_structlog(logger_factory=factory, cache_logger=True)
+        config = structlog.get_config()
+        assert config["logger_factory"] is factory
+        assert config["cache_logger_on_first_use"] is True

package/skills/vds-skill/vds-scripts/platform_core/tests/test_pagination.py

@@ -0,0 +1,153 @@
+"""Tests for platform_core.http.pagination — TSK-7.17."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from vds_platform_core.http.pagination import paginate
+
+
+# ---------------------------------------------------------------------------
+# Minimal HTTPClient stub — returns pre-canned responses in order
+# ---------------------------------------------------------------------------
+class _StubClient:
+    def __init__(self, responses: list[dict[str, Any]]) -> None:
+        self._iter = iter(responses)
+        self.calls: list[dict[str, Any]] = []
+
+    async def get(self, url: str, **kwargs: Any) -> dict[str, Any]:
+        self.calls.append({"url": url, **kwargs})
+        return next(self._iter)  # type: ignore[arg-type]
+
+    async def post(self, url: str, **kwargs: Any) -> dict[str, Any]:  # pragma: no cover
+        return {}
+
+    async def aclose(self) -> None:
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Page-number style
+# ---------------------------------------------------------------------------
+class TestPageNumberPagination:
+    @pytest.mark.asyncio
+    async def test_yields_all_items_across_pages(self) -> None:
+        client = _StubClient(
+            [
+                {"items": [{"id": 1}, {"id": 2}]},
+                {"items": [{"id": 3}]},
+                {"items": []},
+            ]
+        )
+        results = [item async for item in paginate(client, "/things")]
+        assert [r["id"] for r in results] == [1, 2, 3]
+
+    @pytest.mark.asyncio
+    async def test_empty_first_page_yields_nothing(self) -> None:
+        client = _StubClient([{"items": []}])
+        results = [item async for item in paginate(client, "/empty")]
+        assert results == []
+
+    @pytest.mark.asyncio
+    async def test_page_and_size_params_sent(self) -> None:
+        client = _StubClient(
+            [
+                {"items": [{"id": 1}]},
+                {"items": []},
+            ]
+        )
+        async for _ in paginate(client, "/x", page_param="p", size_param="sz", page_size=5):
+            pass
+        first_params = client.calls[0]["params"]
+        assert first_params["p"] == 1
+        assert first_params["sz"] == 5
+        assert client.calls[1]["params"]["p"] == 2
+
+    @pytest.mark.asyncio
+    async def test_custom_items_extractor(self) -> None:
+        client = _StubClient(
+            [
+                {"results": [{"n": "a"}, {"n": "b"}]},
+                {"results": []},
+            ]
+        )
+        results = [item async for item in paginate(client, "/r", items_extractor=lambda r: r.get("results", []))]
+        assert [r["n"] for r in results] == ["a", "b"]
+
+    @pytest.mark.asyncio
+    async def test_max_pages_guard_fires(self) -> None:
+        # Returns a non-empty page every time — should hit max_pages=2
+        client = _StubClient([{"items": [{"id": i}]} for i in range(10)])
+        with pytest.raises(RuntimeError, match="max_pages=2"):
+            async for _ in paginate(client, "/inf", max_pages=2):
+                pass
+
+
+# ---------------------------------------------------------------------------
+# Cursor-based style
+# ---------------------------------------------------------------------------
+class TestCursorPagination:
+    @pytest.mark.asyncio
+    async def test_cursor_yields_items_until_none(self) -> None:
+        client = _StubClient(
+            [
+                {"items": [{"id": 1}], "next": "/things?cursor=2"},
+                {"items": [{"id": 2}], "next": "/things?cursor=3"},
+                {"items": [{"id": 3}], "next": None},
+            ]
+        )
+        results = [
+            item
+            async for item in paginate(
+                client,
+                "/things",
+                next_extractor=lambda r: r.get("next"),
+            )
+        ]
+        assert [r["id"] for r in results] == [1, 2, 3]
+
+    @pytest.mark.asyncio
+    async def test_cursor_follows_next_url(self) -> None:
+        client = _StubClient(
+            [
+                {"items": [{"id": 1}], "cursor": "tok1"},
+                {"items": [{"id": 2}], "cursor": None},
+            ]
+        )
+        async for _ in paginate(
+            client,
+            "/start",
+            next_extractor=lambda r: f"/next?cursor={r['cursor']}" if r["cursor"] else None,
+        ):
+            pass
+        assert client.calls[0]["url"] == "/start"
+        assert client.calls[1]["url"] == "/next?cursor=tok1"
+
+    @pytest.mark.asyncio
+    async def test_cursor_max_pages_guard_fires(self) -> None:
+        # Always returns a next link
+        client = _StubClient([{"items": [{"id": i}], "next": f"/p{i + 1}"} for i in range(10)])
+        with pytest.raises(RuntimeError, match="max_pages=3"):
+            async for _ in paginate(
+                client,
+                "/start",
+                next_extractor=lambda r: r.get("next"),
+                max_pages=3,
+            ):
+                pass
+
+    @pytest.mark.asyncio
+    async def test_async_for_pattern(self) -> None:
+        """Verify the typical async for usage pattern works end-to-end."""
+        client = _StubClient(
+            [
+                {"items": [{"x": 1}, {"x": 2}]},
+                {"items": []},
+            ]
+        )
+        collected: list[dict[str, Any]] = []
+        async for item in paginate(client, "/api/resources"):
+            collected.append(item)
+        assert len(collected) == 2
+        assert collected[0]["x"] == 1