Files
etchdroid/appium-tests
Davide Depau 99965a7f3c fix(appium-tests): don't let the lay-flat wait eat the write phase
On CI the sheet auto-proceeds -- the emulated gravity sensor reads flat
and the job starts on its own -- so waiting the full timeout for a
button that is already gone burned 15-30s of a ~28s job. The test then
went looking for a write phase that had already finished, which is why
the unplug tests failed while their job ran to a clean FINISHED.

Wait briefly instead: confirm_write_image already established that the
sheet was up, so the button is either there now or the job is running.
2026-08-16 19:40:49 +02:00
..
2025-03-31 00:20:46 +02:00
2025-03-31 00:20:46 +02:00
2026-04-30 15:59:13 +02:00
2026-04-30 15:59:13 +02:00

EtchDroid end-to-end tests

This directory contains code to test EtchDroid on real and emulated devices.

The tests are written in Python using pytest, making use of Appium for interactive UI testing.

Test modules

The tests are divided into two modules:

  • test_generic.py: tests that run on any device, including real devices, provided that a USB drive of at least 2GB is connected (it will be erased).
  • test_qemu.py: tests that must be run using QEMU (not the Android emulator!), since they interact with the QEMU monitor console to connect and disconnect emulated USB drives.

Requirements

  • The Android SDK must be installed. It should either be stored under ~/Android/Sdk (Android Studio default) or specified using the ANDROID_HOME environment variable.
  • uv must be installed
  • 7z, qemu-img and qemu for VM testing.
  • node and npm to install Appium:
    # Inside the appium-tests/ directory
    npm ci
    

On a real device

Warning

The tests will erase the content of the connected USB drive. Some wear is to be expected on the drive since random data will be written to it.

  1. Connect the device to the computer using wireless ADB (for older devices: connect via USB and run adb tcpip 5555 && adb connect <device-ip>:5555).
  2. Connect a USB drive of at least 2GB to the device.
  3. Build and install EtchDroid: ./gradlew installFossDebug
  4. Run the tests using pytest from the appium-tests/ directory, excluding those specifically designed to run in a VM:
    uv run pytest -m "not qemu" -sv
    

Note

Running the tests in a VM is recommended over a physical device since it allows testing the USB hotplugging logic without risking damage to physical drives. The VM is configured to use a virtual USB drive that can be safely erased and re-created on each test run.

Make sure to have qemu-system-x86_64 installed.

  1. Prepare the VM files:

    ./appium-tests/scripts/prepare-vm.sh
    

    This will download the Bliss OS ISO, extract the required files, and create a virtual USB drive image in the .appium-vm/ directory.

  2. Launch QEMU (in a separate terminal):

    ./appium-tests/scripts/run-vm.sh
    

    This starts the VM with a GTK UI and redirects the serial console to stdio. ADB will be available on localhost:5556.

  3. Wait for startup and configure:

    ./appium-tests/scripts/wait-vm-startup.sh
    

    This script waits for the VM to be reachable via ADB and applies necessary settings (like setting the default launcher) for the tests to run reliably.

    We recommend running this script at least once before running the tests to ensure the VM is properly configured, even if the ADB connection is working already.

  4. Build and install EtchDroid:

    ./gradlew installFossDebug
    
  5. Run the tests from the appium-tests/ directory:

    uv run pytest -sv
    

Notes

  • The tests expect a USB drive to be connected before the tests start (the script handles this for QEMU).
  • Warning: The tests will erase the content of the connected USB drive if run on a physical device.
  • Both the QMP and monitor sockets are used by the tests to simulate USB hotplugging in QEMU.