Services

Fixtures

Please refer to instructions under the “fixtures defined from pytest_embedded.plugin” chapter of the output of pytest --fixtures.

CLI Options

Please refer to the instructions under the “embedded” or “embedded-[SERVICE]” groups of the output of pytest --help.

Dependency Graph

graph LR pytest_embedded --> pytest_embedded_serial pytest_embedded -->|pytest_embedded_serial_esp is an optional dependency| pytest_embedded_idf pytest_embedded -->|pytest_embedded_idf is an optional dependency| pytest_embedded_qemu pytest_embedded -->|pytest_embedded_serial is an optional dependency| pytest_embedded_arduino pytest_embedded -->|pytest_embedded_idf is an optional dependency| pytest_embedded_wokwi pytest_embedded_serial --> pytest_embedded_serial_esp pytest_embedded_serial --> pytest_embedded_jtag

Supported Services

Activate a service would enable a set of fixtures or add some extra functionalities to a few fixtures.

pytest-embedded-serial

pytest embedded service for testing via serial ports

Extra Functionalities:

  • serial: enable the fixture

  • dut: duplicate the serial output to pexpect_proc.

pytest-embedded-serial-esp

pytest embedded service for testing espressif boards via serial ports

Extra Functionalities:

  • serial: detect and confirm target and port by esptool automatically.

pytest-embedded-idf

pytest embedded service for esp-idf project

Extra Functionalities:

  • app: parse the built binary by idf rules and gather more information.

  • serial: auto flash the built binary into the target board at the beginning when running test cases.

pytest-embedded-jtag

pytest embedded service for openocd/gdb utilities

Extra Functionalities:

  • openocd: enable the fixture

  • gdb: enable the fixture

  • dut: duplicate the openocd output and the gdb output to dut.pexpect_proc.

pytest-embedded-qemu

pytest embedded service for running tests on QEMU instead of the real target.

Extra Functionalities:

  • app: create the qemu bootable image automatically by the built binaries.

  • qemu: enable the fixture

  • dut: duplicate the qemu output to pexpect_proc.

pytest-embedded-arduino

pytest embedded service for Arduino project

Extra Functionalities:

  • app: Parse Arduino’s build directory and gather more information.

  • serial: Auto flash the built binary into the target board at the beginning when running test cases.

pytest-embedded-wokwi

pytest-embedded service for running tests on Wokwi instead of the real target.

Wokwi supports most ESP32 targets, including: esp32, esp32s2, esp32s3, esp32c3, esp32c6, and esp32h2. In addition, it supports a wide range of peripherals, including sensors, displays, motors, and debugging tools.

Running the tests with Wokwi requires an internet connection. Your firmware is uploaded to the Wokwi server for the duration of the simulation, but it is not saved on the server. On-premises Wokwi installations are available for enterprise customers.

Wokwi CLI installation

The Wokwi plugin uses the Wokwi CLI to interact with the wokwi simulation server. You can download the precompiled CLI binaries from the releases page. Alternatively, on Linux or Mac OS, you can install the CLI using the following command:

curl -L https://wokwi.com/ci/install.sh | sh

And on Windows:

iwr https://wokwi.com/ci/install.ps1 -useb | iex

Wokwi API Tokens

Before using this plugin, you need to create a free Wokwi account and generate an API key. You can then set the WOKWI_CLI_TOKEN environment variable to the API key.

Linux / Mac OS / WSL:

export WOKWI_CLI_TOKEN="your-api-key"

Windows PowerShell:

$env:WOKWI_CLI_TOKEN="your-api-key"

Usage

To run your tests with Wokwi, make sure to specify the wokwi service when running pytest, e.g.:

pytest --embedded-services idf,wokwi

To limit the amount of simulation time, use the --wokwi-timeout flag. For example, to set the simulation time limit to 60 seconds (60000 milliseconds):

pytest --embedded-services idf,wokwi --wokwi-timeout=60000