Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

37.3 KB
Raw Blame
"""e2b semantics, over an in-memory backend (no VMs, no host processes)."""

from __future__ import annotations

import asyncio
import json

import e2b
import pytest
from e2b import (
    AsyncCommandHandle,
    AsyncSandbox,
    CommandExitException,
    CommandResult,
    FileNotFoundException,
    Sandbox,
    SandboxException,
    SandboxNotFoundException,
    TemplateException,
    TimeoutException,
)
from e2b._backend import resolve_template, set_backend
from e2b._errors import map_error
from fake_backend import FakeBackend, NotFound, Timeout, Transport


@pytest.fixture
def backend(monkeypatch):
    monkeypatch.delenv("CUA_E2B_TEMPLATES", raising=False)
    b = FakeBackend()
    set_backend(b)
    yield b
    set_backend(None)


async def _sandbox(backend, **kw) -> AsyncSandbox:
    short = kw.get("timeout")
    if isinstance(short, float) and not short.is_integer():
        # e2b's API takes whole seconds; tests that need a lifetime of a few
        # milliseconds set it on the handle
        kw.pop("timeout")
        sb = await AsyncSandbox.create(template="world-1", **kw)
        await sb._set_lifetime(short)
        return sb
    return await AsyncSandbox.create(template="world-1", **kw)


# ── commands.run: foreground ───────────────────────────────────────────────


async def test_foreground_run_returns_command_result(backend):
    sb = await _sandbox(backend)
    r = await sb.commands.run("echo hi", user="root", timeout=30)
    assert isinstance(r, CommandResult)
    assert (r.stdout, r.stderr, r.exit_code, r.error) == ("hi\n", "", 0, None)
    spawned = backend.machines[sb.sandbox_id].spawned[-1]
    # e2b runs the line with a login bash.
    assert spawned["argv"] == ["/bin/bash", "-l", "-c", "echo hi"]
    assert spawned["user"] == "root"
    assert spawned["timeout_ms"] == 30_000


async def test_nonzero_exit_raises_command_exit_exception(backend):
    sb = await _sandbox(backend)
    with pytest.raises(CommandExitException) as info:
        await sb.commands.run("fail 3")
    exc = info.value
    assert (exc.exit_code, exc.stdout, exc.stderr) == (3, "out", "err")
    # It is both a SandboxException and a CommandResult, like e2b's.
    assert isinstance(exc, SandboxException) and isinstance(exc, CommandResult)
    assert str(exc) == "Command exited with code 3 and error:\nerr"


async def test_exit_exception_is_a_result_for_callers(backend):
    # A typical caller: `except CommandExitException as exc: result = exc`.
    sb = await _sandbox(backend)
    try:
        result = await sb.commands.run("fail 1")
    except CommandExitException as exc:
        result = exc
    assert (result.exit_code, result.stdout, result.stderr) == (1, "out", "err")


async def test_default_user_and_envs(backend):
    sb = await _sandbox(backend, envs={"A": "1", "B": "1"})
    backend.machines[sb.sandbox_id].dirs.add("/w")
    await sb.commands.run("echo x", envs={"B": "2"}, user="user", cwd="/w")
    s = backend.machines[sb.sandbox_id].spawned[-1]
    assert s["user"] is None  # e2b's "user" is the Space's default user
    assert s["env"] == {"A": "1", "B": "2"}
    assert s["cwd"] == "/w"


async def test_timeout_zero_is_unlimited_and_default_is_60s(backend):
    sb = await _sandbox(backend)
    await sb.commands.run("echo x", timeout=0)
    await sb.commands.run("echo x")
    spawned = backend.machines[sb.sandbox_id].spawned
    assert [s["timeout_ms"] for s in spawned] == [None, 60_000]


async def test_command_past_its_timeout_raises_timeout(backend):
    sb = await _sandbox(backend)
    with pytest.raises(TimeoutException):
        await sb.commands.run("forever", timeout=0.05)


async def test_request_timeout_bounds_the_start(backend):
    sb = await _sandbox(backend)
    with pytest.raises(TimeoutException):
        await sb.commands.run("hang-start", request_timeout=0.05)


async def test_utf8_split_across_chunks_and_callbacks(backend):
    sb = await _sandbox(backend)
    out, err = [], []
    r = await sb.commands.run("chunks", on_stdout=out.append, on_stderr=err.append)
    assert r.stdout == "hello é\n"
    assert "".join(out) == "hello é\n" and err == ["warn"]


async def test_async_callbacks_are_awaited(backend):
    sb = await _sandbox(backend)
    seen = []

    async def cb(text):
        await asyncio.sleep(0)
        seen.append(text)

    await sb.commands.run("echo hi", on_stdout=cb)
    assert seen == ["hi\n"]


async def test_unknown_command_is_exit_127(backend):
    sb = await _sandbox(backend)
    with pytest.raises(CommandExitException) as info:
        await sb.commands.run("nope")
    assert info.value.exit_code == 127


# ── commands.run: background handles ───────────────────────────────────────


