Add in-memory fake backend for CI smoke tests

install_fake_backend() / uninstall_fake_backend() swap the
mouse / keyboard / screen / clipboard wrappers with recorders that
mutate an in-memory FakeState rather than the real OS. Lets a CI
runner exercise every MCP tool end-to-end without a display
server. Toggle via JE_AUTOCONTROL_FAKE_BACKEND=1 or the new
--fake-backend CLI flag. ac_click_mouse adapter relaxed to pass
through string keycodes unchanged so it works under either
backend.

Author: JE-Chen

je_auto_control/utils/mcp_server/__init__.py

@@ -13,6 +13,10 @@
 from je_auto_control.utils.mcp_server.context import (
     OperationCancelledError, ToolCallContext,
 )
+from je_auto_control.utils.mcp_server.fake_backend import (
+    FakeState, fake_state, install_fake_backend, reset_fake_state,
+    uninstall_fake_backend,
+)
 from je_auto_control.utils.mcp_server.rate_limit import RateLimiter
 from je_auto_control.utils.mcp_server.http_transport import (
     HttpMCPServer, start_mcp_http_server,
@@ -29,12 +33,14 @@
 )
 
 __all__ = [
-    "AuditLogger", "HttpMCPServer", "MCPContent", "MCPPrompt",
+    "AuditLogger", "FakeState", "HttpMCPServer", "MCPContent", "MCPPrompt",
     "MCPPromptArgument", "MCPResource", "MCPServer", "MCPTool",
     "MCPToolAnnotations", "OperationCancelledError", "PromptProvider",
     "RateLimiter", "ResourceProvider", "ToolCallContext",
     "build_default_tool_registry",
     "default_prompt_provider", "default_resource_provider",
-    "make_plugin_tool", "register_plugin_tools",
+    "fake_state", "install_fake_backend", "make_plugin_tool",
+    "register_plugin_tools", "reset_fake_state",
     "start_mcp_http_server", "start_mcp_stdio_server",
+    "uninstall_fake_backend",
 ]

je_auto_control/utils/mcp_server/__main__.py

@@ -8,6 +8,9 @@
 import json
 import sys
 
+from je_auto_control.utils.mcp_server.fake_backend import (
+    install_fake_backend, maybe_install_from_env,
+)
 from je_auto_control.utils.mcp_server.prompts import default_prompt_provider
 from je_auto_control.utils.mcp_server.resources import (
     default_resource_provider,
@@ -39,13 +42,22 @@ def _build_parser() -> argparse.ArgumentParser:
         "--read-only", action="store_true",
         help="Restrict tools to those marked readOnlyHint=true.",
     )
+    parser.add_argument(
+        "--fake-backend", action="store_true",
+        help=("Install the in-memory fake backend so tools record but "
+              "don't drive the real OS. Useful for CI smoke tests."),
+    )
     return parser
 
 
 def main(argv: list = None) -> int:
     """CLI entry point. Returns the process exit code."""
     parser = _build_parser()
     args = parser.parse_args(argv)
+    if args.fake_backend:
+        install_fake_backend()
+    else:
+        maybe_install_from_env()
     listing_modes = (args.list_tools, args.list_resources, args.list_prompts)
     if any(listing_modes):
         _print_listings(args)

je_auto_control/utils/mcp_server/fake_backend.py

