"""Tests for stealth fetching and the browse agent-as-tool (offline).
StealthFetcher and BrowserTools run against in-test fakes with the
real surface (stealthii get/shutdown, Playwright page); run_browse_task
runs against a fake browser class plus a stubbed sub-agent prompt so
no Chromium or network is ever touched.
"""
# retoor <retoor@molodetz.nl>
import unittest
from unittest import mock
from stealthii import StealthRequestError
from blackcat.agent import BlackCatBot
from blackcat.browse import (
BROWSER_SCHEMAS,
BROWSER_TOOLS,
MAX_BROWSE_STEPS,
BrowserTools,
run_browse_task,
)
from blackcat.client import DeepSeekError
from blackcat.http import StealthFetcher
class _FakeResp:
def __init__(self, status=200, text="", ctype="text/html"):
self.status = status
self._text = text
self.headers = {"content-type": ctype}
async def text(self):
return self._text
class _FakeStealth:
def __init__(self, resp=None, error=None):
self.resp = resp
self.error = error
self.got = []
self.shutdowns = 0
async def get(self, url, headers=None, timeout=None):
self.got.append(url)
if self.error is not None:
raise self.error
return self.resp
async def shutdown(self):
self.shutdowns += 1
class TestStealthFetcher(unittest.IsolatedAsyncioTestCase):
async def test_html_becomes_text(self):
stealth = _FakeStealth(_FakeResp(
text="<html><body><h1>Hi</h1><p>Text here</p></body></html>"))
out = await StealthFetcher(stealth=stealth).fetch(
"https://a.org/p")
self.assertIn("Hi", out["content"])
self.assertNotIn("<html", out["content"])
self.assertEqual(out["fallback_provider"], "stealthii")
self.assertEqual(stealth.got, ["https://a.org/p"])
async def test_plain_text_passes_through(self):
stealth = _FakeStealth(_FakeResp(text="just words",
ctype="text/plain"))
out = await StealthFetcher(stealth=stealth).fetch(
"https://a.org/t.txt")
self.assertEqual(out["content"], "just words")
async def test_status_error_raises(self):
stealth = _FakeStealth(_FakeResp(status=404, text="nope"))
with self.assertRaises(DeepSeekError):
await StealthFetcher(stealth=stealth).fetch(
"https://a.org/missing")
async def test_bad_scheme_rejected(self):
with self.assertRaises(DeepSeekError):
await StealthFetcher(stealth=_FakeStealth()).fetch(
"ftp://a.org/x")
async def test_stealth_error_becomes_unreachable(self):
stealth = _FakeStealth(error=StealthRequestError("boom"))
with self.assertRaises(DeepSeekError) as caught:
await StealthFetcher(stealth=stealth).fetch(
"https://a.org/p")
self.assertIn("unreachable", str(caught.exception))
async def test_aclose_idempotent_and_unstarted_safe(self):
fetcher = StealthFetcher(stealth=_FakeStealth())
await fetcher.aclose()
await fetcher.aclose()
self.assertEqual(fetcher._stealth, None)
await StealthFetcher().aclose()
class _FakeElement:
def __init__(self, page, ref=None, text=None):
self._page = page
self._ref = ref
self._text = text
async def click(self, timeout=None):
self._page.clicked.append(self._ref)
async def fill(self, text, timeout=None):
self._page.filled.append((self._ref, text))
async def press(self, key):
self._page.pressed_keys.append(key)
@property
def first(self):
return self
async def wait_for(self, state=None, timeout=None):
self._page.waited.append(("text", self._text))
class _FakeKeyboard:
def __init__(self, page):
self._page = page
async def press(self, key):
self._page.pressed_keys.append(key)
class _FakeContext:
def __init__(self, cookies=()):
self._cookies = list(cookies)
self.cleared = False
async def cookies(self):
return list(self._cookies)
async def clear_cookies(self):
self.cleared = True
self._cookies = []
class _FakePage:
def __init__(self, url="https://a.org/", title="A",
snapshot="snap", text="page text",
links=(), error=None):
self.url = url
self._title = title
self._snapshot = snapshot
self._text = text
self._links = list(links)
self.error = error
self.clicked = []
self.filled = []
self.pressed_keys = []
self.waited = []
self.context = _FakeContext()
self.keyboard = _FakeKeyboard(self)
self.goto_urls = []
def _maybe_raise(self):
if self.error is not None:
raise self.error
async def goto(self, url, wait_until=None, timeout=None):
self._maybe_raise()
self.goto_urls.append(url)
self.url = url
return None
async def title(self):
self._maybe_raise()
return self._title
async def aria_snapshot(self, mode=None):
self._maybe_raise()
return self._snapshot
def get_by_ref(self, ref):
return _FakeElement(self, ref=ref)
def get_by_text(self, text):
return _FakeElement(self, text=text)
async def go_back(self):
self._maybe_raise()
async def go_forward(self):
self._maybe_raise()
async def reload(self, wait_until=None, timeout=None):
self._maybe_raise()
async def wait_for_timeout(self, ms):
self.waited.append(("ms", ms))
async def wait_for_load_state(self, state, timeout=None):
self.waited.append(("load", state))
async def evaluate(self, js):
self._maybe_raise()
if "querySelectorAll" in js:
return self._links
if "innerText" in js:
return self._text
return {"echo": js}
def _tools(page=None):
return BrowserTools(page or _FakePage())
class TestBrowserTools(unittest.IsolatedAsyncioTestCase):
async def test_dispatch_matches_schemas(self):
tools = _tools()
self.assertEqual(set(tools.dispatch()), set(BROWSER_TOOLS))
self.assertEqual(
{s["function"]["name"] for s in BROWSER_SCHEMAS},
set(BROWSER_TOOLS))
async def test_goto_ok_and_remembers(self):
tools = _tools()
out = await tools.goto("https://b.org/x")
self.assertTrue(out["ok"])
self.assertEqual(out["url"], "https://b.org/x")
self.assertEqual(out["title"], "A")
self.assertIsNone(out["status"])
self.assertEqual(tools.visited, ["https://b.org/x"])
await tools.goto("https://b.org/x")
self.assertEqual(tools.visited, ["https://b.org/x"])
async def test_goto_rejects_bad_url(self):
out = await _tools().goto("ftp://b.org/x")
self.assertEqual(out["code"], "bad_args")
async def test_goto_error(self):
tools = _tools(_FakePage(error=RuntimeError("down")))
out = await tools.goto("https://b.org/x")
self.assertEqual(out["code"], "browser_error")
self.assertIn("RuntimeError", out["error"])
async def test_snapshot_caps(self):
tools = _tools(_FakePage(snapshot="s" * 20000))
out = await tools.snapshot()
self.assertTrue(out["ok"])
self.assertTrue(out["truncated"])
self.assertLessEqual(len(out["snapshot"]), 12000 + 200)
async def test_click_fill_press(self):
page = _FakePage()
tools = _tools(page)
self.assertTrue((await tools.click("e3"))["ok"])
self.assertEqual(page.clicked, ["e3"])
self.assertEqual((await tools.click(""))["code"], "bad_args")
self.assertTrue((await tools.fill("e4", "hi"))["ok"])
self.assertEqual(page.filled, [("e4", "hi")])
self.assertTrue(
(await tools.fill("e4", "hi", submit=True))["ok"])
self.assertIn("Enter", page.pressed_keys)
self.assertEqual(
(await tools.fill("e4", 5))["code"], "bad_args")
self.assertTrue((await tools.press("Escape"))["ok"])
self.assertEqual((await tools.press(""))["code"], "bad_args")
async def test_back_forward_reload(self):
tools = _tools()
for name in ("back", "forward", "reload"):
out = await getattr(tools, name)()
self.assertTrue(out["ok"], name)
self.assertEqual(out["url"], "https://a.org/")
async def test_wait_variants(self):
page = _FakePage()
tools = _tools(page)
out = await tools.wait(text="hello")
self.assertEqual(out["waited"], "text:hello")
out = await tools.wait(ms=50)
self.assertEqual(out["waited"], "ms:50")
out = await tools.wait()
self.assertEqual(out["waited"], "networkidle-or-timeout")
async def test_read_caps(self):
tools = _tools(_FakePage(text="w" * 30000))
out = await tools.read()
self.assertTrue(out["truncated"])
self.assertLessEqual(len(out["text"]), 20000 + 200)
out = await _tools().read(limit_chars=1000)
self.assertFalse(out["truncated"])
async def test_links_capped(self):
links = [{"href": "https://a.org/%d" % i, "text": "t%d" % i}
for i in range(150)]
out = await _tools(_FakePage(links=links)).links()
self.assertEqual(out["total"], 150)
self.assertEqual(len(out["links"]), 100)
weird = _FakePage()
weird._links = {"not": "a list"}
out = await _tools(weird).links()
self.assertEqual(out["links"], [])
async def test_cookies(self):
page = _FakePage()
page.context = _FakeContext([{"name": "s", "value": "1"}])
tools = _tools(page)
out = await tools.cookies()
self.assertEqual(out["total"], 1)
out = await tools.cookies("clear")
self.assertEqual(out["action"], "clear")
self.assertTrue(page.context.cleared)
self.assertEqual((await tools.cookies("drop"))["code"],
"bad_args")
async def test_evaluate(self):
tools = _tools()
out = await tools.evaluate("1+1")
self.assertTrue(out["ok"])
self.assertFalse(out["truncated"])
self.assertIn("1+1", out["result"])
out = await tools.evaluate("x" * 9000)
self.assertTrue(out["truncated"])
self.assertEqual((await tools.evaluate(" "))["code"],
"bad_args")
async def test_concurrent_actions_serialize(self):
page = _FakePage()
tools = _tools(page)
await tools.goto("https://a.org/1")
await tools.goto("https://a.org/2")
self.assertEqual(page.goto_urls,
["https://a.org/1", "https://a.org/2"])
class _FakeBrowser:
last_headed = None
def __init__(self, headed=False):
_FakeBrowser.last_headed = headed
self.shutdowns = 0
def page(self, session=None):
return _FakePageContext()
async def shutdown(self):
self.shutdowns += 1
class _FakePageContext:
async def __aenter__(self):
self.page = _FakePage(url="https://a.org/start")
return self.page
async def __aexit__(self, *exc):
return False
class TestRunBrowseTask(unittest.IsolatedAsyncioTestCase):
async def _run(self, **kwargs):
parent = BlackCatBot(provider="deepseek", api_key="k",
system="t")
self.addAsyncCleanup(parent.aclose)
with mock.patch("blackcat.browse.Stealthii",
lambda: _FakeBrowser(headed=False)), \
mock.patch("blackcat.browse.HeadedStealthii",
lambda: _FakeBrowser(headed=True)), \
mock.patch.object(
BlackCatBot, "prompt",
new=mock.AsyncMock(
return_value="the answer")) as prompt:
out = await run_browse_task(parent, "find facts",
**kwargs)
return parent, prompt, out
async def test_headless_answer_and_visited(self):
parent, prompt, out = await self._run(url="https://a.org/")
self.assertTrue(out["ok"])
self.assertEqual(out["answer"], "the answer")
self.assertFalse(out["headed"])
self.assertFalse(_FakeBrowser.last_headed)
asked = prompt.call_args[0][0]
self.assertIn("https://a.org/", asked)
self.assertIn("find facts", asked)
kinds = [f["kind"] for f in parent.transcript]
self.assertIn("browse_sub", kinds)
async def test_headed_selects_headed_browser(self):
_FakeBrowser.last_headed = None
_parent, _prompt, out = await self._run(headed=True)
self.assertTrue(out["headed"])
self.assertTrue(_FakeBrowser.last_headed)
async def test_max_steps_clamped(self):
_parent, prompt, out = await self._run(
max_steps=MAX_BROWSE_STEPS + 500)
self.assertTrue(out["ok"])
asked = prompt.call_args[0][0]
self.assertIn("at most %d tool steps" % MAX_BROWSE_STEPS,
asked)
async def test_browse_error_is_clean(self):
parent = BlackCatBot(provider="deepseek", api_key="k",
system="t")
self.addAsyncCleanup(parent.aclose)
with mock.patch("blackcat.browse.Stealthii",
side_effect=DeepSeekError("no browser")), \
mock.patch.object(
BlackCatBot, "prompt",
new=mock.AsyncMock(return_value="x")):
out = await run_browse_task(parent, "find facts")
self.assertEqual(out["code"], "browse_failed")
class TestBrowseTool(unittest.IsolatedAsyncioTestCase):
async def test_echo_refuses(self):
async with BlackCatBot(provider="echo",
system="t") as bot:
out = await bot.browse(task="look around")
self.assertEqual(out["code"], "browse_failed")
async def test_blank_task_rejected(self):
async with BlackCatBot(provider="deepseek", api_key="k",
system="t") as bot:
out = await bot.browse(task=" ")
self.assertEqual(out["code"], "bad_args")
async def test_bad_max_steps_rejected(self):
async with BlackCatBot(provider="deepseek", api_key="k",
system="t") as bot:
out = await bot.browse(task="x", max_steps="many")
self.assertEqual(out["code"], "bad_args")
async def test_headed_flag_forwarded(self):
async with BlackCatBot(provider="deepseek", api_key="k",
system="t") as bot:
with mock.patch("blackcat.browse.run_browse_task",
new=mock.AsyncMock(return_value={
"ok": True, "answer": "a",
"steps": 1, "visited": [],
"headed": True})) as run:
out = await bot.browse(task="x", headed=True)
self.assertTrue(out["ok"])
self.assertTrue(run.call_args[1]["headed"])
kinds = [f["kind"] for f in bot.transcript]
self.assertIn("browse", kinds)
if __name__ == "__main__":
unittest.main()