async def test_background_returns_handle_then_wait(backend):
    sb = await _sandbox(backend)
    h = await sb.commands.run("echo bg", background=True)
    assert isinstance(h, AsyncCommandHandle)
    assert isinstance(h.pid, int)
    r = await h.wait()
    assert r.stdout == "bg\n" and h.exit_code == 0 and h.stdout == "bg\n"


async def test_background_wait_raises_on_nonzero(backend):
    sb = await _sandbox(backend)
    h = await sb.commands.run("fail 2", background=True)
    with pytest.raises(CommandExitException) as info:
        await h.wait()
    assert info.value.exit_code == 2


async def test_collector_pattern_reply_then_disconnect(backend):
    """An RL tool collector: background, timeout=0, on_stdout parses the
    first line; then disconnect, which must not kill the process."""
    sb = await _sandbox(backend)
    reply = asyncio.get_running_loop().create_future()
    chunks = []

    def receive(text):
        if reply.done():
            return
        line, sep, _ = text.partition("\n")
        chunks.append(line)
        if sep:
            reply.set_result(json.loads("".join(chunks)))

    h = await sb.commands.run("reply", background=True, timeout=0, user="root", on_stdout=receive)
    waiter = asyncio.create_task(h.wait())
    await asyncio.wait((reply, waiter), return_when=asyncio.FIRST_COMPLETED)
    assert reply.result() == {"ok": True}
    assert h.exit_code is None  # still running
    await h.disconnect()
    await asyncio.gather(waiter, return_exceptions=True)
    proc = backend.machines[sb.sandbox_id].procs[h.pid]
    assert proc.detached and not proc.killed


async def test_handle_kill_then_wait(backend):
    sb = await _sandbox(backend)
    h = await sb.commands.run("forever", background=True, timeout=0)
    assert await h.kill() is True
    with pytest.raises(CommandExitException) as info:
        await h.wait()
    assert info.value.exit_code == -1


async def test_commands_kill_by_pid_and_unknown_pid(backend):
    sb = await _sandbox(backend)
    h = await sb.commands.run("forever", background=True, timeout=0)
    assert [p.pid for p in await sb.commands.list()] == [h.pid]
    assert await sb.commands.kill(h.pid) is True
    assert await sb.commands.kill(99999) is False


async def test_send_stdin(backend):
    sb = await _sandbox(backend)
    h = await sb.commands.run("forever", background=True, timeout=0, stdin=True)
    await h.send_stdin("abc")
    await sb.commands.send_stdin(h.pid, b"def")
    assert backend.machines[sb.sandbox_id].procs[h.pid].stdin == [b"abc", b"def"]
    assert backend.machines[sb.sandbox_id].spawned[-1]["stdin"] is True


# ── files ──────────────────────────────────────────────────────────────────


async def test_file_round_trip(backend):
    sb = await _sandbox(backend)
    info = await sb.files.write("/tmp/a.txt", "héllo", user="root", request_timeout=600)
    assert (info.name, info.path, info.type) == ("a.txt", "/tmp/a.txt", e2b.FileType.FILE)
    assert await sb.files.read("/tmp/a.txt") == "héllo"
    assert await sb.files.read("/tmp/a.txt", format="bytes") == bytearray("héllo".encode())
    assert await sb.files.exists("/tmp/a.txt")
    await sb.files.remove("/tmp/a.txt", user="root", request_timeout=120)
    assert not await sb.files.exists("/tmp/a.txt")


async def test_write_accepts_file_objects(backend):
    import io

    sb = await _sandbox(backend)
    await sb.files.write("/tmp/b", io.BytesIO(b"\x00\x01"))
    assert backend.machines[sb.sandbox_id].files["/tmp/b"] == b"\x00\x01"


async def test_relative_paths_resolve_against_home(backend):
    sb = await _sandbox(backend)
    await sb.files.write("x.txt", "1")
    await sb.files.write("y.txt", "2", user="root")
    files = backend.machines[sb.sandbox_id].files
    assert set(files) == {"/home/cua/x.txt", "/root/y.txt"}


async def test_read_stream(backend):
    sb = await _sandbox(backend)
    payload = bytes(range(256)) * 4096  # 1 MiB
    await sb.files.write("/tmp/big", payload)
    got = bytearray()
    async with await sb.files.read(
        "/tmp/big", format="stream", user="root", request_timeout=60
    ) as stream:
        async for chunk in stream:
            got += chunk
    assert bytes(got) == payload


async def test_missing_file_raises_file_not_found(backend):
    sb = await _sandbox(backend)
    with pytest.raises(FileNotFoundException):
        await sb.files.read("/nope")
    with pytest.raises(FileNotFoundException):
        await sb.files.get_info("/nope")


# ── sandbox lifecycle ──────────────────────────────────────────────────────


async def test_get_host_is_sync_and_cached(backend):
    sb = await _sandbox(backend)
    host = sb.get_host(8080)
    assert host == "127.0.0.1:48080"
    assert sb.get_host(8080) is host
    assert "://" not in host


