acob-client 0.1.0__tar.gz

acob_client-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Local database
+db.sqlite3

acob_client-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: acob-client
+Version: 0.1.0
+Summary: Python client for Agent Controlled Browser
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ACOB Python Client
+
+The ACOB Python client controls one Chromium installation through an ACOB
+server. It uses only the Python standard library.
+
+Install it from the repository:
+
+```bash
+pip install ./client
+```
+
+Create a client with the browser ID shown in the extension popup. The endpoint
+defaults to `http://127.0.0.1:58347`:
+
+```python
+from pathlib import Path
+
+from acob import ACOBClient
+
+client = ACOBClient("0123456789ab4def8123456789abcdef")
+
+tabs = client.tabs(operation="list")
+tab = client.tabs(operation="navigate", url="https://example.com")
+tid = tab["tid"]
+
+client.click(tid, "a")
+client.keyboard(tid, text="ACOB")
+client.keyboard(tid, key="Enter")
+title = client.javascript(tid, "document.title")
+
+capture = client.screenshot(tid, full_page=True)
+png = client.download_screenshot(capture["download_url"])
+Path("screenshot.png").write_bytes(png)
+```
+
+Use a different server and operation timeout when needed:
+
+```python
+client = ACOBClient(
+    "0123456789ab4def8123456789abcdef",
+    endpoint="http://127.0.0.1:8000",
+    timeout=90,
+)
+```
+
+Action methods map directly to the API actions and payload fields. They submit
+an instruction, poll until Chromium completes it, and return the action's
+`result`.
+
+The `tabs()` method mirrors the four tab operations:
+
+```python
+tabs = client.tabs(operation="list")
+tab = client.tabs(
+    operation="navigate",
+    tid=123,
+    url="https://example.com",
+)
+tab = client.tabs(operation="focus", tid=123)
+closed = client.tabs(operation="close", tid=123)
+```
+
+`screenshot()` returns the API's screenshot metadata unchanged. Its
+`download_url` is single-use, so pass it directly to `download_screenshot()`
+when ready to consume the PNG.
+
+For lower-level queue control, use `submit()`, `wait()`, and `execute()`:
+
+```python
+instruction = client.submit("tabs", operation="list")
+terminal_response = client.wait(instruction["id"])
+
+result = client.execute("tabs", operation="list")
+```
+
+`wait()` returns the complete terminal response because that response is
+single-use. `execute()` and the action helpers raise `ACOBInstructionError`
+when Chromium reports a failed instruction. HTTP validation errors raise
+`ACOBHTTPError`; connection, protocol, and timeout failures derive from
+`ACOBError`.
+
+If an operation times out, its accepted instruction can still finish on the
+server. `ACOBTimeoutError.instruction_id` retains its ID so it can be passed to
+`wait()` again.

acob_client-0.1.0/README.md

