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 for Services

The arrow points from the dependent service to the service it depends on. For example, pytest-embedded-serial-esp depends on pytest-embedded-serial.

        graph LR
    pytest-embedded-serial

    pytest-embedded-nuttx --> pytest-embedded-serial
    pytest-embedded-nuttx -->|optional, support test on espressif chips| pytest-embedded-serial-esp
    pytest-embedded-nuttx -->|optional, support test on qemu| pytest-embedded-qemu

    pytest-embedded-serial-esp --> pytest-embedded-serial

    pytest-embedded-jtag --> pytest-embedded-serial

    pytest-embedded-idf -->|optional, support test on espressif chips| pytest-embedded-serial-esp
    pytest-embedded-idf -->|optional, support test on qemu| pytest-embedded-qemu
    pytest-embedded-idf -->|optional, support test on wokwi| pytest-embedded-wokwi

    pytest-embedded-arduino -->|optional, support test on espressif chips| pytest-embedded-serial-esp
    pytest-embedded-arduino -->|optional, support test on qemu| pytest-embedded-qemu
    pytest-embedded-arduino -->|optional, support test on wokwi| pytest-embedded-wokwi

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 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

Writing Tests

When writing tests for your firmware, you can use the same pytest fixtures and assertions as you would for local testing. The main difference is that your tests will be executed in the Wokwi simulation environment and you have access to the Wokwi API for controlling the simulation through the wokwi fixture.

All interactions with the Wokwi simulation is through the wokwi.client - wokwi-python-client

For example, you can use wokwi.client.set_control() to control virtual components in the simulation, such as buttons, LEDs, and other peripherals. Whole documentations can be found at Wokwi Documentation

Button test:

import logging
from pytest_embedded_wokwi import Wokwi
from pytest_embedded import Dut


def test_gpio(dut: Dut, wokwi: Wokwi):
    LOGGER = logging.getLogger(__name__)

    LOGGER.info("Waiting for Button test begin...")
    dut.expect_exact("Butston test")

    for i in range(3):
        LOGGER.info(f"Setting button pressed for {i + 1} seconds")
        wokwi.client.set_control("btn1", "pressed", 1)

        dut.expect_exact(f"Button pressed {i + 1} times")
        wokwi.client.set_control("btn1", "pressed", 0)

pytest-embedded-nuttx

Pytest embedded service for the NuttX project, compatible with Espressif devices.

Using the ‘nuttx’ service alongside ‘serial’ enables reading from and writing to the serial port, taking NuttShell into account when running programs and retrieving return codes.

The nuttx service provides basic serial communication and testing. Adding the ‘esp’ service enables further capabilities for Espressif devices, including flashing and device rebooting. Alternatively, using the ‘qemu’ service is also supported with NuttX binaries.

Additional Features:

app: Scans the NuttX binary directory to locate firmware and bootloader files.
serial: Parses binary information and flashes the board. Requires the ‘esp’ service.
dut: Sends commands to the device through the serial port. Requires the ‘serial’ service, ‘esp’ service for Espressif devices or ‘qemu’ service for emulation.