async def test_kill_deletes_once(backend):
    sb = await _sandbox(backend)
    assert await sb.kill(request_timeout=120) is True
    assert backend.machines[sb.sandbox_id].deleted
    assert await sb.kill() is False


async def test_kill_by_id_classmethod(backend):
    sb = await _sandbox(backend)
    assert await AsyncSandbox.kill(sb.sandbox_id) is True
    assert await AsyncSandbox.kill("missing") is False


async def test_lifetime_timeout_kills_and_set_timeout_extends(backend):
    sb = await _sandbox(backend, timeout=0.05)
    other = await _sandbox(backend, timeout=0.05)
    await other.set_timeout(5)
    await asyncio.sleep(0.15)
    assert backend.machines[sb.sandbox_id].deleted
    assert not backend.machines[other.sandbox_id].deleted
    await other.kill()


async def test_create_passes_template_and_maps_errors(backend):
    sb = await _sandbox(backend)
    assert backend.machines[sb.sandbox_id].template == "world-1"
    backend.fail_create = NotFound("image not found")
    # e2b: a plain SandboxException carrying the API's text
    with pytest.raises(SandboxException) as ei:
        await AsyncSandbox.create(template="nope")
    assert type(ei.value) is SandboxException
    assert str(ei.value) == "404: template 'nope' not found"
    with pytest.raises(
        SandboxException, match="^400: Invalid template reference: invalid template ID: No Way!$"
    ):
        await AsyncSandbox.create(template="No Way!")


async def test_create_snapshot_and_pause(backend):
    sb = await _sandbox(backend)
    snap = await sb.create_snapshot("baked")
    assert snap.snapshot_id == "baked" and snap.names == ["baked"]
    assert await sb.pause() is True
    await sb.connect()
    assert not backend.machines[sb.sandbox_id].suspended


async def test_unsupported_create_options_refuse(backend):
    with pytest.raises(SandboxException):
        await AsyncSandbox.create(template="x", mcp={"github": {}})


async def test_async_context_manager_kills(backend):
    async with await _sandbox(backend) as sb:
        pass
    assert backend.machines[sb.sandbox_id].deleted


# ── templates and errors ───────────────────────────────────────────────────


def test_template_mapping(monkeypatch, tmp_path):
    monkeypatch.setenv("CUA_E2B_TEMPLATES", json.dumps({"snap_abc": "world-ckpt"}))
    assert resolve_template("snap_abc") == "world-ckpt"
    assert resolve_template("other") == "other"
    path = tmp_path / "m.json"
    path.write_text(json.dumps({"snap_abc": "from-file"}))
    monkeypatch.setenv("CUA_E2B_TEMPLATES", str(path))
    assert resolve_template("snap_abc") == "from-file"
    monkeypatch.delenv("CUA_E2B_TEMPLATES")
    monkeypatch.setenv("CUA_E2B_IMAGE", "ghcr.io/x/linux:1")
    assert resolve_template(None) == "ghcr.io/x/linux:1"
    assert resolve_template("base") == "ghcr.io/x/linux:1"


def test_error_mapping():
    assert isinstance(map_error(NotFound("x")), SandboxNotFoundException)
    assert isinstance(map_error(NotFound("x"), file=True), FileNotFoundException)
    assert isinstance(map_error(Timeout("x")), TimeoutException)
    t = map_error(Transport("reset"))
    assert type(t) is SandboxException  # transient for retry policies
    plain = ValueError("x")
    assert map_error(plain) is plain


def test_exception_hierarchy_matches_e2b():
    assert issubclass(e2b.FileNotFoundException, e2b.NotFoundException)
    assert issubclass(e2b.SandboxNotFoundException, e2b.NotFoundException)
    assert issubclass(e2b.NotFoundException, e2b.SandboxException)
    assert issubclass(e2b.TemplateException, e2b.SandboxException)
    assert not issubclass(e2b.AuthenticationException, e2b.SandboxException)
    assert issubclass(e2b.TimeoutException, e2b.SandboxException)


# ── synchronous Sandbox ────────────────────────────────────────────────────


def test_sync_sandbox(backend):
    sb = Sandbox.create(template="world-1")
    assert sb.commands.run("echo s").stdout == "s\n"
    with pytest.raises(CommandExitException):
        sb.commands.run("fail 4")
    h = sb.commands.run("echo bg", background=True)
    assert h.wait().stdout == "bg\n"
    sb.files.write("/tmp/s", b"abc")
    assert sb.files.read("/tmp/s") == "abc"
    assert b"".join(sb.files.read("/tmp/s", format="stream")) == b"abc"
    assert sb.get_host(9000) == "127.0.0.1:49000"
    assert sb.kill() is True


# ── behaviour observed against real e2b 2.42 sandboxes (conformance run) ──


async def test_error_strings_match_e2b(backend):
    sb = await _sandbox(backend)
    with pytest.raises(CommandExitException) as info:
        await sb.commands.run("fail 3")
    assert info.value.error == "exit status 3"
    h = await sb.commands.run("forever", background=True, timeout=0)
    await h.kill()
    with pytest.raises(CommandExitException) as info:
        await h.wait()
    assert (info.value.exit_code, info.value.error) == (-1, "signal: killed")