@@ -0,0 +1,184 @@
+"""In-memory fake backend for CI / headless tool tests.
+
+Drop-in replacement for the wrapper layer's mouse / keyboard / screen
+calls that records every invocation rather than touching the real OS.
+Activate via :func:`install_fake_backend` (or set
+``JE_AUTOCONTROL_FAKE_BACKEND=1`` before starting the MCP server) so
+test agents can drive the full tool registry on a CI runner without a
+display server.
+"""
+import os
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Tuple
+
+
+@dataclass
+class FakeState:
+    """Records what the model would have done if the OS were real."""
+
+    cursor: Tuple[int, int] = (0, 0)
+    screen_size: Tuple[int, int] = (1920, 1080)
+    clipboard_text: str = ""
+    typed_text: List[str] = field(default_factory=list)
+    keys_pressed: List[Any] = field(default_factory=list)
+    mouse_actions: List[Tuple[str, Any, ...]] = field(default_factory=list)
+
+
+def fake_state() -> FakeState:
+    """Return the process-wide fake state."""
+    return _STATE
+
+
+_STATE = FakeState()
+_STATE_LOCK = threading.Lock()
+
+
+def reset_fake_state() -> None:
+    """Reset every recorded interaction. Useful between tests."""
+    global _STATE
+    with _STATE_LOCK:
+        _STATE = FakeState()
+
+
+# === Patched callables ======================================================
+
+def _fake_get_mouse_position() -> Tuple[int, int]:
+    return _STATE.cursor
+
+
+def _fake_set_mouse_position(x: int, y: int) -> Tuple[int, int]:
+    with _STATE_LOCK:
+        _STATE.cursor = (int(x), int(y))
+        _STATE.mouse_actions.append(("set_position", int(x), int(y)))
+    return _STATE.cursor
+
+
+def _fake_click_mouse(mouse_keycode: Any, x: Any = None,
+                      y: Any = None) -> Tuple[Any, int, int]:
+    cx, cy = _STATE.cursor if x is None or y is None else (int(x), int(y))
+    with _STATE_LOCK:
+        _STATE.cursor = (cx, cy)
+        _STATE.mouse_actions.append(("click", mouse_keycode, cx, cy))
+    return mouse_keycode, cx, cy
+
+
+def _fake_press_mouse(mouse_keycode: Any, x: Any = None,
+                      y: Any = None) -> Tuple[Any, int, int]:
+    cx, cy = _STATE.cursor if x is None or y is None else (int(x), int(y))
+    with _STATE_LOCK:
+        _STATE.mouse_actions.append(("press", mouse_keycode, cx, cy))
+    return mouse_keycode, cx, cy
+
+
+def _fake_release_mouse(mouse_keycode: Any, x: Any = None,
+                        y: Any = None) -> Tuple[Any, int, int]:
+    cx, cy = _STATE.cursor if x is None or y is None else (int(x), int(y))
+    with _STATE_LOCK:
+        _STATE.mouse_actions.append(("release", mouse_keycode, cx, cy))
+    return mouse_keycode, cx, cy
+
+
+def _fake_mouse_scroll(scroll_value: int, x: Any = None, y: Any = None,
+                        scroll_direction: str = "scroll_down"
+                        ) -> Tuple[int, str]:
+    with _STATE_LOCK:
+        _STATE.mouse_actions.append(
+            ("scroll", int(scroll_value), scroll_direction),
+        )
+    return int(scroll_value), scroll_direction
+
+
+def _fake_screen_size() -> Tuple[int, int]:
+    return _STATE.screen_size
+
+
+def _fake_write(text: str, *_args, **_kwargs) -> str:
+    with _STATE_LOCK:
+        _STATE.typed_text.append(text)
+    return text
+
+
+def _fake_type_keyboard(keycode: Any, *_args, **_kwargs) -> str:
+    with _STATE_LOCK:
+        _STATE.keys_pressed.append(keycode)
+    return str(keycode)
+
+
+def _fake_hotkey(keys: List[Any], *_args, **_kwargs) -> Tuple[str, str]:
+    joined = ",".join(str(k) for k in keys)
+    with _STATE_LOCK:
+        _STATE.keys_pressed.append(("hotkey", joined))
+    return joined, joined
+
+
+def _fake_get_clipboard() -> str:
+    return _STATE.clipboard_text
+
+
+def _fake_set_clipboard(text: str) -> None:
+    with _STATE_LOCK:
+        _STATE.clipboard_text = str(text)
+
+
+# === Install / uninstall ====================================================
+
+_INSTALLED: Dict[str, Any] = {}
+
+
+def install_fake_backend() -> None:
+    """Replace the headless API entry points with the fake recorders."""
+    if _INSTALLED:
+        return
+    from je_auto_control.utils.clipboard import clipboard as clipboard_module
+    from je_auto_control.wrapper import auto_control_keyboard as kbd_module
+    from je_auto_control.wrapper import auto_control_mouse as mouse_module
+    from je_auto_control.wrapper import auto_control_screen as screen_module
+    targets: Dict[Any, Dict[str, Any]] = {
+        mouse_module: {
+            "get_mouse_position": _fake_get_mouse_position,
+            "set_mouse_position": _fake_set_mouse_position,
+            "click_mouse": _fake_click_mouse,
+            "press_mouse": _fake_press_mouse,
+            "release_mouse": _fake_release_mouse,
+            "mouse_scroll": _fake_mouse_scroll,
+        },
+        screen_module: {"screen_size": _fake_screen_size},
+        kbd_module: {
+            "write": _fake_write,
+            "type_keyboard": _fake_type_keyboard,
+            "hotkey": _fake_hotkey,
+        },
+        clipboard_module: {
+            "get_clipboard": _fake_get_clipboard,
+            "set_clipboard": _fake_set_clipboard,
+        },
+    }
+    for module, replacements in targets.items():
+        for name, replacement in replacements.items():
+            key = f"{module.__name__}.{name}"
+            _INSTALLED[key] = (module, name, getattr(module, name))
+            setattr(module, name, replacement)
+
+
+def uninstall_fake_backend() -> None:
+    """Restore the real backend functions previously replaced."""
+    while _INSTALLED:
+        _key, value = _INSTALLED.popitem()
+        module, name, original = value
+        setattr(module, name, original)
+
+
+def maybe_install_from_env() -> bool:
+    """Install the fake backend when ``JE_AUTOCONTROL_FAKE_BACKEND`` is truthy."""
+    raw = os.environ.get("JE_AUTOCONTROL_FAKE_BACKEND", "").strip().lower()
+    if raw in {"1", "true", "yes", "on"}:
+        install_fake_backend()
+        return True
+    return False
+
+
+__all__ = [
+    "FakeState", "fake_state", "install_fake_backend",
+    "maybe_install_from_env", "reset_fake_state", "uninstall_fake_backend",
+]

