Testing

Running tests

uv run poe test                  # Unit tests (no QEMU needed)
uv run poe test:integration      # Integration tests (needs QEMU + images)
uv run poe ci                    # Full CI: check + test

# Specific file or test
uv run pytest tests/unit/test_core_config.py
uv run pytest tests/unit/test_core_config.py::test_default_config -v

Writing a unit test

Unit tests go in tests/unit/. They don't need QEMU. Mock dependencies as needed.

def test_my_feature():
    from quicksand_core import SandboxConfig
    config = SandboxConfig(image="ubuntu", memory="1G")  # SandboxConfig for internal/unit testing
    assert config.memory == "1G"

Writing an integration test

Integration tests go in tests/integration/. They boot real VMs.

import pytest

@pytest.mark.integration
async def test_my_feature(tmp_dir):
    async with Sandbox(image="ubuntu") as sb:
        result = await sb.execute("echo hello")
        assert result.exit_code == 0
        assert "hello" in result.stdout

Markers

Marker	Use when
@pytest.mark.integration	Test needs QEMU — skipped by poe test
@pytest.mark.slow	Test takes significant time
@pytest.mark.docker	Test needs Docker daemon

Skip conditions (skip_no_qemu, skip_no_docker, skip_no_mke2fs) are in tests/conftest.py.

Streaming stdin integration

The stdin integration tests exercise both virtio-serial and HTTP. They require an image rebuilt with a guest agent that advertises stdin_streaming; older images skip these cases. To use a local save containing the updated agent:

QUICKSAND_STDIN_TEST_IMAGE=/path/to/updated-save \
  uv run pytest tests/integration/execution/test_stdin.py -v