async def test_remove_missing_is_not_an_error(backend):
    sb = await _sandbox(backend)
    assert await sb.files.remove("/nope") is None


async def test_calls_after_kill_raise_timeout(backend):
    sb = await _sandbox(backend)
    await sb.kill()
    with pytest.raises(TimeoutException, match="The sandbox was not found"):
        await sb.commands.run("echo x")
    with pytest.raises(TimeoutException):
        await sb.files.read("/tmp/x")


async def test_lifetime_expiry_then_calls_raise_timeout(backend):
    sb = await _sandbox(backend, timeout=0.02)
    await asyncio.sleep(0.1)
    with pytest.raises(TimeoutException):
        await sb.commands.run("echo x")


# ── lifetimes, network, pause/resume ──────────────────────────────────────


async def test_lifetime_goes_to_the_backend_with_its_action(backend):
    sb = await _sandbox(backend, timeout=600)
    assert backend.machines[sb.sandbox_id].lifetime == (600, "delete")
    await sb.set_timeout(30)
    assert backend.machines[sb.sandbox_id].lifetime == (30, "delete")
    paused = await _sandbox(backend, timeout=60, lifecycle={"on_timeout": "pause"})
    assert backend.machines[paused.sandbox_id].lifetime == (60, "suspend")
    default = await _sandbox(backend)
    assert backend.machines[default.sandbox_id].lifetime == (300, "delete")


async def test_set_timeout_by_id(backend):
    sb = await _sandbox(backend)
    await AsyncSandbox.set_timeout(sb.sandbox_id, 42)
    assert backend.machines[sb.sandbox_id].lifetime == (42, "delete")


async def test_pause_lifetime_then_auto_resume(backend):
    sb = await _sandbox(
        backend, timeout=0.02, lifecycle={"on_timeout": "pause", "auto_resume": True}
    )
    await asyncio.sleep(0.08)
    m = backend.machines[sb.sandbox_id]
    assert m.suspended and not m.deleted
    sb._paused = True  # what get_info would report after the daemon paused it
    assert (await sb.commands.run("echo back")).stdout == "back\n"
    assert not m.suspended


async def test_bad_lifecycle_is_refused(backend):
    with pytest.raises(e2b.InvalidArgumentException):
        await _sandbox(backend, lifecycle={"on_timeout": "explode"})


async def test_no_internet_is_network_none(backend):
    off = await _sandbox(backend, allow_internet_access=False)
    on = await _sandbox(backend)
    deny_all = await _sandbox(backend, network={"deny_out": [e2b.ALL_TRAFFIC]})
    assert backend.machines[off.sandbox_id].network == "none"
    assert backend.machines[on.sandbox_id].network is None
    assert backend.machines[deny_all.sandbox_id].network == "none"
    info = await off.get_info()
    assert info.allow_internet_access is False


async def test_ip_rules_become_egress_rules_in_the_space(backend):
    sb = await _sandbox(
        backend, network={"allow_out": ["1.2.3.4", "10.0.0.0/8"], "deny_out": [e2b.ALL_TRAFFIC]}
    )
    m = backend.machines[sb.sandbox_id]
    assert m.network is None
    assert m.egress == {"allow": ["1.2.3.4", "10.0.0.0/8"], "deny": ["0.0.0.0/0"]}
    info = await sb.get_info()
    assert info.network == {
        "allow_out": ["1.2.3.4", "10.0.0.0/8"],
        "deny_out": ["0.0.0.0/0"],
        "allow_public_traffic": True,
    }
    assert info.allow_internet_access is False
    only_deny = await _sandbox(backend, network={"deny_out": ["8.8.8.8"]})
    assert backend.machines[only_deny.sandbox_id].egress == {"allow": [], "deny": ["8.8.8.8"]}


async def test_proxy_rules_are_refused_not_dropped(backend):
    with pytest.raises(e2b.InvalidArgumentException, match="TLS-intercepting proxy"):
        await _sandbox(
            backend, network={"rules": {"api.x.com": [{"transform": {"headers": {"a": "b"}}}]}}
        )
    with pytest.raises(e2b.InvalidArgumentException, match="TLS-intercepting proxy"):
        await _sandbox(backend, network={"egress_proxy": {"address": "p:1080"}})


async def test_pause_and_connect(backend):
    sb = await _sandbox(backend)
    assert await sb.pause() is True
    assert not await sb.is_running()
    await AsyncSandbox.connect(sb.sandbox_id)
    assert not backend.machines[sb.sandbox_id].suspended