je_auto_control/utils/mcp_server/tools/_handlers.py

@@ -17,10 +17,13 @@
 
 def click_mouse(mouse_keycode: str = "mouse_left",
                 x: Optional[int] = None,
-                y: Optional[int] = None) -> List[int]:
+                y: Optional[int] = None) -> List[Any]:
     from je_auto_control.wrapper.auto_control_mouse import click_mouse as _click
     keycode, click_x, click_y = _click(mouse_keycode, x, y)
-    return [int(keycode), int(click_x), int(click_y)]
+    # Real wrapper resolves the string keycode to an int via the keys table;
+    # the fake backend keeps it as a string. Pass through whatever we got.
+    resolved = int(keycode) if isinstance(keycode, int) else keycode
+    return [resolved, int(click_x), int(click_y)]
 
 
 def set_mouse_position(x: int, y: int) -> List[int]:

test/unit_test/headless/test_mcp_fake_backend.py

@@ -0,0 +1,75 @@
+"""Tests for the fake backend used in CI smoke runs."""
+import pytest
+
+from je_auto_control.utils.mcp_server.fake_backend import (
+    fake_state, install_fake_backend, maybe_install_from_env,
+    reset_fake_state, uninstall_fake_backend,
+)
+from je_auto_control.utils.mcp_server.tools import (
+    build_default_tool_registry,
+)
+
+
+@pytest.fixture()
+def fake_backend():
+    """Install the fake backend for the duration of the test."""
+    reset_fake_state()
+    install_fake_backend()
+    yield
+    uninstall_fake_backend()
+    reset_fake_state()
+
+
+def test_set_mouse_position_records_in_fake_state(fake_backend):
+    by_name = {tool.name: tool for tool in build_default_tool_registry()}
+    by_name["ac_set_mouse_position"].invoke({"x": 100, "y": 200})
+    assert fake_state().cursor == (100, 200)
+    assert ("set_position", 100, 200) in fake_state().mouse_actions
+
+
+def test_click_mouse_records_button_and_coords(fake_backend):
+    by_name = {tool.name: tool for tool in build_default_tool_registry()}
+    by_name["ac_click_mouse"].invoke({
+        "mouse_keycode": "mouse_left", "x": 50, "y": 60,
+    })
+    assert ("click", "mouse_left", 50, 60) in fake_state().mouse_actions
+
+
+def test_clipboard_round_trip_via_fake_backend(fake_backend):
+    by_name = {tool.name: tool for tool in build_default_tool_registry()}
+    by_name["ac_set_clipboard"].invoke({"text": "hi"})
+    assert by_name["ac_get_clipboard"].invoke({}) == "hi"
+    assert fake_state().clipboard_text == "hi"
+
+
+def test_type_text_appends_to_typed_history(fake_backend):
+    by_name = {tool.name: tool for tool in build_default_tool_registry()}
+    by_name["ac_type_text"].invoke({"text": "hello"})
+    assert "hello" in fake_state().typed_text
+
+
+def test_install_is_idempotent(fake_backend):
+    install_fake_backend()
+    install_fake_backend()
+    by_name = {tool.name: tool for tool in build_default_tool_registry()}
+    by_name["ac_set_mouse_position"].invoke({"x": 1, "y": 2})
+    assert fake_state().cursor == (1, 2)
+
+
+def test_maybe_install_from_env_respects_flag(monkeypatch):
+    reset_fake_state()
+    uninstall_fake_backend()
+    monkeypatch.setenv("JE_AUTOCONTROL_FAKE_BACKEND", "1")
+    try:
+        assert maybe_install_from_env() is True
+        from je_auto_control.wrapper import auto_control_mouse as mouse_module
+        moved = mouse_module.set_mouse_position(7, 9)
+        assert moved == (7, 9)
+        assert fake_state().cursor == (7, 9)
+    finally:
+        uninstall_fake_backend()
+
+
+def test_maybe_install_from_env_skips_when_unset(monkeypatch):
+    monkeypatch.delenv("JE_AUTOCONTROL_FAKE_BACKEND", raising=False)
+    assert maybe_install_from_env() is False