@@ -0,0 +1,84 @@
+# ACOB Python Client
+
+The ACOB Python client controls one Chromium installation through an ACOB
+server. It uses only the Python standard library.
+
+Install it from the repository:
+
+```bash
+pip install ./client
+```
+
+Create a client with the browser ID shown in the extension popup. The endpoint
+defaults to `http://127.0.0.1:58347`:
+
+```python
+from pathlib import Path
+
+from acob import ACOBClient
+
+client = ACOBClient("0123456789ab4def8123456789abcdef")
+
+tabs = client.tabs(operation="list")
+tab = client.tabs(operation="navigate", url="https://example.com")
+tid = tab["tid"]
+
+client.click(tid, "a")
+client.keyboard(tid, text="ACOB")
+client.keyboard(tid, key="Enter")
+title = client.javascript(tid, "document.title")
+
+capture = client.screenshot(tid, full_page=True)
+png = client.download_screenshot(capture["download_url"])
+Path("screenshot.png").write_bytes(png)
+```
+
+Use a different server and operation timeout when needed:
+
+```python
+client = ACOBClient(
+    "0123456789ab4def8123456789abcdef",
+    endpoint="http://127.0.0.1:8000",
+    timeout=90,
+)
+```
+
+Action methods map directly to the API actions and payload fields. They submit
+an instruction, poll until Chromium completes it, and return the action's
+`result`.
+
+The `tabs()` method mirrors the four tab operations:
+
+```python
+tabs = client.tabs(operation="list")
+tab = client.tabs(
+    operation="navigate",
+    tid=123,
+    url="https://example.com",
+)
+tab = client.tabs(operation="focus", tid=123)
+closed = client.tabs(operation="close", tid=123)
+```
+
+`screenshot()` returns the API's screenshot metadata unchanged. Its
+`download_url` is single-use, so pass it directly to `download_screenshot()`
+when ready to consume the PNG.
+
+For lower-level queue control, use `submit()`, `wait()`, and `execute()`:
+
+```python
+instruction = client.submit("tabs", operation="list")
+terminal_response = client.wait(instruction["id"])
+
+result = client.execute("tabs", operation="list")
+```
+
+`wait()` returns the complete terminal response because that response is
+single-use. `execute()` and the action helpers raise `ACOBInstructionError`
+when Chromium reports a failed instruction. HTTP validation errors raise
+`ACOBHTTPError`; connection, protocol, and timeout failures derive from
+`ACOBError`.
+
+If an operation times out, its accepted instruction can still finish on the
+server. `ACOBTimeoutError.instruction_id` retains its ID so it can be passed to
+`wait()` again.

acob_client-0.1.0/acob/__init__.py

@@ -0,0 +1,26 @@
+from .client import (
+    DEFAULT_ENDPOINT,
+    ACOBClient,
+    ACOBConnectionError,
+    ACOBError,
+    ACOBHTTPError,
+    ACOBInstructionError,
+    ACOBProtocolError,
+    ACOBTimeoutError,
+    ScreenshotResult,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_ENDPOINT",
+    "ACOBClient",
+    "ACOBConnectionError",
+    "ACOBError",
+    "ACOBHTTPError",
+    "ACOBInstructionError",
+    "ACOBProtocolError",
+    "ACOBTimeoutError",
+    "ScreenshotResult",
+    "__version__",
+]

acob_client-0.1.0/acob/client.py