async def test_pause_modes_and_cold_resume(backend):
    """e2b 2.56: pause(mode=...), the deprecated keep_memory, connect(on_resume=...)."""
    full = await _sandbox(backend)
    await full.pause()
    await AsyncSandbox.connect(full.sandbox_id)
    assert backend.machines[full.sandbox_id].reboots == 0  # memory restored

    for kwargs in ({"mode": "filesystem"}, {"keep_memory": False}):
        sb = await _sandbox(backend)
        await sb.pause(**kwargs)
        await AsyncSandbox.connect(sb.sandbox_id)
        assert backend.machines[sb.sandbox_id].reboots == 1  # cold boot from disk

    kept = await _sandbox(backend)
    await kept.pause(mode="full")
    await AsyncSandbox.connect(kept.sandbox_id)
    assert backend.machines[kept.sandbox_id].reboots == 0

    again = await _sandbox(backend)
    await again.pause(mode="filesystem")
    await again.connect()  # on the instance too
    assert backend.machines[again.sandbox_id].reboots == 1

    with pytest.raises(e2b.InvalidArgumentException, match="not both"):
        await (await _sandbox(backend)).pause(keep_memory=True, mode="full")
    with pytest.raises(e2b.InvalidArgumentException, match="full, filesystem"):
        await (await _sandbox(backend)).pause(mode="disk")


async def test_connect_on_resume_reboot(backend):
    sb = await _sandbox(backend)
    await sb.pause()
    await AsyncSandbox.connect(sb.sandbox_id, on_resume="reboot")
    assert backend.machines[sb.sandbox_id].reboots == 1
    running = await _sandbox(backend)
    await AsyncSandbox.connect(running.sandbox_id, on_resume="reboot")
    assert backend.machines[running.sandbox_id].reboots == 0  # only a paused one reboots
    with pytest.raises(e2b.InvalidArgumentException, match="restore, reboot"):
        await AsyncSandbox.connect(sb.sandbox_id, on_resume="now")


async def test_lifecycle_object_form_and_its_rules(backend):
    sb = await _sandbox(
        backend, lifecycle={"on_timeout": {"action": "pause", "mode": "filesystem"}}
    )
    assert backend.machines[sb.sandbox_id].lifetime == (300, "suspend")
    assert backend.records[sb.sandbox_id]["resume"] == "cold"
    assert (await sb.get_info()).lifecycle["on_timeout"] == "pause"
    plain = await _sandbox(backend, lifecycle={"on_timeout": {"action": "pause"}})
    assert "resume" not in backend.records[plain.sandbox_id]
    for bad, text in (
        ({"on_timeout": {"action": "kill", "mode": "full"}}, "only allowed"),
        ({"on_timeout": "kill", "auto_resume": True}, "can only be True"),
        (
            {"on_timeout": {"action": "pause", "mode": "filesystem"}, "auto_resume": True},
            "filesystem",
        ),
        ({"on_timeout": {"action": "boom"}}, 'on_timeout\\["action"\\]'),
    ):
        with pytest.raises(e2b.InvalidArgumentException, match=text):
            await _sandbox(backend, lifecycle=bad)


async def test_snapshot_modes_and_none_defaults(backend):
    sb = await _sandbox(backend, secure=None, allow_internet_access=None)
    assert backend.machines[sb.sandbox_id].network is None  # None is e2b's "internet on"
    await sb.create_snapshot("warm", mode="filesystem")
    await sb.create_snapshot("hot")
    assert backend.machines[sb.sandbox_id].cold_snapshots == {"warm": True, "hot": False}
    with pytest.raises(e2b.InvalidArgumentException):
        await sb.create_snapshot("x", mode="memory")


async def test_snapshots_list_and_delete(backend):
    sb, other = await _sandbox(backend), await _sandbox(backend)
    await sb.create_snapshot("one")
    await other.create_snapshot("two")
    every = await AsyncSandbox.list_snapshots().next_items()
    assert sorted(i.snapshot_id for i in every) == ["one", "two"]
    mine = await sb.list_snapshots().next_items()
    assert [i.snapshot_id for i in mine] == ["one"]
    assert [i.snapshot_id for i in await AsyncSandbox.list_snapshots(name="two").next_items()] == [
        "two"
    ]
    assert await AsyncSandbox.delete_snapshot("one") is True
    assert await AsyncSandbox.delete_snapshot("one") is False
    assert [i.snapshot_id for i in await AsyncSandbox.list_snapshots().next_items()] == ["two"]


async def test_fork_a_running_sandbox(backend):
    sb = await _sandbox(backend, metadata={"k": "v"})
    await sb.files.write("/tmp/x", "hello")
    forks = await sb.fork(count=3, timeout=90)
    assert len(forks) == 3 and all(isinstance(f, AsyncSandbox) for f in forks)
    assert len({f.sandbox_id for f in forks}) == 3
    assert backend.machines[forks[0].sandbox_id].lifetime == (90, "delete")
    assert (await forks[0].files.read("/tmp/x")) == "hello"
    assert forks[0].metadata == {"k": "v"}
    by_id = await AsyncSandbox.fork(sb.sandbox_id)  # the class form, count defaults to 1
    assert len(by_id) == 1
    with pytest.raises(e2b.InvalidArgumentException):
        await sb.fork(count=21)
    # a fork that cannot start is reported in its slot, not raised
    await sb.pause()
    again = await AsyncSandbox.connect(sb.sandbox_id)
    backend.machines[again.sandbox_id].suspended = True
    got = await again.fork(count=2)
    assert len(got) == 2 and all(isinstance(r, Exception) for r in got)


