"""Committed tests for the blackcat agent (stdlib unittest, no network)."""
# retoor <retoor@molodetz.nl>
import importlib.util
import io
import json
import os
import sys
import tempfile
import unittest
from contextlib import redirect_stdout
from unittest import mock
HAS_READLINE = importlib.util.find_spec("readline") is not None
from blackcat.agent import BlackCatBot
from blackcat.cli import main
from blackcat.client import (
DeepSeekClient,
DeepSeekError,
OpenRouterClient,
encode_image,
load_dotenv,
resolve_api_key,
user_message,
)
NO_ENV_FILE = {"BLACKCAT_ENV_FILE": os.path.join(tempfile.gettempdir(),
"blackcat-no-such-env")}
class _FakeResp:
"""Minimal async stand-in for an aiohttp response."""
def __init__(self, status=200, payload=None, raw=None):
self.status = status
self.headers = {}
if raw is not None:
self._raw = raw
else:
self._raw = json.dumps(payload).encode("utf-8")
async def __aenter__(self):
return self
async def __aexit__(self, *exc):
return False
async def read(self):
return self._raw
def raise_for_status(self):
if self.status >= 400:
raise _response_error(self.status)
def _response_error(status):
import aiohttp
return aiohttp.ClientResponseError(
request_info=mock.Mock(), history=(), status=status)
class _FakeSession:
"""Records requests; answers from a handler callable."""
def __init__(self, handler):
self.handler = handler
self.posts = []
self.gets = []
self.closed = False
def post(self, url, **kwargs):
self.posts.append((url, kwargs.get("json")))
return self.handler("POST", url, kwargs)
def get(self, url, **kwargs):
self.gets.append((url, kwargs.get("headers")))
return self.handler("GET", url, kwargs)
async def close(self):
self.closed = True
def _json_handler(payload, status=200):
def handle(_method, _url, _kwargs):
return _FakeResp(status=status, payload=payload)
return handle
class TestEchoAgent(unittest.IsolatedAsyncioTestCase):
async def test_prompt_and_transcript(self):
async with BlackCatBot(provider="echo") as bot:
self.assertEqual(await bot.prompt("hi"), "echo: hi")
kinds = [f["kind"] for f in bot.transcript]
self.assertEqual(kinds, ["init", "prompt", "close"])
async def test_prompt_with_images(self):
async with BlackCatBot(provider="echo") as bot:
reply = await bot.prompt("look", images=["a.png"])
self.assertIn("[+1 image(s)]", reply)
async def test_search_fetch_echo(self):
async with BlackCatBot(provider="echo") as bot:
self.assertEqual(((await bot.search("q")))["query"], "q")
self.assertEqual(((await bot.fetch("https://x.test")))["url"],
"https://x.test")
async def test_save_report(self):
with tempfile.TemporaryDirectory() as tmp:
path = os.path.join(tmp, "r.json")
async with BlackCatBot(provider="echo") as bot:
await bot.prompt("hi")
await bot.save_report(path)
with open(path, encoding="utf-8") as fh:
report = json.load(fh)
self.assertEqual(report["agent"], "blackcat")
self.assertEqual(report["frames"], len(report["transcript"]))
self.assertGreaterEqual(report["frames"], 2)
def test_unknown_provider(self):
with self.assertRaises(ValueError):
BlackCatBot(provider="meta")
async def test_system_explicit(self):
async with BlackCatBot(provider="echo",
system="be brief") as bot:
self.assertEqual(bot.system, "be brief")
async def test_system_from_env_file(self):
with tempfile.TemporaryDirectory() as tmp:
path = os.path.join(tmp, ".env")
with open(path, "w", encoding="utf-8") as fh:
fh.write("BLACKCAT_SYSTEM=from-file\n")
env = dict(NO_ENV_FILE)
env["BLACKCAT_ENV_FILE"] = path
with mock.patch.dict(os.environ, env, clear=True):
async with BlackCatBot(provider="echo") as bot:
self.assertEqual(bot.system, "from-file")
async def test_system_explicit_wins_over_env(self):
env = dict(NO_ENV_FILE)
env["BLACKCAT_SYSTEM"] = "from-env"
with mock.patch.dict(os.environ, env, clear=True):
async with BlackCatBot(provider="echo",
system="explicit") as bot:
self.assertEqual(bot.system, "explicit")
class TestVisionMessages(unittest.IsolatedAsyncioTestCase):
async def test_text_only(self):
self.assertEqual(await user_message("hi"),
{"role": "user", "content": "hi"})
async def test_url_passthrough(self):
msg = await user_message("v", images=["https://x.test/i.png"])
blocks = msg["content"]
self.assertEqual(blocks[1]["image_url"]["url"],
"https://x.test/i.png")
async def test_local_file_encoded(self):
with tempfile.TemporaryDirectory() as tmp:
path = os.path.join(tmp, "i.png")
with open(path, "wb") as fh:
fh.write(b"\x89PNG\r\n\x1a")
url = await encode_image(path)
self.assertTrue(url.startswith("data:image/png;base64,"))
async def test_bad_type_rejected(self):
with tempfile.TemporaryDirectory() as tmp:
path = os.path.join(tmp, "i.txt")
with open(path, "w") as fh:
fh.write("nope")
with self.assertRaises(DeepSeekError):
await encode_image(path)
class TestDeepSeekClient(unittest.IsolatedAsyncioTestCase):
def test_missing_key(self):
with mock.patch.dict(os.environ, NO_ENV_FILE, clear=True):
with self.assertRaises(DeepSeekError):
DeepSeekClient()
async def test_chat_request_shape(self):
client = DeepSeekClient(api_key="k")
payload = {"choices": [{"message": {"content": "yo"}}],
"usage": {"total_tokens": 3}}
session = _FakeSession(_json_handler(payload))
client._http = session
out = await client.chat([{"role": "user", "content": "hi"}])
url, body = session.posts[0]
self.assertEqual(url, "https://api.deepseek.com/chat/completions")
self.assertEqual(body["model"], "deepseek-flash")
self.assertFalse(body["stream"])
self.assertEqual(DeepSeekClient.text_of(out), "yo")
async def test_chrome_identity_no_blackcat(self):
from blackcat.http import open_session
async with open_session(30) as session:
ua = str(session.headers.get("User-Agent", ""))
self.assertIn("Chrome/", ua)
self.assertNotIn("blackcat", ua.lower())
for value in session.headers.values():
self.assertNotIn("blackcat", str(value).lower())
async def test_retry_then_success(self):
client = DeepSeekClient(api_key="k")
payload = {"choices": [{"message": {"content": "yo"}}]}
calls = []
def handle(_method, _url, _kwargs):
calls.append(1)
if len(calls) == 1:
return _FakeResp(status=429, payload={"error": "slow"})
return _FakeResp(payload=payload)
bot = BlackCatBot(provider="deepseek", api_key="k")
bot._client = client
self.addAsyncCleanup(bot.aclose)
client._http = _FakeSession(handle)
out = await bot._chat_with_retry(
[{"role": "user", "content": "hi"}])
self.assertEqual(DeepSeekClient.text_of(out), "yo")
self.assertEqual(len(calls), 2)
async def test_v1_base_normalized(self):
client = DeepSeekClient(api_key="k",
base_url="https://api.deepseek.com/v1")
session = _FakeSession(_json_handler({"content": "x"}))
client._http = session
await client.fetch("https://a.test/p")
url, _body = session.posts[0]
self.assertEqual(url,
"https://api.deepseek.com/v1/tools/fetch")
def test_no_search_backend(self):
self.assertFalse(hasattr(DeepSeekClient(api_key="k"), "search"))
async def test_fetch_validation(self):
client = DeepSeekClient(api_key="k")
with self.assertRaises(DeepSeekError):
await client.fetch("ftp://x.test")
class TestOpenRouterClient(unittest.IsolatedAsyncioTestCase):
def test_missing_key(self):
with mock.patch.dict(os.environ, NO_ENV_FILE, clear=True):
with self.assertRaises(DeepSeekError) as ctx:
OpenRouterClient()
self.assertIn("OPENROUTER_API_KEY", str(ctx.exception))
def test_defaults(self):
client = OpenRouterClient(api_key="k")
self.assertEqual(client.base_url,
"https://openrouter.ai/api/v1")
self.assertEqual(client.model, "openrouter/auto")
async def test_chat_request_shape(self):
client = OpenRouterClient(api_key="k")
payload = {"choices": [{"message": {"content": "yo"}}],
"usage": {"total_tokens": 3}}
session = _FakeSession(_json_handler(payload))
client._http = session
out = await client.chat([{"role": "user", "content": "hi"}])
url, body = session.posts[0]
self.assertEqual(url,
"https://openrouter.ai/api/v1/chat/completions")
self.assertEqual(body["model"], "openrouter/auto")
self.assertFalse(body["stream"])
self.assertEqual(OpenRouterClient.text_of(out), "yo")
async def test_no_fetch_or_search_backend(self):
client = OpenRouterClient(api_key="k")
self.assertFalse(hasattr(client, "search"))
with self.assertRaises(DeepSeekError):
await client.fetch("https://a.test/p")
def test_bot_provider_defaults(self):
bot = BlackCatBot(provider="openrouter", api_key="k")
self.addAsyncCleanup(bot.aclose)
self.assertIsInstance(bot._client, OpenRouterClient)
self.assertEqual(bot.model, "openrouter/auto")
self.assertEqual(bot.base_url,
"https://openrouter.ai/api/v1")
def test_bot_explicit_model_wins(self):
bot = BlackCatBot(provider="openrouter", api_key="k",
model="x/y", base_url="https://o.test/v1")
self.addAsyncCleanup(bot.aclose)
self.assertEqual(bot.model, "x/y")
self.assertEqual(bot.base_url, "https://o.test/v1")
class TestCLI(unittest.TestCase):
def run_cli(self, argv):
buf = io.StringIO()
with redirect_stdout(buf):
code = main(argv)
return code, buf.getvalue()
def test_prompt_echo(self):
code, out = self.run_cli(["--provider", "echo", "prompt", "hello"])
self.assertEqual(code, 0)
self.assertIn("echo: hello", out)
def test_search_echo(self):
code, out = self.run_cli(["--provider", "echo", "search", "q"])
self.assertEqual(code, 0)
self.assertIn('"query": "q"', out)
def test_out_report(self):
with tempfile.TemporaryDirectory() as tmp:
path = os.path.join(tmp, "r.json")
code, _ = self.run_cli(
["--provider", "echo", "prompt", "hi", "--out", path])
self.assertEqual(code, 0)
with open(path, encoding="utf-8") as fh:
self.assertEqual(json.load(fh)["agent"], "blackcat")
def test_live_without_key_fails(self):
with mock.patch.dict(os.environ, NO_ENV_FILE, clear=True):
code = main(["--provider", "deepseek", "prompt", "hi"])
self.assertEqual(code, 2)
def test_openrouter_without_key_fails(self):
with mock.patch.dict(os.environ, NO_ENV_FILE, clear=True):
code = main(["--provider", "openrouter", "prompt", "hi"])
self.assertEqual(code, 2)
def test_openrouter_accepted_choice(self):
from blackcat.cli import build_parser
args = build_parser().parse_args(
["--provider", "openrouter", "prompt", "hi"])
self.assertEqual(args.provider, "openrouter")
def test_tui_command_calls_run(self):
with mock.patch("blackcat.tui.run_tui",
return_value=0) as run:
code = main(["--provider", "echo", "tui"])
self.assertEqual(code, 0)
self.assertEqual(run.call_args[1]["provider"], "echo")
def test_yolo_flag_reaches_tui(self):
with mock.patch("blackcat.tui.run_tui",
return_value=0) as run:
code = main(["--provider", "echo", "--yolo", "tui"])
self.assertEqual(code, 0)
self.assertTrue(run.call_args[1]["yolo"])
def test_tui_prompt_argument_reaches_run(self):
with mock.patch("blackcat.tui.run_tui",
return_value=0) as run:
code = main(["--provider", "echo", "tui", "fix the bug"])
self.assertEqual(code, 0)
self.assertEqual(run.call_args[1]["initial_prompt"],
"fix the bug")
with mock.patch("blackcat.tui.run_tui",
return_value=0) as run:
code = main(["--provider", "echo", "tui"])
self.assertEqual(code, 0)
self.assertIsNone(run.call_args[1]["initial_prompt"])
def test_tui_mode_silences_terminal_logging(self):
import logging
with mock.patch("blackcat.tui.run_tui", return_value=0):
code = main(["--provider", "echo", "tui"])
self.assertEqual(code, 0)
logger = logging.getLogger("blackcat")
streams = [h for h in logger.handlers
if isinstance(h, logging.StreamHandler)
and not isinstance(h, logging.FileHandler)]
self.assertEqual(streams, [])
def test_setup_logging_stream_off(self):
import logging
from blackcat.cli import setup_logging
logger = setup_logging(stream=False)
streams = [h for h in logger.handlers
if isinstance(h, logging.StreamHandler)
and not isinstance(h, logging.FileHandler)]
self.assertEqual(streams, [])
logger = setup_logging(stream=True)
streams = [h for h in logger.handlers
if isinstance(h, logging.StreamHandler)
and not isinstance(h, logging.FileHandler)]
self.assertEqual(len(streams), 1)
def test_long_run_flags_reach_tui(self):
with mock.patch("blackcat.tui.run_tui",
return_value=0) as run:
code = main(["--provider", "echo", "--context-limit", "5000",
"--session", "s.json", "tui"])
self.assertEqual(code, 0)
self.assertEqual(run.call_args[1]["context_limit"], 5000)
self.assertEqual(run.call_args[1]["session"], "s.json")
def test_session_flag_resumes_across_processes(self):
with tempfile.TemporaryDirectory() as tmp:
path = os.path.join(tmp, "s.json")
with mock.patch.dict(os.environ, NO_ENV_FILE, clear=True):
code = main(["--provider", "echo", "--session", path,
"prompt", "first"])
self.assertEqual(code, 0)
code = main(["--provider", "echo", "--session", path,
"prompt", "second"])
self.assertEqual(code, 0)
with open(path, encoding="utf-8") as fh:
payload = json.load(fh)
contents = [m.get("content") for m in payload["messages"]]
self.assertEqual(contents, ["first", "echo: first",
"second", "echo: second"])
def test_tui_without_textual_shows_hint(self):
with mock.patch.dict(sys.modules, {"textual": None}):
code = main(["--provider", "echo", "tui"])
self.assertEqual(code, 2)
def test_default_provider_is_deepseek(self):
from blackcat.cli import build_parser
args = build_parser().parse_args(["prompt", "hi"])
self.assertEqual(args.provider, "deepseek")
with mock.patch.dict(os.environ, NO_ENV_FILE, clear=True):
code = main(["prompt", "hi"])
self.assertEqual(code, 2)
class TestChat(unittest.TestCase):
def run_chat(self, argv, inputs):
buf = io.StringIO()
with mock.patch("builtins.input", side_effect=inputs):
with redirect_stdout(buf):
code = main(argv)
return code, buf.getvalue()
def test_bare_boot_is_chat(self):
code, out = self.run_chat(["--provider", "echo"],
["hello", EOFError()])
self.assertEqual(code, 0)
self.assertIn("echo: hello", out)
def test_chat_command_and_quit(self):
code, out = self.run_chat(["--provider", "echo", "chat"],
["hi", "/quit"])
self.assertEqual(code, 0)
self.assertIn("echo: hi", out)
def test_chat_out_report(self):
with tempfile.TemporaryDirectory() as tmp:
path = os.path.join(tmp, "r.json")
code, _ = self.run_chat(["--provider", "echo", "--out", path],
["hi", EOFError()])
self.assertEqual(code, 0)
with open(path, encoding="utf-8") as fh:
self.assertEqual(json.load(fh)["agent"], "blackcat")
def test_bare_boot_defaults_to_deepseek(self):
with mock.patch.dict(os.environ, NO_ENV_FILE, clear=True):
code, out = self.run_chat([], [EOFError()])
self.assertEqual(code, 2)
self.assertNotIn("echo:", out)
def test_multiline_paste_is_one_prompt(self):
code, out = self.run_chat(["--provider", "echo"],
["first\nsecond", "/quit"])
self.assertEqual(code, 0)
self.assertIn("echo: first\nsecond", out)
def test_backslash_continuation(self):
code, out = self.run_chat(["--provider", "echo"],
["hello \\", "world", "/quit"])
self.assertEqual(code, 0)
self.assertIn("echo: hello \nworld", out)
def test_continuation_eof_exits(self):
code, _ = self.run_chat(["--provider", "echo"],
["abc\\", EOFError()])
self.assertEqual(code, 0)
def test_help_mentions_history_and_multiline(self):
code, out = self.run_chat(["--provider", "echo"],
["/help", "/quit"])
self.assertEqual(code, 0)
self.assertIn("Up/Down", out)
self.assertIn("Shift+Tab", out)
class TestReadline(unittest.TestCase):
def test_setup_no_tty_returns_none(self):
from blackcat.cli import setup_readline
with mock.patch.object(sys.stdin, "isatty",
return_value=False):
self.assertIsNone(setup_readline("/no/such/history"))
@unittest.skipUnless(HAS_READLINE, "readline unavailable")
def test_history_roundtrip(self):
import readline as rl
from blackcat.cli import save_readline_history, setup_readline
before = [rl.get_history_item(i + 1)
for i in range(rl.get_current_history_length())]
try:
with tempfile.TemporaryDirectory() as tmp:
path = os.path.join(tmp, "hist")
with mock.patch.object(sys.stdin, "isatty",
return_value=True):
self.assertEqual(setup_readline(path), path)
rl.add_history("blackcat-test-line")
save_readline_history(path)
with open(path, encoding="utf-8") as fh:
self.assertIn("blackcat-test-line", fh.read())
finally:
rl.clear_history()
for item in before:
rl.add_history(item)
@unittest.skipUnless(HAS_READLINE, "readline unavailable")
def test_history_env_override(self):
from blackcat.cli import setup_readline
with tempfile.TemporaryDirectory() as tmp:
path = os.path.join(tmp, "hist")
env = {"BLACKCAT_HISTORY_FILE": path}
with mock.patch.dict(os.environ, env, clear=True), \
mock.patch.object(sys.stdin, "isatty",
return_value=True):
self.assertEqual(setup_readline(), path)
def test_save_none_is_noop(self):
from blackcat.cli import save_readline_history
save_readline_history(None)
class TestDotenv(unittest.TestCase):
def write_env(self, tmp, body):
path = os.path.join(tmp, ".env")
with open(path, "w", encoding="utf-8") as fh:
fh.write(body)
return path
def test_env_file_key_resolves(self):
with tempfile.TemporaryDirectory() as tmp:
path = self.write_env(tmp, "DEEPSEEK_API_KEY=file-key\n")
env = {"BLACKCAT_ENV_FILE": path}
with mock.patch.dict(os.environ, env, clear=True):
self.assertEqual(resolve_api_key(), "file-key")
def test_env_var_wins_over_file(self):
with tempfile.TemporaryDirectory() as tmp:
path = self.write_env(tmp, "DEEPSEEK_API_KEY=file-key\n")
env = {"BLACKCAT_ENV_FILE": path, "DEEPSEEK_API_KEY": "env-key"}
with mock.patch.dict(os.environ, env, clear=True):
self.assertEqual(resolve_api_key(), "env-key")
def test_missing_file_ignored(self):
with mock.patch.dict(os.environ, NO_ENV_FILE, clear=True):
self.assertEqual(load_dotenv(), {})
self.assertIsNone(resolve_api_key())
def test_openrouter_key_resolves(self):
env = dict(NO_ENV_FILE)
env["OPENROUTER_API_KEY"] = "or-key"
with mock.patch.dict(os.environ, env, clear=True):
self.assertEqual(resolve_api_key(provider="openrouter"),
"or-key")
self.assertIsNone(resolve_api_key())
def test_openrouter_key_from_file(self):
with tempfile.TemporaryDirectory() as tmp:
path = self.write_env(tmp, "OPENROUTER_API_KEY=file-or-key\n")
env = {"BLACKCAT_ENV_FILE": path}
with mock.patch.dict(os.environ, env, clear=True):
self.assertEqual(resolve_api_key(provider="openrouter"),
"file-or-key")
def test_shared_key_covers_both_providers(self):
env = dict(NO_ENV_FILE)
env["BLACKCAT_API_KEY"] = "shared-key"
with mock.patch.dict(os.environ, env, clear=True):
self.assertEqual(resolve_api_key(), "shared-key")
self.assertEqual(resolve_api_key(provider="openrouter"),
"shared-key")
def test_comments_quotes_and_export(self):
with tempfile.TemporaryDirectory() as tmp:
body = ('# comment\n\n'
'export DEEPSEEK_API_KEY="quoted-key"\n'
'OTHER=plain\n'
'not a kv line\n')
path = self.write_env(tmp, body)
with mock.patch.dict(os.environ, {"BLACKCAT_ENV_FILE": path},
clear=True):
found = load_dotenv()
self.assertEqual(found["DEEPSEEK_API_KEY"], "quoted-key")
self.assertEqual(found["OTHER"], "plain")
if __name__ == "__main__":
unittest.main()