Testing
Sandroid uses pytest. The suite (~1100 tests) lives in tests/ and mirrors
the package layout (tests/core, tests/ai, tests/tui, …). CI runs
it on Python 3.12 and 3.13 for every push and pull request against main
and dev (.github/workflows/tests.yml).
Running Tests
pip install -e ".[dev,full]"
# Run all tests
pytest
# One package / one file / one test
pytest tests/core
pytest tests/tui/test_chat_panel.py -k toggle
# With coverage
pytest --cov=sandroid --cov-report=html
Device Isolation
Tests must never act on a real device, even when a developer has an
emulator attached. tests/conftest.py enforces this for every test:
subprocesscalls (run/Popen/check_output,os.popen,asynciosubprocesses) toadb,emulator,frida*,objection,fritap,mitmdump/mitmweb,pkill/killall,iptables,gost… are recorded and replaced by a process that exits with status 1 and prints nothing (the same as a missingadb);frida.get_usb_device(),get_device(),get_device_manager(),attach(),spawn()… raisefrida.InvalidOperationError;socket connections to the adb server (5037), emulator console/adb ports (5554-5685) and frida-server (27042/27043) on localhost are refused;
the session runs with a temporary
HOME/XDG directories and working directory,ANDROID_HOME/ANDROID_SDK_ROOTpointing nowhere, and withoutSANDROID_*/ API-key environment variables, so tests neither read your~/.config/sandroidnor leave./resultsbehind.
Blocked calls are listed in the terminal summary (“sandroid device guard”).
They indicate a test that reaches the device layer without mocking it; fix
the test by mocking Adb.send_adb_command or the relevant service.
# Turn every blocked device call into a test error
SANDROID_TESTS_STRICT_DEVICE=1 pytest
# Also append blocked calls to a file
SANDROID_TESTS_BLOCKED_LOG=/tmp/blocked.log pytest
Tests that really need hardware are marked @pytest.mark.requires_device;
they are skipped unless pytest runs with --allow-device (and only those
tests then run without the guard).
Writing Tests
Follow pytest conventions and mock the device layer:
from sandroid.core.adb import Adb
def test_reads_android_version(monkeypatch):
monkeypatch.setattr(
Adb, "send_adb_command", lambda cmd, serial=None: ("35\n", "")
)
...
Textual widgets are tested headlessly with App.run_test() (see
tests/tui/); async tests need no decorator (asyncio_mode = "auto").
Testing Standards
See the Testing Requirements section of CODING_GUIDELINES.md for
coverage expectations, naming and mocking conventions.