async def test_list_order(backend):
    a, b = await _sandbox(backend), await _sandbox(backend)
    for i, sb in enumerate((a, b)):
        backend.records[sb.sandbox_id]["started"] = i
    got = [i.sandbox_id for i in await AsyncSandbox.list(order="desc").next_items()]
    assert sorted(got) == sorted([a.sandbox_id, b.sandbox_id])
    # like e2b, the order is checked when the page is fetched
    with pytest.raises(e2b.InvalidArgumentException):
        await AsyncSandbox.list(order="sideways").next_items()


# ── files: stream, owners, metadata, rename, watch ─────────────────────────


async def test_stream_cancels_on_early_close(backend):
    sb = await _sandbox(backend)
    await sb.files.write("/tmp/s", b"x" * (300 * 1024))
    reader = await sb.files.read("/tmp/s", format="stream")
    first = await reader.__anext__()
    assert len(first) == 64 * 1024
    await reader.aclose()
    assert reader._d.cancelled


async def test_stream_of_missing_file_fails_at_once(backend):
    sb = await _sandbox(backend)
    with pytest.raises(FileNotFoundException):
        await sb.files.read("/nope", format="stream")


async def test_write_gives_the_file_to_the_user(backend):
    sb = await _sandbox(backend)
    m = backend.machines[sb.sandbox_id]
    await sb.files.write("/tmp/as-user", "1")  # default user: cua
    await sb.files.write("/tmp/as-root", "1", user="root")
    assert m.owners["/tmp/as-user"] == "cua"
    assert m.owners["/tmp/as-root"] == "root"
    info = await sb.files.get_info("/tmp/as-user")
    assert (info.owner, info.group) == ("cua", "cua")


async def test_write_metadata_round_trip(backend):
    sb = await _sandbox(backend)
    w = await sb.files.write("/tmp/m", "x", metadata={"Kind": "input"})
    assert w.metadata == {"kind": "input"}
    assert (await sb.files.get_info("/tmp/m")).metadata == {"kind": "input"}


async def test_rename(backend):
    sb = await _sandbox(backend)
    await sb.files.write("/tmp/a", "1")
    info = await sb.files.rename("/tmp/a", "/tmp/b")
    assert info.path == "/tmp/b"
    assert await sb.files.read("/tmp/b") == "1"
    with pytest.raises(FileNotFoundException):
        await sb.files.rename("/tmp/missing", "/tmp/c")


async def test_watch_dir(backend):
    sb = await _sandbox(backend)
    seen = []
    handle = await sb.files.watch_dir("/w", on_event=seen.append, timeout=0)
    await sb.files.write("/w/new.txt", "1")
    for _ in range(50):
        if seen:
            break
        await asyncio.sleep(0.05)
    await handle.stop()
    assert seen and seen[0].name == "new.txt"
    assert seen[0].type == e2b.FilesystemEventType.WRITE


# ── pty, info, list ────────────────────────────────────────────────────────


async def test_pty(backend):
    sb = await _sandbox(backend)
    out = []
    h = await sb.pty.create(e2b.PtySize(rows=24, cols=80), on_data=out.append)
    spawned = backend.machines[sb.sandbox_id].spawned[-1]
    assert spawned["argv"] == ["/bin/bash", "-i", "-l"] and spawned["pty"] == (80, 24)
    assert spawned["env"]["TERM"] == "xterm-256color"
    await sb.pty.send_stdin(h.pid, b"ls\r")
    await sb.pty.resize(h.pid, e2b.PtySize(rows=40, cols=120))
    for _ in range(20):
        if out:
            break
        await asyncio.sleep(0.01)
    assert out == [b"ls\r"]
    assert backend.machines[sb.sandbox_id].procs[h.pid].size == (120, 40)
    assert await sb.pty.kill(h.pid) is True


async def test_get_info_and_metrics(backend):
    sb = await _sandbox(backend, metadata={"run": "7"})
    info = await sb.get_info()
    assert info.sandbox_id == sb.sandbox_id and info.template_id == "world-1"
    assert info.metadata == {"run": "7"} and info.state == "running"
    assert info.cpu_count == 2 and info.memory_mb == 3906
    [m] = await sb.get_metrics()
    assert isinstance(m, e2b.SandboxMetrics) and m.cpu_used_pct == 12.5
    assert m.mem_used == 1024000000 and m.disk_total == 1000


async def test_list_with_metadata_query(backend):
    a = await _sandbox(backend, metadata={"run": "a"})
    await _sandbox(backend, metadata={"run": "b"})
    pager = AsyncSandbox.list(query=e2b.SandboxQuery(metadata={"run": "a"}))
    assert pager.has_next
    items = await pager.next_items()
    assert [i.sandbox_id for i in items] == [a.sandbox_id]
    assert not pager.has_next
    await a.kill()
    assert a.sandbox_id not in [i.sandbox_id for i in await AsyncSandbox.list().next_items()]


