Require boolean terminal-status callbacks in polling helpers

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

hyperbrowser/client/polling.py

@@ -46,6 +46,14 @@ def _validate_operation_name(operation_name: str) -> None:
         raise HyperbrowserError("operation_name must not contain control characters")
 
 
+def _ensure_boolean_terminal_result(result: object, *, operation_name: str) -> bool:
+    if not isinstance(result, bool):
+        raise HyperbrowserError(
+            f"is_terminal_status must return a boolean for {operation_name}"
+        )
+    return result
+
+
 def _validate_retry_config(
     *,
     max_attempts: int,
@@ -154,7 +162,9 @@ def poll_until_terminal_status(
             time.sleep(poll_interval_seconds)
             continue
 
-        if is_terminal_status(status):
+        if _ensure_boolean_terminal_result(
+            is_terminal_status(status), operation_name=operation_name
+        ):
             return status
         if has_exceeded_max_wait(start_time, max_wait_seconds):
             raise HyperbrowserTimeoutError(
@@ -225,7 +235,9 @@ async def poll_until_terminal_status_async(
             await asyncio.sleep(poll_interval_seconds)
             continue
 
-        if is_terminal_status(status):
+        if _ensure_boolean_terminal_result(
+            is_terminal_status(status), operation_name=operation_name
+        ):
             return status
         if has_exceeded_max_wait(start_time, max_wait_seconds):
             raise HyperbrowserTimeoutError(

tests/test_polling.py

@@ -762,6 +762,17 @@ def test_polling_helpers_validate_retry_and_interval_configuration():
             max_wait_seconds=1.0,
         )
 
+    with pytest.raises(
+        HyperbrowserError, match="is_terminal_status must return a boolean"
+    ):
+        poll_until_terminal_status(
+            operation_name="invalid-terminal-callback",
+            get_status=lambda: "completed",
+            is_terminal_status=lambda value: "yes",  # type: ignore[return-value]
+            poll_interval_seconds=0.0,
+            max_wait_seconds=1.0,
+        )
+
     with pytest.raises(
         HyperbrowserError, match="max_wait_seconds must be non-negative"
     ):
@@ -857,6 +868,16 @@ async def validate_async_operation_name() -> None:
                 poll_interval_seconds=0.1,
                 max_wait_seconds=1.0,
             )
+        with pytest.raises(
+            HyperbrowserError, match="is_terminal_status must return a boolean"
+        ):
+            await poll_until_terminal_status_async(
+                operation_name="invalid-terminal-callback-async",
+                get_status=lambda: asyncio.sleep(0, result="completed"),
+                is_terminal_status=lambda value: "yes",  # type: ignore[return-value]
+                poll_interval_seconds=0.0,
+                max_wait_seconds=1.0,
+            )
         with pytest.raises(
             HyperbrowserError, match="operation_name must be 200 characters or fewer"
         ):