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

USB Serial JTAG

By default, Wokwi diagrams use UART connections ($serialMonitor:TX/$serialMonitor:RX) for serial communication. Some targets (e.g. ESP32-P4) can use USB Serial JTAG instead. You can enable this with the --wokwi-usb-serial-jtag flag:

pytest --embedded-services idf,wokwi --wokwi-usb-serial-jtag true

This works for both auto-generated diagrams and diagrams loaded from disk (including those specified via --wokwi-diagram). When enabled, the flag will:

Set the serialInterface attribute to USB_SERIAL_JTAG on the board part
Remove any $serialMonitor connections from the diagram

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)

Metadata

Release files for pytest-embedded-wokwi 2.9.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pytest-embedded-wokwi 2.9.3
File	Size	Uploaded
pytest_embedded_wokwi-2.9.3.tar.gz	10.2 kB	Aug 31, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pytest-embedded-wokwi 2.9.3
File	Interpreter	ABI	Platform	Reset
pytest_embedded_wokwi-2.9.3-py3-none-any.whl 9.6 kB Aug 31, 2026	Python 3	none	any	Details

Total release size: 19.9 kB

Release files / pytest_embedded_wokwi-2.9.3.tar.gz

Download URL	pytest_embedded_wokwi-2.9.3.tar.gz
Size	10.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`16aac7a897b1a921890f66d8eb15f50990e2142d2f879241631a681e6e054982`
BLAKE2b-256 checksum How to use checksums	`abcc46adafa251d074c2e57fe53c99ed73d1e95d69c0c5402a4de22f1a686bab`
Upload date	Aug 31, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`python-requests/2.31.0`

Release files / pytest_embedded_wokwi-2.9.3-py3-none-any.whl

Download URL	pytest_embedded_wokwi-2.9.3-py3-none-any.whl
Size	9.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`81f99e07f8c5aa089daa5a1fe17c1924329fc4364173c0ecb991b735f298f7c4`
BLAKE2b-256 checksum How to use checksums	`6bde75e47df2f5e51c4760f2662041ac9400e891542e1c1ea865160efe6bd9ff`
Upload date	Aug 31, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`python-requests/2.31.0`