def test_sync_pty_watch_and_list(backend):
    sb = Sandbox.create(template="world-1")
    w = sb.files.watch_dir("/w")
    sb.files.write("/w/x", "1")
    events = w.get_new_events()
    assert [e.name for e in events] == ["x"]
    w.stop()
    assert [i.sandbox_id for i in Sandbox.list().next_items()] == [sb.sandbox_id]
    h = sb.pty.create(e2b.PtySize(rows=24, cols=80))
    assert sb.pty.kill(h.pid) is True
    sb.kill()


# ── git ────────────────────────────────────────────────────────────────────


def test_git_status_parsing():
    from e2b.sandbox_async.git import parse_status

    st = parse_status(
        "## main...origin/main [ahead 2, behind 1]\n"
        " M changed.py\n"
        "A  added.py\n"
        "R  old.py -> new.py\n"
        "UU both.py\n"
        "?? new.txt\n"
    )
    assert (st.current_branch, st.upstream, st.ahead, st.behind, st.detached) == (
        "main",
        "origin/main",
        2,
        1,
        False,
    )
    by = {f.name: f for f in st.file_status}
    assert by["changed.py"].status == "modified" and not by["changed.py"].staged
    assert by["added.py"].staged and by["new.py"].renamed_from == "old.py"
    assert by["both.py"].status == "conflict" and st.has_conflicts
    assert st.untracked_count == 1 and st.staged_count == 3
    fresh = parse_status("## No commits yet on main\n?? a.txt\n")
    assert fresh.current_branch == "main" and fresh.has_untracked
    assert parse_status("## HEAD (no branch)\n").detached


async def test_git_runs_git_commands(backend):
    sb = await _sandbox(backend)
    with pytest.raises(CommandExitException):  # the fake has no git
        await sb.git.init("/r", initial_branch="main")
    argv = backend.machines[sb.sandbox_id].spawned[-1]["argv"]
    assert argv[-1] == "git init --initial-branch main /r"
    assert backend.machines[sb.sandbox_id].spawned[-1]["env"]["GIT_TERMINAL_PROMPT"] == "0"


# ── templates: a recipe built into a snapshot, or a container image ───────


async def test_template_recipe_runs_in_a_vm_and_is_snapshotted(backend, tmp_path):
    backend.permissive = True
    (tmp_path / "app").mkdir()
    (tmp_path / "app" / "main.py").write_text("print('hi')")
    logs = []
    t = (
        e2b.Template(file_context_path=tmp_path)
        .from_base_image()
        .set_envs({"MODE": "rl"})
        .set_workdir("/srv")
        .copy("app", "/srv/app")
        .run_cmd(["echo one", "echo two"])
        .apt_install(["git"], no_install_recommends=True)
        .set_start_cmd("serve /srv/app/main.py", e2b.wait_for_port(8080))
    )
    info = await e2b.AsyncTemplate.build(t, "world-7", on_build_logs=logs.append)
    assert (info.name, info.template_id) == ("world-7", "world-7")
    snapshot = f"world-7-{info.build_id}"
    builder = next(m for m in backend.machines.values() if snapshot in m.cold_snapshots)
    assert builder.deleted  # the builder is gone, the snapshot stays
    ran = [s["argv"][-1] for s in builder.spawned]
    assert "echo one && echo two" in ran
    assert any("apt-get install -y --no-install-recommends git" in c for c in ran)
    assert any("serve /srv/app/main.py" in c for c in ran)
    assert builder.files["/srv/app/main.py"] == b"print('hi')"
    assert backend.templates["world-7"]["snapshot"] == snapshot
    assert backend.templates["world-7:default"]["snapshot"] == snapshot
    assert await e2b.AsyncTemplate.exists("world-7") is True
    assert any("step 3/" in str(e) for e in logs)
    status = await e2b.AsyncTemplate.get_build_status(info)
    assert status.status == "ready"
    assert await e2b.AsyncTemplate.delete("world-7") is True
    assert await e2b.AsyncTemplate.exists("world-7") is False


async def test_template_from_an_oci_image_is_refused_with_the_way_out(backend):
    t = e2b.Template().from_python_image("3.12").run_cmd("pip install requests")
    with pytest.raises(e2b.BuildException, match="cua images build"):
        await e2b.AsyncTemplate.build(t, "web")
    assert backend.template("web") is None
    ok = e2b.Template().from_image("linux").run_cmd("echo hi")
    backend.permissive = True
    await e2b.AsyncTemplate.build(ok, "fine")
    assert backend.template("fine")["kind"] == "snapshot"