@@ -0,0 +1,430 @@
+import json
+import math
+import time
+from collections.abc import Sequence
+from typing import TypeAlias, TypedDict, cast
+from urllib.error import HTTPError, URLError
+from urllib.parse import SplitResult, urljoin, urlsplit
+from urllib.request import Request, urlopen
+from uuid import UUID
+
+DEFAULT_ENDPOINT = "http://127.0.0.1:58347"
+
+JsonValue: TypeAlias = (
+    bool | int | float | str | list["JsonValue"] | dict[str, "JsonValue"] | None
+)
+JsonObject: TypeAlias = dict[str, JsonValue]
+
+
+class ScreenshotResult(TypedDict):
+    download_url: str
+    content_type: str
+    full_page: bool
+    single_use: bool
+    tid: int
+
+
+class ACOBError(Exception):
+    """Base exception for ACOB client failures."""
+
+
+class ACOBConnectionError(ACOBError):
+    """The ACOB server could not be reached."""
+
+
+class ACOBProtocolError(ACOBError):
+    """The ACOB server returned an unexpected response."""
+
+
+class ACOBHTTPError(ACOBError):
+    """The ACOB server rejected an HTTP request."""
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        response: JsonObject | None = None,
+    ) -> None:
+        super().__init__(f"{message} (HTTP {status_code})")
+        self.status_code = status_code
+        self.response = response
+
+
+class ACOBInstructionError(ACOBError):
+    """Chromium failed to execute an accepted instruction."""
+
+    def __init__(self, instruction_id: int, response: JsonObject) -> None:
+        message = response.get("error")
+        if not isinstance(message, str) or not message:
+            message = "Browser instruction failed"
+        super().__init__(message)
+        self.instruction_id = instruction_id
+        self.response = response
+
+
+class ACOBTimeoutError(ACOBError):
+    """An instruction did not finish before the configured timeout."""
+
+    def __init__(self, instruction_id: int, timeout: float) -> None:
+        super().__init__(
+            f"Instruction {instruction_id} did not finish within {timeout:g} seconds"
+        )
+        self.instruction_id = instruction_id
+        self.timeout = timeout
+
+
+class ACOBClient:
+    """Synchronous client for controlling one ACOB browser."""
+
+    _REQUEST_TIMEOUT = 10.0
+
+    def __init__(
+        self,
+        bid: str,
+        endpoint: str | None = None,
+        *,
+        timeout: float = 60.0,
+        poll_interval: float = 0.5,
+    ) -> None:
+        self.bid = self._validate_bid(bid)
+        self.endpoint = self._validate_endpoint(
+            DEFAULT_ENDPOINT if endpoint is None else endpoint
+        )
+        self.timeout = self._positive_float(timeout, "timeout")
+        self.poll_interval = self._positive_float(
+            poll_interval,
+            "poll_interval",
+        )
+        self._instructions_url = (
+            f"{self.endpoint}/api/browsers/{self.bid}/instructions"
+        )
+
+    def submit(self, action: str, /, **payload: JsonValue) -> JsonObject:
+        """Submit an instruction without waiting for Chromium to execute it."""
+        body = dict(payload)
+        body["action"] = action
+        return self._request_json(
+            "POST",
+            f"{self._instructions_url}/",
+            body,
+            timeout=min(self._REQUEST_TIMEOUT, self.timeout),
+        )
+
+    def wait(
+        self,
+        instruction_id: int,
+        *,
+        timeout: float | None = None,
+    ) -> JsonObject:
+        """Wait for and return an instruction's one-use terminal response."""
+        if (
+            isinstance(instruction_id, bool)
+            or not isinstance(instruction_id, int)
+            or instruction_id <= 0
+        ):
+            raise ValueError("instruction_id must be a positive integer")
+
+        wait_timeout = (
+            self.timeout
+            if timeout is None
+            else self._positive_float(timeout, "timeout")
+        )
+        deadline = time.monotonic() + wait_timeout
+        instruction_url = f"{self._instructions_url}/{instruction_id}/"
+
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise ACOBTimeoutError(instruction_id, wait_timeout)
+
+            response = self._request_json(
+                "GET",
+                instruction_url,
+                timeout=min(self._REQUEST_TIMEOUT, remaining),
+            )
+            status = response.get("status")
+            if status in {"completed", "failed"}:
+                return response
+            if status not in {"pending", "processing"}:
+                raise ACOBProtocolError(
+                    f"Instruction {instruction_id} returned invalid status: {status!r}"
+                )
+
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise ACOBTimeoutError(instruction_id, wait_timeout)
+            time.sleep(min(self.poll_interval, remaining))
+
+    def execute(
+        self,
+        action: str,
+        /,
+        *,
+        timeout: float | None = None,
+        **payload: JsonValue,
+    ) -> JsonValue:
+        """Submit an action, wait for it, and return its browser result."""
+        instruction = self.submit(action, **payload)
+        instruction_id = instruction.get("id")
+        if (
+            isinstance(instruction_id, bool)
+            or not isinstance(instruction_id, int)
+            or instruction_id <= 0
+        ):
+            raise ACOBProtocolError("Created instruction did not contain a valid id")
+
+        terminal = self.wait(instruction_id, timeout=timeout)
+        if terminal.get("status") == "failed":
+            raise ACOBInstructionError(instruction_id, terminal)
+        return terminal.get("result")
+
+    def tabs(
+        self,
+        operation: str,
+        *,
+        tid: int | None = None,
+        url: str | None = None,
+        timeout: float | None = None,
+    ) -> JsonValue:
+        """Run a list, navigate, focus, or close tab operation."""
+        payload: JsonObject = {"operation": operation}
+        if tid is not None:
+            payload["tid"] = tid
+        if url is not None:
+            payload["url"] = url
+        return self.execute("tabs", timeout=timeout, **payload)
+
+    def click(
+        self,
+        tid: int,
+        selector: str,
+        *,
+        timeout: float | None = None,
+    ) -> JsonObject:
+        """Click the center of the element matching a CSS selector."""
+        return self._expect_object(
+            self.execute(
+                "click",
+                tid=tid,
+                selector=selector,
+                timeout=timeout,
+            ),
+            "click",
+        )
+
+    def keyboard(
+        self,
+        tid: int,
+        *,
+        text: str | None = None,
+        key: str | None = None,
+        modifiers: Sequence[str] | None = None,
+        timeout: float | None = None,
+    ) -> JsonObject:
+        """Insert text or dispatch one key to the focused page control."""
+        payload: JsonObject = {"tid": tid}
+        if text is not None:
+            payload["text"] = text
+        if key is not None:
+            payload["key"] = key
+        if modifiers is not None:
+            payload["modifiers"] = list(modifiers)
+        return self._expect_object(
+            self.execute("keyboard", timeout=timeout, **payload),
+            "keyboard",
+        )
+
+    def screenshot(
+        self,
+        tid: int,
+        *,
+        full_page: bool = False,
+        timeout: float | None = None,
+    ) -> ScreenshotResult:
+        """Capture a tab and return its one-use download metadata."""
+        result = self._expect_object(
+            self.execute(
+                "screenshot",
+                tid=tid,
+                full_page=full_page,
+                timeout=timeout,
+            ),
+            "screenshot",
+        )
+        return cast(ScreenshotResult, result)
+
+    def download_screenshot(self, download_url: str) -> bytes:
+        """Consume a screenshot URL returned by a low-level execute call."""
+        if not isinstance(download_url, str) or not download_url:
+            raise ValueError("download_url must be a non-empty string")
+
+        resolved_url = urljoin(f"{self.endpoint}/", download_url)
+        if self._origin(urlsplit(resolved_url)) != self._origin(
+            urlsplit(self.endpoint)
+        ):
+            raise ACOBProtocolError(
+                "Screenshot download URL points to a different server"
+            )
+        return self._request_bytes(
+            "GET",
+            resolved_url,
+            timeout=min(self._REQUEST_TIMEOUT, self.timeout),
+            accept="image/png",
+        )
+
+    def javascript(
+        self,
+        tid: int,
+        script: str,
+        *,
+        timeout: float | None = None,
+    ) -> JsonValue:
+        """Evaluate JavaScript in a tab and return its JSON-compatible value."""
+        return self.execute(
+            "javascript",
+            tid=tid,
+            script=script,
+            timeout=timeout,
+        )
+
+    def _request_json(
+        self,
+        method: str,
+        url: str,
+        body: JsonObject | None = None,
+        *,
+        timeout: float,
+    ) -> JsonObject:
+        raw = self._request_bytes(method, url, body, timeout=timeout)
+        try:
+            parsed: object = json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise ACOBProtocolError(
+                f"{method} {url} returned invalid JSON"
+            ) from error
+        if not isinstance(parsed, dict):
+            raise ACOBProtocolError(
+                f"{method} {url} returned a non-object JSON response"
+            )
+        return cast(JsonObject, parsed)
+
+    def _request_bytes(
+        self,
+        method: str,
+        url: str,
+        body: JsonObject | None = None,
+        *,
+        timeout: float,
+        accept: str = "application/json",
+    ) -> bytes:
+        headers = {"Accept": accept}
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(
+                body,
+                ensure_ascii=False,
+                separators=(",", ":"),
+            ).encode("utf-8")
+        request = Request(url, data=data, headers=headers, method=method)
+
+        try:
+            with urlopen(request, timeout=timeout) as response:
+                return response.read()
+        except HTTPError as error:
+            try:
+                response_body = error.read()
+            finally:
+                error.close()
+            parsed = self._try_parse_object(response_body)
+            message = self._http_error_message(parsed)
+            raise ACOBHTTPError(error.code, message, parsed) from None
+        except (URLError, TimeoutError, OSError) as error:
+            reason = getattr(error, "reason", error)
+            raise ACOBConnectionError(
+                f"Could not connect to ACOB at {self.endpoint}: {reason}"
+            ) from error
+
+    @staticmethod
+    def _expect_object(result: JsonValue, action: str) -> JsonObject:
+        if not isinstance(result, dict):
+            raise ACOBProtocolError(f"{action} returned an invalid result")
+        return result
+
+    @staticmethod
+    def _try_parse_object(body: bytes) -> JsonObject | None:
+        try:
+            parsed: object = json.loads(body.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return None
+        return cast(JsonObject, parsed) if isinstance(parsed, dict) else None
+
+    @staticmethod
+    def _http_error_message(response: JsonObject | None) -> str:
+        if response is None:
+            return "ACOB request failed"
+        message = response.get("error")
+        if not isinstance(message, str) or not message:
+            return "ACOB request failed"
+
+        details = response.get("details")
+        if not isinstance(details, list):
+            return message
+        rendered_details = []
+        for detail in details:
+            if not isinstance(detail, dict):
+                continue
+            field = detail.get("field")
+            detail_message = detail.get("message")
+            if isinstance(field, str) and isinstance(detail_message, str):
+                rendered_details.append(f"{field}: {detail_message}")
+        return (
+            f"{message}: {'; '.join(rendered_details)}"
+            if rendered_details
+            else message
+        )
+
+    @staticmethod
+    def _validate_bid(bid: str) -> str:
+        try:
+            parsed = UUID(bid)
+        except (ValueError, TypeError, AttributeError) as error:
+            raise ValueError(
+                "bid must be a lowercase dashless UUIDv4"
+            ) from error
+        if parsed.hex != bid or parsed.version != 4:
+            raise ValueError("bid must be a lowercase dashless UUIDv4")
+        return bid
+
+    @staticmethod
+    def _validate_endpoint(endpoint: str) -> str:
+        if not isinstance(endpoint, str) or not endpoint:
+            raise ValueError("endpoint must be a non-empty HTTP or HTTPS URL")
+        normalized = endpoint.rstrip("/")
+        try:
+            parsed = urlsplit(normalized)
+            _ = parsed.port
+        except ValueError as error:
+            raise ValueError("endpoint must be a valid HTTP or HTTPS URL") from error
+        if (
+            parsed.scheme not in {"http", "https"}
+            or parsed.hostname is None
+            or parsed.query
+            or parsed.fragment
+        ):
+            raise ValueError("endpoint must be a valid HTTP or HTTPS URL")
+        return normalized
+
+    @staticmethod
+    def _origin(url: SplitResult) -> tuple[str, str | None, int | None]:
+        default_port = 443 if url.scheme == "https" else 80
+        return url.scheme.lower(), url.hostname, url.port or default_port
+
+    @staticmethod
+    def _positive_float(value: float, name: str) -> float:
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise ValueError(f"{name} must be a positive number")
+        converted = float(value)
+        if not math.isfinite(converted) or converted <= 0:
+            raise ValueError(f"{name} must be a positive number")
+        return converted

acob_client-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "acob-client"
+version = "0.1.0"
+description = "Python client for Agent Controlled Browser"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[tool.hatch.build.targets.wheel]
+packages = ["acob"]
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "RUF", "UP"]
+
+[tool.pyright]
+include = ["acob", "tests"]
+pythonVersion = "3.10"

