Raven-1/tests/test_browser_driver.py
Dizhan Xue b963862e50
fix(*): keep the browser touch note, explain launch failures, isolate the test profile (#848)
## Summary

Follow-ups to #839 in the browser driver, the browser tools and the
real-browser tests.

**The touch note survives the end of an owner's binding (regression from
#839).** #839 had the driver tell the tools' `_acted` store whenever it
dropped an owner's tab binding, and the store then deleted that owner's
last-act stamp. The readback promises `note: the user interacted with
the browser since your last action` until the owner acts again, and the
end of a binding is not the end of the owner: `Browser.release()` has no
production caller, so the listener fired only on a reap after
`OWNER_IDLE_S`, on the owner's tab closing and on the browser closing.
When the reader closed an agent's tab from the panel, or the binding
idled out, the agent's next read lost the note. The listener is removed
and the driver's owner removal is back to its pre-#839 form;
`_ACTED_MAX` still bounds the store.

**A host missing a system library is told so.** The driver now answers
`Chromium is installed but cannot start here: the system library
libatk-1.0.so.0 is missing. Installing system libraries needs root, so
it is the user's step: on Debian or Ubuntu, <python> -m playwright
install-deps chromium`. Before, on x64 the loader's refusal came back as
Playwright's whole launch log, after a throwaway relaunch that could not
help; where Playwright's own dependency check runs (its linux-arm64
Chromium builds), its report suggests `playwright install-deps`, which
the driver read as "Chromium is not installed". The message says whose
step it is because tool results reach the model too.

**Only failures a fresh profile cannot fix skip the throwaway
relaunch.** The relaunch was gated on the substring "profile", and every
Playwright launch failure quotes the command line,
`--user-data-dir=<home>/.raven/browser-profile` included, so every
failure relaunched and logged "profile is busy". Every failure is still
retried once except a missing system library, Playwright's host check
and a missing executable, and the warning says the launch failed rather
than that the profile is busy. Matching Chromium's lock words instead
would be narrower and wrong under another locale: with
`LANG=zh_CN.UTF-8` a second headful launch on a held profile prints its
line in Chinese, Playwright's English rewrite of it does not fire, and
the error says only "Target page, context or browser has been closed".

**The profile path is read at launch.** `PROFILE_DIR` was computed at
import, before `tests/conftest.py` gives each test its own HOME, so the
real-browser tests used the developer's own `~/.raven/browser-profile`,
with parallel workers opening it at once; the cookie
`test_browser_real_web.py` sets turned up in a developer's own cookie
jar. `_profile_dir()` now resolves the path on each launch.

**The real-browser suites skip on a host that cannot load Chromium.**
`tests/_browser_cache.py` gains `chromium_launch_failure()`: one bare
headless launch per process, with Playwright alone. When it fails for a
missing system library, both
`tests/integration/test_browser_*real_web.py` modules skip with the
library named: the twelve `libatk-1.0.so.0` launch failures reported on
#839 become twelve skips. Any other launch failure, such as an older
build left in the cache or a timeout under load, is not a reason to
skip, and the suites fail on it as before.

`docs/browser-and-desktop.md` said a second process would get a
throwaway profile. The headless shell takes no profile lock, so a second
headless Chromium opens the same profile; the sentence now says so.

Not in this PR:

- `url_for` still predicts the landing page before the permission
prompt, so whatever moves while a person decides moves the call (the
binding-generation idea in the #600 discussion).
- Two headless Ravens share one profile with no lock; documented above,
not changed.
-
`tests/integration/test_browser_tools_real_web.py::test_two_owners_two_tabs_and_neither_takes_the_other`
hung in 2 of 73 runs of both real-browser files on main's tree -- both
times with one profile shared by every worker, never in the 24 runs with
a profile per test -- and in none of 78 runs on this branch or 240 runs
of that test alone. The cause is unknown, and counts this small cannot
credit any change here with a fix. One of the first 45 branch runs, made
before the profile change, also failed one test outright; it was not
seen again and is not explained.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Python 3.12, the repo environment with all extras, run from this tree.

- `python -m pytest tests/test_browser_driver.py
tests/test_browser_tools.py tests/test_browser_cache.py -q`: 129 passed.
With `raven/browser/driver.py` and `raven/agent/tools/browser.py` taken
from origin/main, 15 of them fail: the touch-note test for a reader's
close and for an idle binding, the launch-time profile test, the four
host-library cases, the empty-message retry, and the seven probe tests,
which call a helper main lacks.
- Each guarded construct was mutated on its own (14 mutations, among
them: no stamp after a close, a stamp pruned on a tab close, each of the
three no-retry clauses dropped, the host-library check moved after the
not-installed one, the profile path fixed at import, the probe skipping
on any failure, the probe launching on the caller's loop); each turns at
least one test red.
- Full suite, `python -m pytest -q`: 27482 passed, 116 skipped, 2
failed. Both failures are local to this box and touch nothing this
branch changes:
`tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`
(an npm elsewhere on PATH leaks past the fixture) and
`tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
(the suite runs as root, which reads the file the test makes
unreadable).
- `python -m pytest tests/integration/test_browser_real_web.py
tests/integration/test_browser_tools_real_web.py -q` with a real
Chromium: 12 passed in each of 3 runs. A guard around `_profile_dir()`
logged 39 resolutions, none under the real home, and no file under
`~/.raven/browser-profile` changed during the runs.
- Report shapes: the host-library fixtures follow real launches against
a binary built to need an absent library, with Playwright's dependency
check both skipped (the loader's refusal) and forced (both of its Linux
reports). Two headless launches on one profile: the second starts. Two
headful launches on one profile under `xvfb-run`: with
`LANG=en_US.UTF-8` the error says the profile "is already in use"; with
`LANG=zh_CN.UTF-8` it carries none of Chromium's English lock words.
- `ruff check`, `ruff format --check`, `lint-imports` (10 kept), `ty
check raven`, `scripts/check_source_language.py`,
`scripts/check_large_files.py`: all pass.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

User-visible: the touch note is reported again after the reader closes
an agent's tab or the binding idles out; a launch that fails for a
missing system library reads as one line naming it, with no throwaway
relaunch; every other launch failure still gets one throwaway relaunch,
under a different warning.

- [x] Security impact considered: the new message names a root command,
and it is worded as the user's step because tool results reach the
model.
- [x] Backward compatibility considered: `Browser.on_owner_released`
(added in #839) and the module constant `PROFILE_DIR` are removed; `git
grep` finds no reader of either outside the two files changed here.
- [x] Rollback path is clear for risky changes: revert the squash
commit; nothing persisted changes shape.

## Related Issues

Follows up #839; refs #600.

---------

Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
2026-10-03 22:09:53 +08:00

1250 lines
45 KiB
Python

"""The browser driver and its RPC surface, without launching Chromium.
Everything here is about the contract the front end and the agent depend on:
nothing starts a browser unless someone navigates, a missing optional extra is
reported rather than raised, and the input verbs reach the driver unchanged.
A real Chromium run belongs in tests/integration, not in the unit suite.
"""
from __future__ import annotations
import base64
import time
from typing import Any
import pytest
from raven.browser import driver as driver_module
from raven.browser.driver import Browser, BrowserUnavailableError, _Owner, get_browser
from raven.rpc.methods import browser as rpc_browser
@pytest.fixture(autouse=True)
def fresh_singleton(monkeypatch: pytest.MonkeyPatch) -> None:
"""Each test gets its own Browser; the module holds one per process."""
monkeypatch.setattr(driver_module, "_BROWSER", None)
monkeypatch.setattr(
rpc_browser,
"_watch",
{"send": None, "renewed": 0.0, "size": None, "quality": 70, "pending": None, "pump": None},
)
def test_get_browser_is_one_page_per_process() -> None:
"""The agent's tools and the panel have to reach the same page."""
assert get_browser() is get_browser()
def test_probe_reports_a_missing_package_with_a_recovery_path(monkeypatch: pytest.MonkeyPatch) -> None:
"""A missing package is a sentence the user can act on, not an ImportError.
No `playwright install` here: without the library that command cannot run.
The honest fix is reinstalling (install.sh's engines carry the library) or,
from a source checkout, syncing the extras."""
import builtins
real_import = builtins.__import__
def no_playwright(name: str, *a: Any, **k: Any) -> Any:
if name == "playwright":
raise ImportError("nope")
return real_import(name, *a, **k)
monkeypatch.setattr(builtins, "__import__", no_playwright)
ok, why = Browser.probe()
assert ok is False
assert "install.sh" in why
assert "uv sync --all-extras" in why
assert "playwright install chromium" not in why
async def test_state_does_not_start_a_browser() -> None:
"""The panel asks for state on every draw; that must stay free."""
b = get_browser()
state = await b.state()
assert state["started"] is False
assert b.started is False
async def test_frame_rpc_does_not_start_a_browser() -> None:
"""browser.frame is polled. A poll must never be what launches Chromium."""
out = await rpc_browser.browser_frame({})
assert out["ok"] is True
assert out["started"] is False
assert "jpeg" not in out
async def test_open_rpc_needs_a_url_or_an_action() -> None:
out = await rpc_browser.browser_open({})
assert out["ok"] is False
assert "url or action" in out["error"]
async def test_input_rpc_refuses_when_no_page_is_open() -> None:
"""Forwarding a reader's click into nothing is an error, not a launch."""
out = await rpc_browser.browser_input({"kind": "click", "x": 10, "y": 10})
assert out["ok"] is False
assert out["error"] == "no page is open"
async def test_input_rpc_rejects_an_unknown_kind(monkeypatch: pytest.MonkeyPatch) -> None:
b = get_browser()
monkeypatch.setattr(type(b), "started", property(lambda self: True))
out = await rpc_browser.browser_input({"kind": "levitate"})
assert out["ok"] is False
assert "unknown input kind" in out["error"]
async def test_input_rpc_maps_each_verb_to_the_driver(monkeypatch: pytest.MonkeyPatch) -> None:
"""The panel's four gestures have to arrive as the driver's four calls."""
b = get_browser()
monkeypatch.setattr(type(b), "started", property(lambda self: True))
seen: list[tuple[str, dict[str, Any]]] = []
async def rec(name: str, **kw: Any) -> dict[str, Any]:
seen.append((name, kw))
return {"url": "u", "title": "t", "started": True}
monkeypatch.setattr(b, "click", lambda **kw: rec("click", **kw))
monkeypatch.setattr(b, "type_text", lambda text, **kw: rec("type", text=text, **kw))
monkeypatch.setattr(b, "press", lambda key: rec("press", key=key))
monkeypatch.setattr(b, "scroll", lambda dx, dy: rec("scroll", dx=dx, dy=dy))
await rpc_browser.browser_input({"kind": "click", "x": 3, "y": 4})
await rpc_browser.browser_input({"kind": "text", "text": "hi", "ref": "ref_1"})
await rpc_browser.browser_input({"kind": "key", "key": "Enter"})
await rpc_browser.browser_input({"kind": "scroll", "dx": 0, "dy": 120})
assert [name for name, _ in seen] == ["click", "type", "press", "scroll"]
assert seen[0][1]["x"] == 3
assert seen[1][1] == {"text": "hi", "ref": "ref_1"}
assert seen[2][1] == {"key": "Enter"}
assert seen[3][1] == {"dx": 0, "dy": 120}
async def test_input_rpc_raw_verbs_are_fire_and_forget(monkeypatch: pytest.MonkeyPatch) -> None:
"""The live-view stream (drag, hover, IME text) maps to the raw driver
calls and answers a bare ok -- a state readback per pointer move would be
latency the screencast already made redundant."""
b = get_browser()
monkeypatch.setattr(type(b), "started", property(lambda self: True))
seen: list[tuple[str, Any]] = []
async def mouse(action: str, **kw: Any) -> None:
seen.append((action, kw))
async def key_event(key: str, action: str = "press") -> None:
seen.append((action, key))
async def insert_text(text: str) -> None:
seen.append(("insert", text))
monkeypatch.setattr(b, "mouse", mouse)
monkeypatch.setattr(b, "key_event", key_event)
monkeypatch.setattr(b, "insert_text", insert_text)
outs = [
await rpc_browser.browser_input({"kind": "down", "x": 5, "y": 6, "count": 2}),
await rpc_browser.browser_input({"kind": "move", "x": 7, "y": 8}),
await rpc_browser.browser_input({"kind": "up", "x": 7, "y": 8}),
await rpc_browser.browser_input({"kind": "wheel", "dx": 0, "dy": 120}),
await rpc_browser.browser_input({"kind": "keydown", "key": "Shift"}),
await rpc_browser.browser_input({"kind": "text", "text": "你好"}),
]
assert all(o == {"ok": True} for o in outs)
assert [s[0] for s in seen] == ["down", "move", "up", "wheel", "down", "insert"]
assert seen[0][1]["count"] == 2
assert seen[4] == ("down", "Shift")
assert seen[5] == ("insert", "你好")
async def test_typed_text_with_a_ref_still_fills_the_ref(monkeypatch: pytest.MonkeyPatch) -> None:
"""The agent-facing verb keeps its shape: text + ref fills that element."""
b = get_browser()
monkeypatch.setattr(type(b), "started", property(lambda self: True))
seen: dict[str, Any] = {}
async def type_text(text: str, **kw: Any) -> dict[str, Any]:
seen.update({"text": text, **kw})
return {"url": "u", "title": "t", "started": True}
monkeypatch.setattr(b, "type_text", type_text)
await rpc_browser.browser_input({"kind": "text", "text": "hi", "ref": "ref_2"})
assert seen == {"text": "hi", "ref": "ref_2"}
def test_watch_is_registered_only_with_a_notification_sink() -> None:
"""The TUI pipe has no panel to stream to; only serve gets browser.watch."""
from raven.rpc.dispatcher import Dispatcher
bare = Dispatcher()
rpc_browser.register_browser_methods(bare)
wired = Dispatcher()
async def sink(frame: dict[str, Any]) -> None: ...
rpc_browser.register_browser_methods(wired, send_frame=sink)
assert "browser.watch" not in bare._handlers
assert "browser.watch" in wired._handlers
async def test_watch_never_starts_a_browser() -> None:
"""A panel coming up to watch nothing must not launch Chromium."""
async def sink(frame: dict[str, Any]) -> None: ...
out = await rpc_browser._browser_watch({"on": True, "width": 800, "height": 600}, sink)
assert out["ok"] is True
assert out["started"] is False
assert get_browser().started is False
async def test_watch_renewal_with_the_same_size_does_not_restream(monkeypatch: pytest.MonkeyPatch) -> None:
"""The panel heartbeats its lease; a heartbeat must not restart the cast."""
b = get_browser()
monkeypatch.setattr(type(b), "started", property(lambda self: True))
monkeypatch.setattr(type(b), "streaming", property(lambda self: True))
monkeypatch.setattr(type(b), "viewport", property(lambda self: (800, 600)))
calls: list[dict[str, Any]] = []
async def start_stream(on_frame: Any, **kw: Any) -> None:
calls.append(kw)
monkeypatch.setattr(b, "start_stream", start_stream)
async def sink(frame: dict[str, Any]) -> None: ...
p = {"on": True, "width": 800, "height": 600, "quality": 55}
first = await rpc_browser._browser_watch(p, sink)
second = await rpc_browser._browser_watch(p, sink)
resized = await rpc_browser._browser_watch({**p, "width": 900}, sink)
assert first["watching"] and second["watching"] and resized["watching"]
assert len(calls) == 2
assert calls[1]["width"] == 900
def test_frame_packets_are_binary_with_a_json_header() -> None:
"""The wire shape the panel decodes: magic, header length, header, JPEG."""
import base64
import json
import struct
jpeg = b"\xff\xd8fakejpeg"
pkt = rpc_browser._packet(base64.b64encode(jpeg).decode(), "https://x.test", 640, 480, True)
assert pkt[:4] == rpc_browser.FRAME_MAGIC
(hl,) = struct.unpack(">I", pkt[4:8])
head = json.loads(pkt[8 : 8 + hl])
assert head == {"url": "https://x.test", "vw": 640, "vh": 480, "loading": True}
assert pkt[8 + hl :] == jpeg
async def test_the_pump_sends_the_newest_frame_and_drops_the_stale_one() -> None:
"""Frames that land while a send is on the wire replace the pending slot:
the reader gets the page as it is now, never a backlog replay."""
import asyncio
sent: list[bytes] = []
gate = asyncio.Event()
async def slow_send(pkt: bytes) -> None:
sent.append(pkt)
await gate.wait()
rpc_browser._watch["pending"] = b"frame-1"
task = asyncio.ensure_future(rpc_browser._pump(slow_send))
await asyncio.sleep(0)
rpc_browser._watch["pending"] = b"frame-2"
rpc_browser._watch["pending"] = b"frame-3"
gate.set()
await task
assert sent == [b"frame-1", b"frame-3"]
async def test_mode_rpc_reports_headful_without_starting_a_browser() -> None:
"""Asking for the current mode (a no-op flip) must not launch Chromium."""
out = await rpc_browser.browser_mode({"headful": False})
assert out["ok"] is True
assert out["headful"] is False
assert get_browser().started is False
async def test_set_headful_relaunches_and_carries_the_url_over(monkeypatch: pytest.MonkeyPatch) -> None:
b = get_browser()
seen: list[str] = []
async def close() -> None:
seen.append("close")
b._s = driver_module._State()
async def goto(url: str) -> dict[str, Any]:
seen.append(f"goto:{url}")
return {"url": url, "title": "", "started": True, "headful": b._headful}
monkeypatch.setattr(b, "close", close)
monkeypatch.setattr(b, "goto", goto)
b._s.page = object()
monkeypatch.setattr(type(b), "url", property(lambda self: "https://x.test/a"))
out = await b.set_headful(True)
assert seen == ["close", "goto:https://x.test/a"]
assert b._headful is True
assert out["headful"] is True
async def test_close_is_safe_before_anything_started() -> None:
"""The panel's close button must not need a browser to have existed."""
out = await rpc_browser.browser_close({})
assert out == {"ok": True, "started": False}
async def test_driver_raises_unavailable_when_the_extra_is_missing(monkeypatch: pytest.MonkeyPatch) -> None:
b = get_browser()
monkeypatch.setattr(Browser, "probe", staticmethod(lambda: (False, "playwright is not installed")))
with pytest.raises(BrowserUnavailableError):
await b._ensure()
async def test_launch_reports_missing_chromium_with_the_interpreter_command(monkeypatch: pytest.MonkeyPatch) -> None:
"""The binary hint names sys.executable: that venv has playwright in both a
uv tool install and a source checkout, while `uv sync` exists only in the
latter."""
import shlex
import sys
import types
class _Starter:
async def start(self) -> None:
raise RuntimeError("Executable doesn't exist at /nowhere/chrome")
fake_api = types.ModuleType("playwright.async_api")
fake_api.async_playwright = _Starter
fake_pkg = types.ModuleType("playwright")
fake_pkg.async_api = fake_api
monkeypatch.setitem(sys.modules, "playwright", fake_pkg)
monkeypatch.setitem(sys.modules, "playwright.async_api", fake_api)
b = get_browser()
with pytest.raises(BrowserUnavailableError) as exc:
await b._ensure()
why = str(exc.value)
assert "Chromium is not installed where this process looks for it" in why
assert why.endswith(f"{shlex.quote(sys.executable)} -m playwright install chromium"), "the fix closes the line"
# The path Playwright searched, quoted back, and the knob that moves the
# search: without them the message reads as "not installed" whichever of
# the two it was, and a sandboxed HOME sends the reader to download a
# browser they already have.
assert "(/nowhere/chrome)" in why
assert "PLAYWRIGHT_BROWSERS_PATH" in why
assert "\n" not in why, "the panel shows this in one block, where a newline collapses to a space"
# Playwright's report when the browser process cannot load a library, trimmed
# from a real launch against a binary built to need one that is absent. Its
# logged command line carries the profile path, as every launch failure's does.
_LOADER_FAILURE = (
"BrowserType.launch_persistent_context: Target page, context or browser has been closed\n"
"Browser logs:\n\n"
"<launching> /cache/chromium_headless_shell-1234/chrome-headless-shell-linux64/chrome-headless-shell "
"--disable-field-trial-config --user-data-dir=/home/u/.raven/browser-profile --remote-debugging-pipe\n"
"<launched> pid=4242\n"
"[pid=4242][err] /cache/chromium_headless_shell-1234/chrome-headless-shell-linux64/chrome-headless-shell: "
"error while loading shared libraries: libatk-1.0.so.0: cannot open shared object file: No such file or directory\n"
"Call log:\n"
" - [pid=4242] <process did exit: exitCode=127, signal=null>\n"
)
def _boxed(*lines: str) -> str:
"""playwright-core 1.62's ``wrapInASCIIBox`` at padding 1: the frame its
Linux dependency check puts around every report."""
width = max(map(len, lines))
rule = "\u2550" * (width + 2)
rows = [f"\u2551 {line.ljust(width)} \u2551" for line in lines]
return "\n".join(["\u2554" + rule + "\u2557", *rows, "\u255a" + rule + "\u255d"])
# Playwright's own Linux dependency check, in the shapes a real launch gives
# outside Docker. In playwright-core 1.62 only its linux-arm64 Chromium builds
# run it -- x64 builds unpack to a folder the check does not scan, so a missing
# library reaches the loader instead. When every missing library maps to an apt
# package it offers `install-deps`; when one does not, it lists the libraries
# and offers nothing.
_DEPENDENCY_REPORT = "BrowserType.launch_persistent_context: \n" + _boxed(
"Host system is missing dependencies to run browsers.",
"Please install them with the following command:",
"",
" playwright install-deps",
"",
"Alternatively, use apt:",
" apt-get install libgtk-4-1",
"",
"<3 Playwright Team",
)
def _unmapped_report(*libraries: str) -> str:
return "BrowserType.launch_persistent_context: \n" + _boxed(
"Host system is missing dependencies to run browsers.",
"Missing libraries:",
*(f" {library}" for library in libraries),
)
# Its Windows check, as its source assembles the report: "dependencies!", and
# remedies of its own -- a Visual C++ runtime among them, which no install-deps
# line brings.
_WINDOWS_REPORT = (
"BrowserType.launch_persistent_context: Host system is missing dependencies!\n\n"
"Some of the Universal C Runtime files cannot be found on the system. You can fix\n"
"that by installing Microsoft Visual C++ Redistributable for Visual Studio from:\n"
"https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads\n\n"
"Full list of missing libraries:\n"
" vcruntime140.dll\n"
)
def _playwright_whose_persistent_launch_fails(
monkeypatch: pytest.MonkeyPatch, text: str, calls: list[str], profiles: list[str] | None = None
) -> None:
"""A playwright module whose persistent launch raises ``text``, and whose
throwaway relaunch is recorded and then fails too. ``profiles``, when
given, collects the directory each persistent launch was handed."""
import sys
import types
class _Chromium:
async def launch_persistent_context(self, user_data_dir: str, *args: Any, **kwargs: Any) -> Any:
calls.append("persistent")
if profiles is not None:
profiles.append(user_data_dir)
raise RuntimeError(text)
async def launch(self, **kwargs: Any) -> Any:
calls.append("throwaway")
raise RuntimeError("the throwaway relaunch failed as well")
class _Playwright:
chromium = _Chromium()
async def stop(self) -> None:
pass
class _Starter:
async def start(self) -> _Playwright:
return _Playwright()
fake_api = types.ModuleType("playwright.async_api")
fake_api.async_playwright = _Starter
fake_pkg = types.ModuleType("playwright")
fake_pkg.async_api = fake_api
monkeypatch.setitem(sys.modules, "playwright", fake_pkg)
monkeypatch.setitem(sys.modules, "playwright.async_api", fake_api)
@pytest.mark.parametrize(
("report", "lacks"),
[
pytest.param(_LOADER_FAILURE, "the system library libatk-1.0.so.0 is missing", id="loader-refusal"),
pytest.param(_DEPENDENCY_REPORT, "the host is missing system libraries it needs", id="dependency-check"),
pytest.param(
_unmapped_report("libgbm.so.1"),
"the system library libgbm.so.1 is missing",
id="dependency-check-unmapped-one",
),
pytest.param(
_unmapped_report("libatk-1.0.so.0", "libgbm.so.1"),
"the system libraries libatk-1.0.so.0, libgbm.so.1 are missing",
id="dependency-check-unmapped-two",
),
],
)
async def test_a_host_missing_a_library_is_told_so_and_given_install_deps(
monkeypatch: pytest.MonkeyPatch, report: str, lacks: str
) -> None:
"""Installing Chromium again cannot fix a missing system library, so the
reader is told what the host lacks and the command that supplies it. The
dependency check's own text suggests `playwright install-deps`, which is
why the not-installed reading used to claim it."""
import shlex
import sys
calls: list[str] = []
_playwright_whose_persistent_launch_fails(monkeypatch, report, calls)
with pytest.raises(BrowserUnavailableError) as exc:
await get_browser()._ensure()
why = str(exc.value)
assert why.startswith(f"Chromium is installed but cannot start here: {lacks}.")
assert why.endswith(f"{shlex.quote(sys.executable)} -m playwright install-deps chromium")
assert "not installed" not in why
assert "the user's step" in why, "a root install is the user's to make, not the model's"
assert "\n" not in why, "the panel shows this in one block, where a newline collapses to a space"
assert calls == ["persistent"], "no profile supplies a missing library, so nothing relaunches"
async def test_the_windows_dependency_report_keeps_its_own_remedies(monkeypatch: pytest.MonkeyPatch) -> None:
"""Windows names a runtime to install, not a package command, so its
report reaches the reader whole rather than as the Linux advice."""
calls: list[str] = []
_playwright_whose_persistent_launch_fails(monkeypatch, _WINDOWS_REPORT, calls)
with pytest.raises(BrowserUnavailableError) as exc:
await get_browser()._ensure()
why = str(exc.value)
assert why.startswith("could not start Chromium: ")
assert "Microsoft Visual C++ Redistributable" in why
assert "vcruntime140.dll" in why
assert "install-deps" not in why
assert "Debian" not in why
assert calls == ["persistent"]
@pytest.mark.parametrize(
"failure",
[
"Failed to create a ProcessSingleton for your profile directory.",
"Opening in existing browser session. This usually means that the profile is already in use by "
"another instance of Chromium.",
"The profile appears to be in use by another Chromium process (4242) on another computer (box).",
"[err] SingletonLock: File exists",
"Target page, context or browser has been closed\n[pid=4242] <process did exit: exitCode=0, signal=null>",
],
ids=["singleton", "in-use", "in-use-elsewhere", "lock-file", "in-use-under-another-locale"],
)
async def test_a_failure_the_profile_may_be_behind_is_retried_once_on_a_throwaway_profile(
monkeypatch: pytest.MonkeyPatch, failure: str
) -> None:
"""A profile another instance holds is what a throwaway profile gets past.
The first four lines are Chromium's English words for that on Linux. Under
another locale Chromium translates its line, Playwright's English rewrite
of it does not fire, and the last line is all that is left: the second
browser handed off to the first and exited cleanly. So a failure nobody
recognises gets the relaunch too -- any failure but one no profile can
fix."""
calls: list[str] = []
report = f"BrowserType.launch_persistent_context: {failure}\n--user-data-dir=/home/u/.raven/browser-profile"
_playwright_whose_persistent_launch_fails(monkeypatch, report, calls)
with pytest.raises(BrowserUnavailableError) as exc:
await get_browser()._ensure()
assert calls == ["persistent", "throwaway"]
assert "the throwaway relaunch failed as well" in str(exc.value)
async def test_a_failure_with_no_message_is_retried_too(monkeypatch: pytest.MonkeyPatch) -> None:
"""A bare exception -- a timeout raised with no text -- says nothing about
the profile either way, and the warning before the relaunch must not be
what stops it."""
calls: list[str] = []
_playwright_whose_persistent_launch_fails(monkeypatch, "", calls)
with pytest.raises(BrowserUnavailableError) as exc:
await get_browser()._ensure()
assert calls == ["persistent", "throwaway"]
assert "the throwaway relaunch failed as well" in str(exc.value)
async def test_a_missing_browser_is_not_retried_on_a_throwaway_profile(monkeypatch: pytest.MonkeyPatch) -> None:
"""No profile puts a browser at the path Playwright resolved, so the
reader hears about the path rather than about a relaunch that failed."""
calls: list[str] = []
_playwright_whose_persistent_launch_fails(
monkeypatch, "BrowserType.launch_persistent_context: Executable doesn't exist at /nowhere/chrome", calls
)
with pytest.raises(BrowserUnavailableError) as exc:
await get_browser()._ensure()
assert calls == ["persistent"]
assert "Chromium is not installed where this process looks for it (/nowhere/chrome)" in str(exc.value)
async def test_the_profile_is_the_one_under_the_home_in_effect_at_launch(
monkeypatch: pytest.MonkeyPatch, tmp_path: Any
) -> None:
"""The suite hands every test its own HOME after this module is imported,
so a profile path fixed at import was the runner's own: each real-browser
test wrote its cookies into the profile its runner browses with, and
parallel workers opened that one directory at once."""
calls: list[str] = []
profiles: list[str] = []
_playwright_whose_persistent_launch_fails(monkeypatch, _LOADER_FAILURE, calls, profiles)
home = tmp_path / "home"
monkeypatch.setenv("HOME", str(home))
with pytest.raises(BrowserUnavailableError):
await get_browser()._ensure()
assert profiles == [str(home / ".raven" / "browser-profile")]
# ── tabs ────────────────────────────────────────────────────────────────
class _FakePage:
def __init__(self, url: str = "about:blank", title: str = "") -> None:
self.url = url
self._title = title
self._closed = False
self._raven_loading = False
def is_closed(self) -> bool:
return self._closed
async def title(self) -> str:
return self._title
async def close(self) -> None:
self._closed = True
async def bring_to_front(self) -> None:
pass
class _FakeContext:
def __init__(self, pages: list[Any]) -> None:
self.pages = pages
async def new_page(self) -> _FakePage:
page = _FakePage("about:blank", f"tab{len(self.pages)}")
self.pages.append(page)
return page
def _with_pages(b: Browser, pages: list[_FakePage], active: int = 0) -> None:
b._s.context = _FakeContext(pages)
b._s.page = pages[active]
async def test_tabs_lists_every_open_page_with_the_active_flag() -> None:
b = get_browser()
p1, p2 = _FakePage("https://a.test", "A"), _FakePage("https://b.test", "B")
p2._raven_loading = True
_with_pages(b, [p1, p2], active=1)
tabs = await b.tabs()
assert [(t["url"], t["active"], t["loading"]) for t in tabs] == [
("https://a.test", False, False),
("https://b.test", True, True),
]
async def test_tab_activate_switches_the_shared_page_and_restreams(monkeypatch: pytest.MonkeyPatch) -> None:
b = get_browser()
p1, p2 = _FakePage("https://a.test"), _FakePage("https://b.test")
_with_pages(b, [p1, p2], active=0)
streams: list[str] = []
async def restream() -> None:
streams.append("restream")
monkeypatch.setattr(b, "_restream", restream)
monkeypatch.setattr(b, "_state", lambda error=None, page=None: _fake_state(b))
await b.tab_activate(1)
assert b._s.page is p2
assert streams == ["restream"]
async def test_tab_close_of_the_active_tab_moves_to_a_neighbour(monkeypatch: pytest.MonkeyPatch) -> None:
b = get_browser()
p1, p2 = _FakePage("https://a.test"), _FakePage("https://b.test")
_with_pages(b, [p1, p2], active=1)
async def restream() -> None:
pass
monkeypatch.setattr(b, "_restream", restream)
monkeypatch.setattr(b, "_state", lambda error=None, page=None: _fake_state(b))
await b.tab_close(1)
assert p2._closed is True
assert b._s.page is p1
async def test_tab_close_of_the_last_tab_closes_the_browser(monkeypatch: pytest.MonkeyPatch) -> None:
b = get_browser()
p1 = _FakePage("https://a.test")
_with_pages(b, [p1], active=0)
closed: list[bool] = []
async def full_close() -> None:
closed.append(True)
b._s.context = None
b._s.page = None
monkeypatch.setattr(b, "close", full_close)
out = await b.tab_close(0)
assert closed == [True]
assert out["started"] is False
async def _fake_state(b: Browser) -> dict[str, Any]:
return {"url": b._s.page.url if b._s.page else "", "title": "", "started": True, "headful": False}
async def test_tabs_rpc_lists_without_starting_a_browser() -> None:
out = await rpc_browser.browser_tabs({"action": "list"})
assert out["ok"] is True
assert out["tabs"] == []
assert out["started"] is False
# ── the verbs, on a fake page ──────────────────────────────────────────
#
# The real-Chromium suite (tests/integration/test_browser_tools_real_web.py)
# is the acceptance for these; it needs a browser and a desktop, so what the
# unit suite pins here is the branching around each verb: which page a call
# lands on, what an owner inherits, and what a failure reports.
class _FakeLocator:
def __init__(self, page: "_ActingPage", ref: str) -> None:
self._page = page
self._ref = ref
async def evaluate(self, js: str, **kw: Any) -> Any:
return self._page.opens_tab
async def click(self, **kw: Any) -> None:
if self._page.raises:
raise RuntimeError(self._page.raises)
self._page.acts.append(("click", self._ref))
async def fill(self, text: str, **kw: Any) -> None:
self._page.acts.append(("fill", self._ref, text))
class _FakeMouse:
def __init__(self, page: "_ActingPage") -> None:
self._page = page
async def click(self, x: float, y: float, **kw: Any) -> None:
self._page.acts.append(("mouse_click", x, y))
async def wheel(self, dx: float, dy: float) -> None:
self._page.acts.append(("wheel", dx, dy))
async def move(self, x: float, y: float) -> None:
self._page.acts.append(("move", x, y))
async def down(self, **kw: Any) -> None:
self._page.acts.append(("down",))
async def up(self, **kw: Any) -> None:
self._page.acts.append(("up",))
class _FakeKeyboard:
def __init__(self, page: "_ActingPage") -> None:
self._page = page
async def type(self, text: str) -> None:
self._page.acts.append(("type", text))
async def press(self, key: str) -> None:
self._page.acts.append(("press", key))
async def down(self, key: str) -> None:
self._page.acts.append(("keydown", key))
async def up(self, key: str) -> None:
self._page.acts.append(("keyup", key))
async def insert_text(self, text: str) -> None:
self._page.acts.append(("insert", text))
class _ActingPage(_FakePage):
"""A page the acting verbs can be driven against."""
def __init__(self, url: str = "https://a.test", title: str = "A") -> None:
super().__init__(url, title)
self.acts: list[tuple[Any, ...]] = []
self.raises: str = ""
self.opens_tab = False
self.handlers: dict[str, list[Any]] = {}
self.mouse = _FakeMouse(self)
self.keyboard = _FakeKeyboard(self)
def set_default_timeout(self, ms: int) -> None:
pass
def on(self, event: str, handler: Any) -> None:
self.handlers.setdefault(event, []).append(handler)
def locator(self, selector: str) -> _FakeLocator:
return _FakeLocator(self, selector)
async def goto(self, url: str, **kw: Any) -> None:
if self.raises:
raise RuntimeError(self.raises)
self.url = url
self.acts.append(("goto", url))
async def go_back(self, **kw: Any) -> None:
self.acts.append(("back",))
async def go_forward(self, **kw: Any) -> None:
self.acts.append(("forward",))
async def reload(self, **kw: Any) -> None:
if self.raises:
raise RuntimeError(self.raises)
self.acts.append(("reload",))
async def wait_for_load_state(self, state: str, **kw: Any) -> None:
self.acts.append(("settled", state))
async def evaluate(self, js: str, *args: Any) -> Any:
if self.raises:
raise RuntimeError(self.raises)
return {"url": self.url, "title": self._title, "text": "body text", "refs": []}
async def screenshot(self, **kw: Any) -> bytes:
self.acts.append(("shot", kw.get("full_page")))
return b"\xff\xd8jpeg"
def _driving(b: Browser, pages: list[_FakePage], active: int = 0) -> None:
"""A driver whose pages are fakes and whose stream and history are inert."""
_with_pages(b, pages, active=active)
async def ensure() -> Any:
return b._s.page
async def restream() -> None:
pass
async def reach(page: Any = None) -> tuple[bool, bool]:
return True, False
async def settle() -> None:
pass
b._ensure = ensure # type: ignore[method-assign]
b._restream = restream # type: ignore[method-assign]
b._history_reach = reach # type: ignore[method-assign]
b._settle = settle # type: ignore[method-assign]
async def test_goto_reports_the_page_it_landed_on_and_an_error_as_an_error() -> None:
b = get_browser()
page = _ActingPage()
_driving(b, [page])
out = await b.goto("https://ok.test/", owner="run:a")
assert out["url"] == "https://ok.test/" and "error" not in out
assert out["can_back"] is True and out["can_forward"] is False
page.raises = "net::ERR_NAME_NOT_RESOLVED"
bad = await b.goto("https://nope.test/", owner="run:a")
assert bad["error"] == "net::ERR_NAME_NOT_RESOLVED"
async def test_a_refused_target_never_starts_a_browser() -> None:
b = get_browser()
page = _ActingPage()
_driving(b, [page])
out = await b.goto("file:///etc/passwd", owner="run:a")
assert "error" in out
assert page.acts == [], "the refusal must come before the page is touched"
async def test_history_moves_go_where_they_are_asked() -> None:
b = get_browser()
page = _ActingPage()
_driving(b, [page])
for direction, act in (("back", ("back",)), ("forward", ("forward",)), ("reload", ("reload",))):
page.acts.clear()
await b.go(direction, owner="run:a")
assert page.acts == [act]
page.raises = "boom"
assert (await b.go("reload", owner="run:a"))["error"] == "boom"
async def test_click_takes_a_ref_a_point_or_neither() -> None:
b = get_browser()
page = _ActingPage()
_driving(b, [page])
await b.click(ref="ref_3", owner="run:a")
assert ("click", '[data-raven-ref="ref_3"]') in page.acts
await b.click(x=10, y=20, owner="run:a")
assert ("mouse_click", 10, 20) in page.acts
out = await b.click(owner="run:a")
assert out["error"] == "click needs a ref or x/y"
page.raises = "element is not visible"
assert (await b.click(ref="ref_3", owner="run:a"))["error"] == "element is not visible"
async def test_typing_fills_a_ref_types_into_focus_and_submits() -> None:
b = get_browser()
page = _ActingPage()
_driving(b, [page])
await b.type_text("Ada", ref="ref_1", owner="run:a")
assert ("fill", '[data-raven-ref="ref_1"]', "Ada") in page.acts
page.acts.clear()
await b.type_text("loose text", owner="run:a")
assert page.acts == [("type", "loose text")]
page.acts.clear()
await b.type_text("query", submit=True, owner="run:a")
assert ("press", "Enter") in page.acts and ("settled", "domcontentloaded") in page.acts
async def test_press_and_scroll_report_the_page_afterwards() -> None:
b = get_browser()
page = _ActingPage()
_driving(b, [page])
out = await b.press("Escape", owner="run:a")
assert ("press", "Escape") in page.acts and out["url"] == page.url
out = await b.scroll(dx=0, dy=400, owner="run:a")
assert ("wheel", 0, 400) in page.acts and "error" not in out
async def test_a_readers_raw_input_needs_no_owner_and_no_readback() -> None:
b = get_browser()
page = _ActingPage()
_driving(b, [page])
await b.mouse("move", x=5, y=6)
await b.mouse("down")
await b.mouse("up")
await b.mouse("wheel", dx=1, dy=2)
await b.key_event("a", action="down")
await b.key_event("a", action="up")
assert page.acts == [("move", 5, 6), ("down",), ("up",), ("wheel", 1, 2), ("keydown", "a"), ("keyup", "a")]
async def test_a_snapshot_failure_is_a_state_with_an_error() -> None:
b = get_browser()
page = _ActingPage()
_driving(b, [page])
page.raises = "Execution context was destroyed"
out = await b.snapshot(owner="run:a")
assert out["error"] == "Execution context was destroyed"
async def test_a_screenshot_is_base64_and_leaves_the_front_tab_alone() -> None:
b = get_browser()
first, second = _ActingPage("https://a.test", "A"), _ActingPage("https://b.test", "B")
_driving(b, [first, second], active=1)
b._s.owners["run:a"] = _Owner(first, time.monotonic())
shot = await b.screenshot(quality=70, owner="run:a")
assert base64.b64decode(shot) == b"\xff\xd8jpeg"
assert b._s.page is second, "a read must not move what the panel shows"
async def test_an_owner_keeps_its_tab_and_can_hand_it_back() -> None:
b = get_browser()
first, second = _ActingPage("https://a.test", "A"), _ActingPage("https://b.test", "B")
_driving(b, [first, second])
assert b.url_for("run:a") == "https://a.test", "an unbound owner reads the active tab"
b._s.owners["run:a"] = _Owner(second, time.monotonic())
assert b.url_for("run:a") == "https://b.test"
b.release("run:a")
assert b.url_for("run:a") == "https://a.test"
assert not second.is_closed(), "releasing a binding leaves the tab open"
async def test_a_popup_moves_the_owner_that_opened_it() -> None:
b = get_browser()
opener, popup = _ActingPage("https://a.test", "A"), _ActingPage("https://p.test", "P")
async def opened_by() -> Any:
return opener
popup.opener = opened_by # type: ignore[attr-defined]
_driving(b, [opener])
b._s.owners["run:a"] = _Owner(opener, time.monotonic())
b._s.context.pages.append(popup)
await b._adopt(popup)
assert b._s.owners["run:a"].page is popup
assert b._s.page is popup
async def test_the_touch_stamp_is_the_readers_and_not_an_owners() -> None:
b = get_browser()
page = _ActingPage()
_driving(b, [page])
when = time.monotonic()
await b.click(x=1, y=1, owner="run:a")
assert b.touched_since(when) is False, "an owner's act is not the reader's hand"
await b.mouse("move", x=2, y=2)
assert b.touched_since(when) is True
async def test_a_tab_whose_title_cannot_be_read_is_still_listed() -> None:
b = get_browser()
page = _ActingPage("https://a.test", "A")
async def no_title() -> str:
raise RuntimeError("Execution context was destroyed")
page.title = no_title # type: ignore[method-assign]
_driving(b, [page])
tabs = await b.tabs()
assert tabs == [{"index": 0, "url": "https://a.test", "title": "", "active": True, "loading": False}]
async def test_the_tab_verbs_open_switch_and_close(monkeypatch: pytest.MonkeyPatch) -> None:
b = get_browser()
first, second = _ActingPage("https://a.test", "A"), _ActingPage("https://b.test", "B")
_driving(b, [first, second])
opened = _ActingPage("about:blank", "")
async def new_page() -> Any:
b._s.context.pages.append(opened)
return opened
b._s.context.new_page = new_page # type: ignore[attr-defined]
await b.tab_new(owner="run:a")
assert b._s.owners["run:a"].page is opened
assert b._s.page is opened
switched = await b.tab_activate(1, owner="run:a")
assert b._s.page is second and "error" not in switched
closed = await b.tab_close(1, owner="run:a")
assert second.is_closed() and "error" not in closed
assert (await b.tab_activate(9, owner="run:a"))["error"] == "no tab 9"
assert (await b.tab_close(9, owner="run:a"))["error"] == "no tab 9"
async def test_the_tab_limit_answers_rather_than_opening_the_twenty_first() -> None:
b = get_browser()
pages = [_ActingPage(f"https://{i}.test") for i in range(driver_module.MAX_TABS)]
_driving(b, pages)
out = await b.tab_new()
assert "tab limit reached" in out["error"]
async def test_a_stream_that_cannot_restart_after_a_tab_switch_says_so_and_carries_on() -> None:
"""The reader loses the live view, not the session: a failed restream is
logged where a raise would have taken the tab switch down with it."""
b = get_browser()
page = _ActingPage()
_with_pages(b, [page])
started: list[int] = []
async def start_stream(sink: Any, **kw: Any) -> None:
started.append(1)
raise RuntimeError("target closed")
b.start_stream = start_stream # type: ignore[method-assign]
b._s.on_frame = lambda *a: None
await b._restream()
assert started == [1]
async def test_stopping_a_stream_that_is_already_gone_is_not_an_error() -> None:
b = get_browser()
page = _ActingPage()
_with_pages(b, [page])
class _Cdp:
async def send(self, method: str, params: Any = None) -> Any:
raise RuntimeError("session closed")
async def detach(self) -> None:
raise RuntimeError("session closed")
b._s.cdp = _Cdp()
await b.stop_stream()
assert b._s.cdp is None and b._s.on_frame is None
async def test_an_owner_cannot_close_the_users_unheld_tab() -> None:
"""An unowned tab is the reader's, not idle: the panel's tab may hold a
login the user was asked to complete, and closing the last tab closes the
whole browser -- an auto-approved call must never take it out silently."""
b = get_browser()
users, own = _ActingPage("https://login.test", "L"), _ActingPage("https://b.test", "B")
_driving(b, [users, own], active=0)
b._s.owners["run:a"] = _Owner(own, time.monotonic())
refused = await b.tab_close(0, owner="run:a")
assert "user's tab" in refused["error"]
assert not users.is_closed()
allowed = await b.tab_close(1, owner="run:a")
assert own.is_closed() and "error" not in allowed
by_reader = await b.tab_close(0)
assert users.is_closed() and "error" not in by_reader
async def test_a_read_that_must_open_a_tab_leaves_the_panel_alone() -> None:
"""The delegation case: the active tab is held by another owner, so the
reader-owner's first snapshot has to open its own tab -- and the panel must
not follow it. The context's "page" event fires for that tab exactly as it
does for a popup, so this drives the un-stubbed adoption path."""
b = get_browser()
held = _ActingPage("https://parent.test", "P")
_driving(b, [held])
b._s.owners["run:parent"] = _Owner(held, time.monotonic())
streams: list[str] = []
async def restream() -> None:
streams.append("restream")
b._restream = restream # type: ignore[method-assign]
class _SpawningContext(_FakeContext):
async def new_page(self) -> Any:
page = _ActingPage("about:blank", "")
self.pages.append(page)
b._on_new_page(page)
return page
b._s.context = _SpawningContext([held])
out = await b.snapshot(owner="run:child")
for task in list(b._s.adopting):
await task
assert not out.get("error")
assert b._s.page is held, "a read must not move what the panel shows"
assert streams == [], "a read must not restream the panel"
assert b._s.owners["run:child"].page is not held, "the read got its own tab"
async def test_an_acting_owner_that_opens_a_tab_still_fronts_it() -> None:
b = get_browser()
held = _ActingPage("https://parent.test", "P")
_driving(b, [held])
b._s.owners["run:parent"] = _Owner(held, time.monotonic())
streams: list[str] = []
async def restream() -> None:
streams.append("restream")
b._restream = restream # type: ignore[method-assign]
class _SpawningContext(_FakeContext):
async def new_page(self) -> Any:
page = _ActingPage("about:blank", "")
self.pages.append(page)
b._on_new_page(page)
return page
b._s.context = _SpawningContext([held])
page = await b._page_for("run:child", act=True)
for task in list(b._s.adopting):
await task
assert b._s.page is page and page is not held
assert streams == ["restream"], "an act fronts the new tab exactly once"
@pytest.mark.parametrize(
("bindings", "lands_on"),
[
pytest.param({}, "front", id="front-tab-is-the-readers"),
pytest.param({"run:other": ("front", 0)}, "new", id="front-tab-held-by-another-owner"),
pytest.param({"run:x": ("mine", 0)}, "mine", id="caller-holds-its-own-tab"),
pytest.param({"run:x": ("mine", "idle")}, "front", id="caller-idled-out-front-tab-free"),
pytest.param(
{"run:x": ("mine", "idle"), "run:other": ("front", 0)}, "new", id="caller-idled-out-front-tab-held"
),
pytest.param({"run:x": ("mine", "closed")}, "front", id="callers-tab-was-closed"),
pytest.param({"run:other": ("front", "idle")}, "front", id="front-tab-held-by-an-idled-out-owner"),
],
)
async def test_the_url_reported_for_an_owner_is_where_its_call_lands(
bindings: dict[str, tuple[str, Any]], lands_on: str
) -> None:
"""The permission gate keys an acting call on ``url_for`` before the call
runs, so the site a person approves is the site acted on only if this
report and ``_page_for`` pick the same page. One case per branch of that
choice; a call that must open a tab of its own is reported empty, since no
site describes a page nobody has opened yet."""
b = get_browser()
pages = {"mine": _FakePage("https://mine.test/"), "front": _FakePage("https://bank.test/")}
_driving(b, [pages["mine"], pages["front"]], active=1)
b._wire = lambda page: None # type: ignore[method-assign]
for owner, (name, age) in bindings.items():
if age == "closed":
pages[name]._closed = True
seen = time.monotonic() - (driver_module.OWNER_IDLE_S + 1 if age == "idle" else 0)
b._s.owners[owner] = _Owner(pages[name], seen)
before = set(map(id, pages.values()))
reported = b.url_for("run:x")
landed = await b._page_for("run:x")
if lands_on == "new":
assert id(landed) not in before, "the call opened a tab of its own"
assert reported == ""
else:
assert landed is pages[lands_on]
assert reported == landed.url