async def test_template_dockerfile_and_exports(backend, tmp_path):
    df = 'FROM python:3.12\nENV A=1\nWORKDIR /w\nRUN pip install x \\\n  && echo ok\nCMD ["python", "-m", "app"]\n'
    t = e2b.Template().from_dockerfile(df)
    text = e2b.Template.to_dockerfile(t)
    assert text.splitlines()[0] == "FROM python:3.12"
    assert "RUN pip install x   && echo ok" in text and "ENTRYPOINT python -m app" in text
    assert json.loads(e2b.Template.to_json(t))["startCmd"] == "python -m app"
    with pytest.raises(e2b.DockerfileSyntaxError, match="FROM"):
        e2b.Template().from_dockerfile("RUN echo no from")
    with pytest.raises(TemplateException, match="Name must be provided"):
        await e2b.AsyncTemplate.build(t)  # no name
    with pytest.raises(e2b.BuildException, match="mcp-gateway"):
        t.add_mcp_server("github")


async def test_a_failed_template_build_is_a_build_exception(backend):
    t = e2b.Template().from_base_image().run_cmd("fail 3")
    with pytest.raises(e2b.BuildException):
        await e2b.AsyncTemplate.build(t, "bad")
    assert backend.template("bad") is None


# ── volumes ───────────────────────────────────────────────────────────────


async def test_volume_files_roundtrip_on_cua_volume(backend):
    v = await e2b.AsyncVolume.create("data")
    assert (v.volume_id, v.name) == ("data", "data")
    assert [i.name for i in await e2b.AsyncVolume.list()] == ["data"]
    st = await v.write_file("/a/b.txt", "hello", mode=0o600, force=True)
    assert (st.name, st.size, st.mode, st.type) == ("b.txt", 5, 0o600, e2b.VolumeFileType.FILE)
    assert await v.read_file("/a/b.txt") == "hello"
    assert await v.read_file("a/b.txt", format="bytes") == b"hello"
    chunks = [c async for c in await v.read_file("/a/b.txt", format="stream")]
    assert b"".join(chunks) == b"hello"
    assert await v.exists("/a") and await v.exists("/a/b.txt") and not await v.exists("/a/c")
    await v.make_dir("/empty")
    assert await v.exists("/empty")
    assert (await v.update_metadata("/a/b.txt", uid=7)).uid == 7
    assert "e2b-volumes/data/a/b.txt" in backend.volume.files  # a folder of Cua Volume
    with pytest.raises(e2b.VolumePathNotFoundException):
        await v.read_file("/nope")
    await v.remove("/a")
    assert not await v.exists("/a/b.txt")
    again = await e2b.AsyncVolume.connect("data")
    assert again.name == "data"
    info = await e2b.AsyncVolume.get_info("data")
    assert info.volume_id == "data"
    assert await e2b.AsyncVolume.destroy("data") is True
    assert await e2b.AsyncVolume.destroy("data") is False
    with pytest.raises(e2b.VolumeNotFoundException):
        await e2b.AsyncVolume.connect("data")


def test_volume_sync_wrapper(backend):
    v = e2b.Volume.create("sync")
    v.write_file("/x", b"1")
    assert v.read_file("/x", format="bytes") == b"1"
    assert b"".join(v.read_file("/x", format="stream")) == b"1"
    assert [i.volume_id for i in e2b.Volume.list()] == ["sync"]
    assert e2b.Volume.destroy("sync") is True


async def test_volume_mounts_link_the_volume_folder_when_mounted(backend):
    backend.permissive = True
    v = await e2b.AsyncVolume.create("data")
    backend.volume_mounted = True
    sb = await AsyncSandbox.create(template="world-1", volume_mounts={"/mnt/data": v})
    ran = [s["argv"][-1] for s in backend.machines[sb.sandbox_id].spawned]
    assert any("ln -sfn /volume/e2b-volumes/data /mnt/data" in c for c in ran)
    backend.volume_mounted = False
    before = len(backend.machines)
    with pytest.raises(e2b.InvalidArgumentException, match="Cua Volume mounted"):
        await AsyncSandbox.create(template="world-1", volume_mounts={"/mnt/data": "data"})
    assert all(m.deleted for m in list(backend.machines.values())[before:])  # not left behind


async def test_mcp_starts_the_gateway_as_e2b_does_and_iam_is_refused(backend):
    backend.permissive = True
    sb = await _sandbox(backend, mcp={"github": {"x": 1}})
    m = backend.machines[sb.sandbox_id]
    started = [c for c in m.spawned if "mcp-gateway" in c["argv"][-1]][0]
    assert started["user"] == "root" and started["env"]["GATEWAY_ACCESS_TOKEN"] == sb._mcp_token
    assert started["argv"][-1].startswith("mcp-gateway --config ")
    assert sb.get_mcp_url().startswith("http://") and sb.get_mcp_url().endswith("/mcp")
    backend.permissive = False
    with pytest.raises(e2b.SandboxException, match="Failed to start MCP gateway"):
        await _sandbox(backend, mcp={"github": {}})
    assert all(m.deleted for m in list(backend.machines.values())[1:])  # no sandbox left behind
    with pytest.raises(e2b.InvalidArgumentException, match="Keyvault"):
        await _sandbox(
            backend, iam={"tokens": {"aws": {"audience": "sts", "token_type": "JWT-SVID"}}}
        )