acob_client-0.1.0/tests/test_client.py

@@ -0,0 +1,281 @@
+import json
+import unittest
+from email.message import Message
+from io import BytesIO
+from unittest.mock import call, patch
+from urllib.error import HTTPError
+from urllib.request import Request
+
+from acob import (
+    DEFAULT_ENDPOINT,
+    ACOBClient,
+    ACOBHTTPError,
+    ACOBInstructionError,
+    ACOBProtocolError,
+    ACOBTimeoutError,
+)
+
+
+class FakeResponse:
+    def __init__(self, body):
+        self.body = (
+            body
+            if isinstance(body, bytes)
+            else json.dumps(body).encode("utf-8")
+        )
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, _exc_type, _exc_value, _traceback):
+        return False
+
+    def read(self):
+        return self.body
+
+
+class ACOBClientTests(unittest.TestCase):
+    BID = "0123456789ab4def8123456789abcdef"
+
+    def make_client(self, endpoint="http://acob.test/"):
+        return ACOBClient(
+            self.BID,
+            endpoint=endpoint,
+            timeout=5,
+            poll_interval=0.01,
+        )
+
+    def test_initializes_with_default_endpoint_and_validates_configuration(self):
+        client = ACOBClient(self.BID)
+
+        self.assertEqual(client.bid, self.BID)
+        self.assertEqual(client.endpoint, DEFAULT_ENDPOINT)
+
+        invalid_bids = (
+            "not-a-uuid",
+            "00000000000000000000000000000000",
+            "01234567-89ab-4def-8123-456789abcdef",
+            "0123456789AB4DEF8123456789ABCDEF",
+        )
+        for bid in invalid_bids:
+            with self.subTest(bid=bid), self.assertRaises(ValueError):
+                ACOBClient(bid)
+
+        for endpoint in ("", "acob.test", "ftp://acob.test", "http://acob.test?q=1"):
+            with self.subTest(endpoint=endpoint), self.assertRaises(ValueError):
+                ACOBClient(self.BID, endpoint)
+
+    def test_tabs_submits_and_consumes_terminal_response(self):
+        tab = {
+            "tid": 12,
+            "window_id": 3,
+            "active": True,
+            "focused": True,
+            "title": "Example",
+            "url": "https://example.com/",
+            "domain": "example.com",
+        }
+        responses = [
+            FakeResponse({"id": 7, "status": "pending"}),
+            FakeResponse({"id": 7, "status": "processing"}),
+            FakeResponse({"id": 7, "status": "completed", "result": [tab]}),
+        ]
+
+        with (
+            patch("acob.client.urlopen", side_effect=responses) as mocked_urlopen,
+            patch("acob.client.time.sleep") as mocked_sleep,
+        ):
+            result = self.make_client().tabs(operation="list")
+
+        self.assertEqual(result, [tab])
+        self.assertEqual(mocked_urlopen.call_count, 3)
+        self.assertEqual(mocked_sleep.call_count, 1)
+
+        submitted_request = mocked_urlopen.call_args_list[0].args[0]
+        self.assertIsInstance(submitted_request, Request)
+        self.assertEqual(submitted_request.get_method(), "POST")
+        self.assertEqual(
+            submitted_request.full_url,
+            f"http://acob.test/api/browsers/{self.BID}/instructions/",
+        )
+        self.assertEqual(
+            json.loads(submitted_request.data),
+            {"action": "tabs", "operation": "list"},
+        )
+
+        terminal_request = mocked_urlopen.call_args_list[2].args[0]
+        self.assertEqual(terminal_request.get_method(), "GET")
+        self.assertEqual(
+            terminal_request.full_url,
+            f"http://acob.test/api/browsers/{self.BID}/instructions/7/",
+        )
+
+    def test_action_methods_send_the_supported_api_payloads(self):
+        client = self.make_client()
+
+        with patch.object(client, "execute", return_value={}) as execute:
+            client.tabs(operation="list")
+            client.tabs(operation="navigate", url="https://example.com")
+            client.tabs(
+                operation="navigate",
+                tid=10,
+                url="https://example.org",
+            )
+            client.tabs(operation="focus", tid=10)
+            client.tabs(operation="close", tid=10)
+            client.click(10, "button[type=submit]")
+            client.keyboard(10, text="ACOB")
+            client.keyboard(10, key="Enter", modifiers=["ctrl", "shift"])
+            client.javascript(10, "document.title")
+
+        self.assertEqual(
+            execute.call_args_list,
+            [
+                call("tabs", timeout=None, operation="list"),
+                call(
+                    "tabs",
+                    timeout=None,
+                    operation="navigate",
+                    url="https://example.com",
+                ),
+                call(
+                    "tabs",
+                    timeout=None,
+                    operation="navigate",
+                    tid=10,
+                    url="https://example.org",
+                ),
+                call("tabs", timeout=None, operation="focus", tid=10),
+                call("tabs", timeout=None, operation="close", tid=10),
+                call(
+                    "click",
+                    tid=10,
+                    selector="button[type=submit]",
+                    timeout=None,
+                ),
+                call("keyboard", timeout=None, tid=10, text="ACOB"),
+                call(
+                    "keyboard",
+                    timeout=None,
+                    tid=10,
+                    key="Enter",
+                    modifiers=["ctrl", "shift"],
+                ),
+                call(
+                    "javascript",
+                    tid=10,
+                    script="document.title",
+                    timeout=None,
+                ),
+            ],
+        )
+
+    def test_failed_instruction_raises_with_the_consumed_response(self):
+        terminal = {
+            "id": 4,
+            "status": "failed",
+            "result": None,
+            "error": "No element matches selector: button",
+        }
+        with patch(
+            "acob.client.urlopen",
+            side_effect=[
+                FakeResponse({"id": 4, "status": "pending"}),
+                FakeResponse(terminal),
+            ],
+        ):
+            with self.assertRaises(ACOBInstructionError) as raised:
+                self.make_client().click(12, "button")
+
+        self.assertEqual(raised.exception.instruction_id, 4)
+        self.assertEqual(raised.exception.response, terminal)
+        self.assertEqual(str(raised.exception), terminal["error"])
+
+    def test_http_validation_error_exposes_status_and_response(self):
+        error_body = {
+            "error": "Invalid request",
+            "details": [
+                {
+                    "field": "javascript.script",
+                    "message": "String should have at least 1 character",
+                    "type": "string_too_short",
+                }
+            ],
+        }
+        http_error = HTTPError(
+            "http://acob.test/instructions/",
+            400,
+            "Bad Request",
+            Message(),
+            BytesIO(json.dumps(error_body).encode("utf-8")),
+        )
+
+        with patch("acob.client.urlopen", side_effect=http_error):
+            with self.assertRaises(ACOBHTTPError) as raised:
+                self.make_client().javascript(12, "")
+
+        self.assertEqual(raised.exception.status_code, 400)
+        self.assertEqual(raised.exception.response, error_body)
+        self.assertIn("javascript.script", str(raised.exception))
+
+    def test_screenshot_returns_metadata_for_an_explicit_one_use_download(self):
+        image = b"\x89PNG\r\n\x1a\nACOB"
+        download_url = f"/api/browsers/{self.BID}/screenshots/9/"
+        responses = [
+            FakeResponse({"id": 8, "status": "pending"}),
+            FakeResponse(
+                {
+                    "id": 8,
+                    "status": "completed",
+                    "result": {
+                        "download_url": download_url,
+                        "content_type": "image/png",
+                        "full_page": True,
+                        "single_use": True,
+                        "tid": 12,
+                    },
+                }
+            ),
+            FakeResponse(image),
+        ]
+
+        with patch(
+            "acob.client.urlopen",
+            side_effect=responses,
+        ) as mocked_urlopen:
+            client = self.make_client()
+            result = client.screenshot(12, full_page=True)
+            image_result = client.download_screenshot(result["download_url"])
+
+        self.assertEqual(result["download_url"], download_url)
+        self.assertEqual(image_result, image)
+        submitted_request = mocked_urlopen.call_args_list[0].args[0]
+        self.assertEqual(
+            json.loads(submitted_request.data),
+            {"action": "screenshot", "tid": 12, "full_page": True},
+        )
+        download_request = mocked_urlopen.call_args_list[2].args[0]
+        self.assertEqual(download_request.full_url, f"http://acob.test{download_url}")
+        self.assertEqual(download_request.get_method(), "GET")
+
+    def test_screenshot_rejects_a_download_on_another_origin(self):
+        with self.assertRaises(ACOBProtocolError):
+            self.make_client().download_screenshot("https://example.com/image.png")
+
+    def test_timeout_retains_instruction_id_for_later_recovery(self):
+        with (
+            patch(
+                "acob.client.urlopen",
+                return_value=FakeResponse({"id": 21, "status": "pending"}),
+            ),
+            patch("acob.client.time.monotonic", side_effect=[0, 0, 1]),
+        ):
+            with self.assertRaises(ACOBTimeoutError) as raised:
+                self.make_client().wait(21, timeout=1)
+
+        self.assertEqual(raised.exception.instruction_id, 21)
+        self.assertEqual(raised.exception.timeout, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()