browser-daemon-client 0.1.0__tar.gz

browser_daemon_client-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: browser-daemon-client
+Version: 0.1.0
+Summary: Async client for browser-daemon: Playwright runs over HTTP, sessions and logins, with nothing but aiohttp
+License-Expression: GPL-3.0-only
+Project-URL: Homepage, https://github.com/pschmitt/browser-daemon
+Project-URL: Documentation, https://github.com/pschmitt/browser-daemon/blob/main/docs/run.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9
+
+# browser-daemon-client
+
+Async Python client for [browser-daemon](https://github.com/pschmitt/browser-daemon),
+with nothing but `aiohttp`: made for Home Assistant integrations and other code
+that cannot carry Playwright.
+
+```python
+import aiohttp
+from browser_daemon_client import BrowserDaemon, RunError, step
+
+async with aiohttp.ClientSession() as http:
+    bd = BrowserDaemon(
+        http, "https://browser.example.org", secret, client="Home Assistant · HR WORKS"
+    )
+    try:
+        res = await bd.run(
+            profile="work",
+            url="https://hr.example.org/login",
+            steps=[
+                step.fill("#user", arg="user"),
+                step.fill("#password", arg="password"),
+                step.click("role=button[name='Sign in']"),
+                step.wait_for(".dashboard"),
+                step.text(".balance", as_="balance"),
+            ],
+            args={"user": user, "password": password},
+        )
+    except RunError as err:
+        print(err, err.run.url)  # err.run.screenshot: the tab, as a base64 PNG
+    else:
+        print(res.result["balance"])
+```
+
+- `run()`: a Playwright `script` (a JavaScript function expression) or `steps`,
+  in a profile's browser, a session or a throwaway browser. Runs for a profile
+  go to the node that has it. See [docs/run.md](../docs/run.md).
+- `overview()`, `find_profile()`, `sessions()`, `session()`, `create_session()`,
+  `delete_session()`, `set_idle_timeout()`, `tabs()`, `open_tab()`,
+  `close_tab()`, `export_auth()` (a page's cookies and storage; never log them).
+- `node=` sends a request to another node of the mesh through this one.
+- `read_secret()` reads the cluster secret from its file.
+
+Errors are `BrowserDaemonError` (with `status`), and for runs `RunError` and
+`RunTimeout` (with the whole answer in `.run`).
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, commit, and push a signed tag
+`python-vX.Y.Z`: the `python-client` workflow tests, builds and publishes it to
+PyPI through trusted publishing (the `pypi` environment, tags `python-v*` only;
+no token is stored anywhere).

browser_daemon_client-0.1.0/README.md

@@ -0,0 +1,51 @@
+# browser-daemon-client
+
+Async Python client for [browser-daemon](https://github.com/pschmitt/browser-daemon),
+with nothing but `aiohttp`: made for Home Assistant integrations and other code
+that cannot carry Playwright.
+
+```python
+import aiohttp
+from browser_daemon_client import BrowserDaemon, RunError, step
+
+async with aiohttp.ClientSession() as http:
+    bd = BrowserDaemon(
+        http, "https://browser.example.org", secret, client="Home Assistant · HR WORKS"
+    )
+    try:
+        res = await bd.run(
+            profile="work",
+            url="https://hr.example.org/login",
+            steps=[
+                step.fill("#user", arg="user"),
+                step.fill("#password", arg="password"),
+                step.click("role=button[name='Sign in']"),
+                step.wait_for(".dashboard"),
+                step.text(".balance", as_="balance"),
+            ],
+            args={"user": user, "password": password},
+        )
+    except RunError as err:
+        print(err, err.run.url)  # err.run.screenshot: the tab, as a base64 PNG
+    else:
+        print(res.result["balance"])
+```
+
+- `run()`: a Playwright `script` (a JavaScript function expression) or `steps`,
+  in a profile's browser, a session or a throwaway browser. Runs for a profile
+  go to the node that has it. See [docs/run.md](../docs/run.md).
+- `overview()`, `find_profile()`, `sessions()`, `session()`, `create_session()`,
+  `delete_session()`, `set_idle_timeout()`, `tabs()`, `open_tab()`,
+  `close_tab()`, `export_auth()` (a page's cookies and storage; never log them).
+- `node=` sends a request to another node of the mesh through this one.
+- `read_secret()` reads the cluster secret from its file.
+
+Errors are `BrowserDaemonError` (with `status`), and for runs `RunError` and
+`RunTimeout` (with the whole answer in `.run`).
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, commit, and push a signed tag
+`python-vX.Y.Z`: the `python-client` workflow tests, builds and publishes it to
+PyPI through trusted publishing (the `pypi` environment, tags `python-v*` only;
+no token is stored anywhere).

browser_daemon_client-0.1.0/browser_daemon_client/__init__.py

@@ -0,0 +1,398 @@
+"""Async client for browser-daemon's HTTP API, with nothing but aiohttp.
+
+Made for Home Assistant integrations and other code that cannot carry
+Playwright: :meth:`BrowserDaemon.run` runs a Playwright script or a list of
+steps on the node (see docs/run.md), and the other methods cover sessions,
+tabs and a page's login.
+
+    async with aiohttp.ClientSession() as http:
+        bd = BrowserDaemon(http, "https://browser.example.org", secret)
+        res = await bd.run(
+            profile="work",
+            url="https://example.org/login",
+            steps=[
+                step.fill("#user", arg="user"),
+                step.fill("#password", arg="password"),
+                step.click("role=button[name='Sign in']"),
+                step.text(".balance", as_="balance"),
+            ],
+            args={"user": user, "password": password},
+        )
+        print(res.result["balance"])
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import quote
+
+import aiohttp
+
+__all__ = [
+    "BrowserDaemon",
+    "BrowserDaemonError",
+    "RunError",
+    "RunResult",
+    "RunTimeout",
+    "read_secret",
+    "step",
+]
+
+SECRET_HEADER = "X-Browser-Cluster-Secret"
+DEFAULT_SECRET_FILE = "/run/secrets/browser-daemon/cluster-secret"
+
+
+class BrowserDaemonError(Exception):
+    """The daemon refused a request or could not be reached."""
+
+    def __init__(self, message: str, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+@dataclass
+class RunResult:
+    """The answer of a run (see docs/run.md, "The answer")."""
+
+    ok: bool
+    result: Any = None
+    error: str | None = None
+    timed_out: bool = False
+    steps: list[dict[str, Any]] = field(default_factory=list)
+    logs: list[dict[str, Any]] = field(default_factory=list)
+    url: str | None = None
+    page: str | None = None
+    #: The tab when the run failed: a base64 PNG.
+    screenshot: str | None = None
+    ms: int | None = None
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> RunResult:
+        return cls(
+            ok=bool(data.get("ok")),
+            result=data.get("result"),
+            error=data.get("error"),
+            timed_out=bool(data.get("timed_out")),
+            steps=data.get("steps") or [],
+            logs=data.get("logs") or [],
+            url=data.get("url"),
+            page=data.get("page"),
+            screenshot=data.get("screenshot"),
+            ms=data.get("ms"),
+        )
+
+
+class RunError(BrowserDaemonError):
+    """The script or a step failed; :attr:`run` holds the whole answer."""
+
+    def __init__(self, run: RunResult, status: int | None = None) -> None:
+        super().__init__(run.error or "The run failed", status)
+        self.run = run
+
+
+class RunTimeout(RunError):
+    """The run hit its timeout."""
+
+
+def read_secret(path: str = DEFAULT_SECRET_FILE) -> str | None:
+    """The cluster secret from a file, or None when it cannot be read."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            return f.read().strip() or None
+    except OSError:
+        return None
+
+
+class BrowserDaemon:
+    """A node of the mesh. Requests for other nodes go through it (`node=`)."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        url: str,
+        secret: str | None = None,
+        *,
+        client: str | None = None,
+        timeout: float = 30,
+    ) -> None:
+        self.session = session
+        self.url = url.rstrip("/")
+        self.secret = secret
+        #: Shown on the dashboard for sessions and runs ("Home Assistant · HR WORKS").
+        self.client = client
+        self.timeout = timeout
+        self.local_node: str | None = None
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        node: str | None = None,
+        timeout: float | None = None,
+        accept: tuple[int, ...] = (),
+        **kwargs: Any,
+    ) -> tuple[int, Any]:
+        if node and node != self.local_node:
+            path = f"/api/peers/{quote(node, safe='')}/{path.removeprefix('/api/').lstrip('/')}"
+        headers = {SECRET_HEADER: self.secret} if self.secret else {}
+        try:
+            async with self.session.request(
+                method,
+                self.url + path,
+                headers=headers,
+                timeout=aiohttp.ClientTimeout(total=timeout or self.timeout),
+                **kwargs,
+            ) as res:
+                data = await res.json(content_type=None) if res.status != 204 else None
+                if res.status < 300 or res.status in accept:
+                    return res.status, data
+                message = data.get("error") if isinstance(data, dict) else None
+                raise BrowserDaemonError(
+                    message or f"browser-daemon returned HTTP {res.status}", res.status
+                )
+        except (aiohttp.ClientError, TimeoutError) as err:
+            raise BrowserDaemonError(f"browser-daemon is unreachable: {err!r}") from err
+        except ValueError as err:
+            raise BrowserDaemonError("browser-daemon sent an unreadable answer") from err
+
+    async def _json(self, method: str, path: str, **kwargs: Any) -> Any:
+        return (await self._request(method, path, **kwargs))[1]
+
+    # The mesh
+
+    async def overview(self) -> dict[str, Any]:
+        """Nodes, sessions, profiles and tabs of the whole mesh."""
+        data = await self._json("GET", "/api/mesh/overview")
+        self.local_node = (data.get("local_node") or {}).get("name")
+        return data
+
+    async def find_profile(self, name: str) -> dict[str, Any] | None:
+        """A profile of the mesh by name, with its `node_name` and `session_id`."""
+        overview = await self.overview()
+        return next((p for p in overview.get("profiles", []) if p.get("name") == name), None)
+
+    # Runs
+
+    async def run(
+        self,
+        *,
+        script: str | None = None,
+        steps: list[dict[str, Any]] | None = None,
+        args: dict[str, Any] | None = None,
+        profile: str | None = None,
+        session_id: str | None = None,
+        tab: str | None = None,
+        url: str | None = None,
+        keep_open: bool = False,
+        persistent: bool = False,
+        timeout: float = 60,
+        action_timeout: float | None = None,
+        screenshot_on_error: bool = True,
+        idle_timeout_minutes: int | None = None,
+        node: str | None = None,
+        check: bool = True,
+    ) -> RunResult:
+        """Run a script or steps in a browser of the mesh (see docs/run.md).
+
+        Raises :class:`RunError` (:class:`RunTimeout`) when the run fails,
+        unless `check` is false, and :class:`BrowserDaemonError` when it could
+        not start.
+        """
+        body: dict[str, Any] = {
+            "script": script,
+            "steps": steps,
+            "args": args,
+            "profile": profile,
+            "session_id": session_id,
+            "tab": tab,
+            "url": url,
+            "keep_open": keep_open,
+            "persistent": persistent,
+            "timeout_seconds": max(1, round(timeout)),
+            "action_timeout_seconds": round(action_timeout) if action_timeout else None,
+            "screenshot_on_error": screenshot_on_error,
+            "idle_timeout_minutes": idle_timeout_minutes,
+            "client": self.client,
+        }
+        status, data = await self._request(
+            "POST",
+            "/api/run",
+            node=node,
+            json={k: v for k, v in body.items() if v is not None},
+            timeout=timeout + 45,
+            accept=(422, 504),
+        )
+        res = RunResult.from_json(data or {})
+        if check and not res.ok:
+            raise (RunTimeout if res.timed_out else RunError)(res, status)
+        return res
+
+    # Sessions and tabs
+
+    async def sessions(self, node: str | None = None) -> list[dict[str, Any]]:
+        return await self._json("GET", "/api/sessions", node=node)
+
+    async def session(self, session_id: str, node: str | None = None) -> dict[str, Any]:
+        """The session and its `targets` (tabs)."""
+        return await self._json("GET", f"/api/sessions/{quote(session_id, safe='')}", node=node)
+
+    async def create_session(
+        self, *, profile: str | None = None, node: str | None = None, **options: Any
+    ) -> dict[str, Any]:
+        """Start a session (or attach to the profile's); options as `POST /api/sessions`."""
+        body = {"persistent": True, "profile": profile, **options}
+        if self.client and "name" not in body:
+            body["name"] = self.client
+        return await self._json(
+            "POST",
+            "/api/sessions",
+            node=node,
+            json={k: v for k, v in body.items() if v is not None},
+        )
+
+    async def delete_session(self, session_id: str, node: str | None = None) -> None:
+        await self._request("DELETE", f"/api/sessions/{quote(session_id, safe='')}", node=node)
+
+    async def set_idle_timeout(
+        self, session_id: str, minutes: int, node: str | None = None
+    ) -> None:
+        await self._request(
+            "POST",
+            f"/api/sessions/{quote(session_id, safe='')}/idle-timeout",
+            node=node,
+            params={"minutes": minutes},
+        )
+
+    async def tabs(self, node: str | None = None) -> list[dict[str, Any]]:
+        """The pages of all sessions of the node (`/json/list`)."""
+        return await self._json("GET", "/json/list", node=node)
+
+    async def open_tab(
+        self, url: str, *, session_id: str, node: str | None = None
+    ) -> dict[str, Any]:
+        return await self._json(
+            "PUT", "/json/new", node=node, params={"url": url, "session_id": session_id}
+        )
+
+    async def close_tab(self, page_id: str, node: str | None = None) -> None:
+        await self._request("PUT", f"/json/close/{quote(page_id, safe='')}", node=node)
+
+    async def export_auth(
+        self,
+        page_id: str,
+        *,
+        session_id: str | None = None,
+        urls: list[str] | None = None,
+        storage: bool = False,
+        node: str | None = None,
+    ) -> dict[str, Any]:
+        """A page's cookies (and local/session storage): its login, for an API client.
+
+        The answer is credentials: never log it.
+        """
+        body: dict[str, Any] = {"urls": urls or [], "storage": storage}
+        if session_id:
+            body["session_id"] = session_id
+        return await self._json(
+            "POST", f"/api/pages/{quote(page_id, safe='')}/auth", node=node, json=body
+        )
+
+
+class step:
+    """Builders for run steps (docs/run.md, "Steps"). `as_` names the value."""
+
+    @staticmethod
+    def _make(action: str, as_: str | None = None, **fields: Any) -> dict[str, Any]:
+        out = {"action": action, **{k: v for k, v in fields.items() if v is not None}}
+        if as_:
+            out["as"] = as_
+        return out
+
+    @staticmethod
+    def goto(url: str, *, wait_until: str | None = None, **kw: Any) -> dict[str, Any]:
+        return step._make("goto", url=url, wait_until=wait_until, **kw)
+
+    @staticmethod
+    def click(selector: str, **kw: Any) -> dict[str, Any]:
+        return step._make("click", selector=selector, **kw)
+
+    @staticmethod
+    def fill(
+        selector: str, value: str | None = None, *, arg: str | None = None, **kw: Any
+    ) -> dict[str, Any]:
+        """Fill an input with `value`, or with `args[arg]` (keeps secrets out of the steps)."""
+        return step._make("fill", selector=selector, value=value, value_arg=arg, **kw)
+
+    @staticmethod
+    def type(
+        selector: str, value: str | None = None, *, arg: str | None = None, **kw: Any
+    ) -> dict[str, Any]:
+        return step._make("type", selector=selector, value=value, value_arg=arg, **kw)
+
+    @staticmethod
+    def press(key: str, selector: str | None = None, **kw: Any) -> dict[str, Any]:
+        return step._make("press", key=key, selector=selector, **kw)
+
+    @staticmethod
+    def select(
+        selector: str, value: Any = None, *, arg: str | None = None, **kw: Any
+    ) -> dict[str, Any]:
+        return step._make("select", selector=selector, value=value, value_arg=arg, **kw)
+
+    @staticmethod
+    def check(selector: str, checked: bool = True, **kw: Any) -> dict[str, Any]:
+        return step._make("check", selector=selector, checked=checked, **kw)
+
+    @staticmethod
+    def wait_for(
+        selector: str | None = None,
+        *,
+        state: str | None = None,
+        url: str | None = None,
+        load_state: str | None = None,
+        ms: int | None = None,
+        **kw: Any,
+    ) -> dict[str, Any]:
+        return step._make(
+            "wait_for", selector=selector, state=state, url=url, load_state=load_state, ms=ms, **kw
+        )
+
+    @staticmethod
+    def text(selector: str, *, all: bool | None = None, **kw: Any) -> dict[str, Any]:
+        return step._make("text", selector=selector, all=all, **kw)
+
+    @staticmethod
+    def value(selector: str, **kw: Any) -> dict[str, Any]:
+        return step._make("value", selector=selector, **kw)
+
+    @staticmethod
+    def attribute(selector: str, name: str, **kw: Any) -> dict[str, Any]:
+        return step._make("attribute", selector=selector, name=name, **kw)
+
+    @staticmethod
+    def count(selector: str, **kw: Any) -> dict[str, Any]:
+        return step._make("count", selector=selector, **kw)
+
+    @staticmethod
+    def visible(selector: str, **kw: Any) -> dict[str, Any]:
+        return step._make("visible", selector=selector, **kw)
+
+    @staticmethod
+    def evaluate(expression: str, arg: Any = None, **kw: Any) -> dict[str, Any]:
+        return step._make("evaluate", expression=expression, arg=arg, **kw)
+
+    @staticmethod
+    def screenshot(
+        selector: str | None = None, *, full_page: bool | None = None, **kw: Any
+    ) -> dict[str, Any]:
+        return step._make("screenshot", selector=selector, full_page=full_page, **kw)
+
+    @staticmethod
+    def url(**kw: Any) -> dict[str, Any]:
+        return step._make("url", **kw)
+
+    @staticmethod
+    def title(**kw: Any) -> dict[str, Any]:
+        return step._make("title", **kw)

browser_daemon_client-0.1.0/browser_daemon_client.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: browser-daemon-client
+Version: 0.1.0
+Summary: Async client for browser-daemon: Playwright runs over HTTP, sessions and logins, with nothing but aiohttp
+License-Expression: GPL-3.0-only
+Project-URL: Homepage, https://github.com/pschmitt/browser-daemon
+Project-URL: Documentation, https://github.com/pschmitt/browser-daemon/blob/main/docs/run.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9
+
+# browser-daemon-client
+
+Async Python client for [browser-daemon](https://github.com/pschmitt/browser-daemon),
+with nothing but `aiohttp`: made for Home Assistant integrations and other code
+that cannot carry Playwright.
+
+```python
+import aiohttp
+from browser_daemon_client import BrowserDaemon, RunError, step
+
+async with aiohttp.ClientSession() as http:
+    bd = BrowserDaemon(
+        http, "https://browser.example.org", secret, client="Home Assistant · HR WORKS"
+    )
+    try:
+        res = await bd.run(
+            profile="work",
+            url="https://hr.example.org/login",
+            steps=[
+                step.fill("#user", arg="user"),
+                step.fill("#password", arg="password"),
+                step.click("role=button[name='Sign in']"),
+                step.wait_for(".dashboard"),
+                step.text(".balance", as_="balance"),
+            ],
+            args={"user": user, "password": password},
+        )
+    except RunError as err:
+        print(err, err.run.url)  # err.run.screenshot: the tab, as a base64 PNG
+    else:
+        print(res.result["balance"])
+```
+
+- `run()`: a Playwright `script` (a JavaScript function expression) or `steps`,
+  in a profile's browser, a session or a throwaway browser. Runs for a profile
+  go to the node that has it. See [docs/run.md](../docs/run.md).
+- `overview()`, `find_profile()`, `sessions()`, `session()`, `create_session()`,
+  `delete_session()`, `set_idle_timeout()`, `tabs()`, `open_tab()`,
+  `close_tab()`, `export_auth()` (a page's cookies and storage; never log them).
+- `node=` sends a request to another node of the mesh through this one.
+- `read_secret()` reads the cluster secret from its file.
+
+Errors are `BrowserDaemonError` (with `status`), and for runs `RunError` and
+`RunTimeout` (with the whole answer in `.run`).
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, commit, and push a signed tag
+`python-vX.Y.Z`: the `python-client` workflow tests, builds and publishes it to
+PyPI through trusted publishing (the `pypi` environment, tags `python-v*` only;
+no token is stored anywhere).

browser_daemon_client-0.1.0/browser_daemon_client.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+browser_daemon_client/__init__.py
+browser_daemon_client.egg-info/PKG-INFO
+browser_daemon_client.egg-info/SOURCES.txt
+browser_daemon_client.egg-info/dependency_links.txt
+browser_daemon_client.egg-info/requires.txt
+browser_daemon_client.egg-info/top_level.txt
+tests/test_client.py

browser_daemon_client-0.1.0/browser_daemon_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

browser_daemon_client-0.1.0/browser_daemon_client.egg-info/requires.txt

@@ -0,0 +1 @@
+aiohttp>=3.9

browser_daemon_client-0.1.0/browser_daemon_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+browser_daemon_client

browser_daemon_client-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "browser-daemon-client"
+version = "0.1.0"
+description = "Async client for browser-daemon: Playwright runs over HTTP, sessions and logins, with nothing but aiohttp"
+readme = "README.md"
+license = "GPL-3.0-only"
+requires-python = ">=3.11"
+dependencies = ["aiohttp>=3.9"]
+
+[project.urls]
+Homepage = "https://github.com/pschmitt/browser-daemon"
+Documentation = "https://github.com/pschmitt/browser-daemon/blob/main/docs/run.md"
+
+[tool.setuptools]
+packages = ["browser_daemon_client"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100

browser_daemon_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

browser_daemon_client-0.1.0/tests/test_client.py

@@ -0,0 +1,164 @@
+"""The client against a fake daemon: what it sends and how it reads the answers."""
+
+from __future__ import annotations
+
+import json
+
+import aiohttp
+import pytest
+from aiohttp import web
+from aiohttp.test_utils import TestServer
+
+from browser_daemon_client import (
+    BrowserDaemon,
+    BrowserDaemonError,
+    RunError,
+    RunTimeout,
+    read_secret,
+    step,
+)
+
+
+@pytest.fixture
+async def daemon():
+    """A fake node: records every request and answers from `answers`."""
+    seen: list[dict] = []
+    answers: dict[tuple[str, str], tuple[int, object]] = {}
+
+    async def handle(request: web.Request) -> web.Response:
+        body = await request.text()
+        seen.append(
+            {
+                "method": request.method,
+                "path": request.rel_url.raw_path,
+                "query": dict(request.query),
+                "secret": request.headers.get("X-Browser-Cluster-Secret"),
+                "json": json.loads(body) if body else None,
+            }
+        )
+        status, data = answers.get(
+            (request.method, request.rel_url.raw_path), (404, {"error": "nope"})
+        )
+        return web.json_response(data, status=status)
+
+    app = web.Application()
+    app.router.add_route("*", "/{tail:.*}", handle)
+    server = TestServer(app)
+    await server.start_server()
+    async with aiohttp.ClientSession() as http:
+        bd = BrowserDaemon(http, str(server.make_url("/")), "s3cret", client="tests")
+        yield bd, seen, answers
+    await server.close()
+
+
+async def test_a_run_sends_only_what_is_set(daemon):
+    bd, seen, answers = daemon
+    answers[("POST", "/api/run")] = (200, {"ok": True, "result": {"t": "x"}, "ms": 5})
+    res = await bd.run(
+        profile="work",
+        steps=[step.fill("#pw", arg="password"), step.text("h1", as_="t")],
+        args={"password": "hunter2"},
+        timeout=30,
+    )
+    assert res.ok and res.result == {"t": "x"} and res.ms == 5
+    sent = seen[0]
+    assert sent["secret"] == "s3cret"
+    assert sent["json"] == {
+        "profile": "work",
+        "steps": [
+            {"action": "fill", "selector": "#pw", "value_arg": "password"},
+            {"action": "text", "selector": "h1", "as": "t"},
+        ],
+        "args": {"password": "hunter2"},
+        "keep_open": False,
+        "persistent": False,
+        "timeout_seconds": 30,
+        "screenshot_on_error": True,
+        "client": "tests",
+    }
+
+
+async def test_a_failed_run_raises_with_its_answer(daemon):
+    bd, _, answers = daemon
+    answers[("POST", "/api/run")] = (
+        422,
+        {
+            "ok": False,
+            "error": "step 0 (click): timeout",
+            "screenshot": "iVBOR",
+            "url": "https://x/",
+        },
+    )
+    with pytest.raises(RunError) as err:
+        await bd.run(script="async () => 1")
+    assert not isinstance(err.value, RunTimeout)
+    assert str(err.value) == "step 0 (click): timeout"
+    assert err.value.status == 422
+    assert err.value.run.screenshot == "iVBOR"
+    assert err.value.run.url == "https://x/"
+    res = await bd.run(script="async () => 1", check=False)
+    assert not res.ok
+
+
+async def test_a_timed_out_run_raises_run_timeout(daemon):
+    bd, _, answers = daemon
+    answers[("POST", "/api/run")] = (504, {"ok": False, "timed_out": True, "error": "timed out"})
+    with pytest.raises(RunTimeout):
+        await bd.run(script="async () => 1")
+
+
+async def test_a_refused_request_carries_the_daemons_message(daemon):
+    bd, _, answers = daemon
+    answers[("POST", "/api/run")] = (501, {"error": "Runs are not enabled on this node"})
+    with pytest.raises(BrowserDaemonError) as err:
+        await bd.run(script="async () => 1")
+    assert not isinstance(err.value, RunError)
+    assert err.value.status == 501
+    assert "not enabled" in str(err.value)
+
+
+async def test_requests_for_other_nodes_go_through_the_peer_route(daemon):
+    bd, seen, answers = daemon
+    answers[("GET", "/api/mesh/overview")] = (
+        200,
+        {"local_node": {"name": "here"}, "profiles": [{"name": "work", "node_name": "there"}]},
+    )
+    answers[("GET", "/api/peers/there/json/list")] = (200, [])
+    answers[("GET", "/api/sessions")] = (200, [])
+    answers[("POST", "/api/peers/there/sessions/a%2Fb/idle-timeout")] = (204, None)
+    assert (await bd.find_profile("work"))["node_name"] == "there"
+    assert await bd.tabs(node="there") == []
+    assert await bd.sessions(node="here") == []
+    await bd.set_idle_timeout("a/b", 5, node="there")
+    assert [s["path"] for s in seen[1:]] == [
+        "/api/peers/there/json/list",
+        "/api/sessions",
+        "/api/peers/there/sessions/a%2Fb/idle-timeout",
+    ]
+    assert seen[-1]["query"] == {"minutes": "5"}
+
+
+async def test_a_session_is_named_after_the_client(daemon):
+    bd, seen, answers = daemon
+    answers[("POST", "/api/sessions")] = (201, {"id": "abc"})
+    assert (await bd.create_session(profile="work", default_tabs=False))["id"] == "abc"
+    assert seen[0]["json"] == {
+        "persistent": True,
+        "profile": "work",
+        "default_tabs": False,
+        "name": "tests",
+    }
+
+
+async def test_an_unreachable_daemon_is_a_browser_daemon_error():
+    async with aiohttp.ClientSession() as http:
+        bd = BrowserDaemon(http, "http://127.0.0.1:9", timeout=2)
+        with pytest.raises(BrowserDaemonError):
+            await bd.overview()
+
+
+def test_the_secret_is_read_from_its_file(tmp_path):
+    path = tmp_path / "secret"
+    path.write_text("abc\n")
+    assert read_secret(str(path)) == "abc"
+    assert read_secret(str(tmp_path / "missing")) is None