Setting Up Pytest-Embedded with Wokwi Simulator for ESP32 Testing

Testing embedded systems can often be a complex task involving physical hardware setups and intricate configurations. However, with tools like Pytest-embedded and the Wokwi Simulator, this process can be significantly streamlined. This post will guide you through setting up Pytest-embedded to work with the Wokwi Simulator, using a practical example repository that demonstrates how to retrieve geolocation data from an IP address on an ESP32 device.

Prerequisite: Installing Pytest-Embedded

Before diving into testing with the Wokwi Simulator, you must first install Pytest-embedded. This tool extends Pytest, a popular Python testing framework, to support testing embedded systems software. To install Pytest-embedded and its dependencies, you can use pip:

pip install pytest-embedded

Ensure your development environment is set up with Python and that you have access to the command line or terminal for executing the installation commands.

Setting Up Your Testing Environment

You can take reference from my example project that does automated CI/CD testing of an ESP32 device using Pytest-embedded and the Wokwi Simulator. The project hayschan/esp32-ip-to-geolocation is available on GitHub. Feel free to clone or fork the repository to follow along with the setup.

This repository includes the necessary configuration files and sample code to get you started. Here’s what you need to make your project compatible:

1. pytest.ini: This file contains configuration details for Pytest, such as command line options and plugins.
2. pytest_*.py: The test file where you’ll write your tests.
3. Wokwi related files: These include diagram.json and Wokwi.toml, which are crucial for simulating the hardware on Wokwi.

Setting the WOKWI_CLI_TOKEN Environment Variable

You must obtain and set the WOKWI_CLI_TOKEN environment variable. This token allows the Wokwi CLI to authenticate with the Wokwi servers, enabling simulation capabilities.

If you have not set your token, there will be an error message when you run the tests.

> wokwi-cli .
Wokwi CLI v0.9.0 (abc2bb2a3530)
Error: Missing WOKWI_CLI_TOKEN environment variable. Please set it to your Wokwi token.
Get your token at https://wokwi.com/dashboard/ci.

To obtain the token, visit the Wokwi Dashboard and copy the token provided. Next, you need to set the WOKWI_CLI_TOKEN environment variable on your system.

There is also a guide on the WokWi dashboard when you obtain the token.

Windows

Open PowerShell and enter the following command:

$env:WOKWI_CLI_TOKEN="your_token_here"

Again, replace "your_token_here" with your token.

macOS and Linux

On macOS and Linux, the process is similar, and you typically use the terminal to set the environment variable:

export WOKWI_CLI_TOKEN="your_token_here"

Verifying the Environment Variable

To verify that your environment variable is set correctly, you can re-run the wokwi-cli command:

> wokwi-cli .
PS D:\GitHub\esp32-ip-to-geolocation> wokwi-cli .
Wokwi CLI v0.9.0 (abc2bb2a3530)
Connected to Wokwi Simulation API 1.0.0-20240527-g6fb749d7

If the output shows the version and connection details, your environment variable is set correctly.

Building the Project

Once your files and setup are ready, the next step is to build your project. This is done using Espressif’s IDF build system:

idf.py build

This command compiles your project and prepares it for deployment and testing.

Running Tests with Pytest

With your project built, you can now run tests using the following command:

pytest --embedded-services idf,wokwi

During the test session, Pytest-embedded interacts with the Wokwi Simulator, allowing for a virtualized test environment that mimics the actual hardware. Below is a snippet from a typical test session:

Conclusion

Integrating Pytest-embedded with the Wokwi Simulator provides a robust framework for testing embedded software without needing physical hardware for each test iteration. This setup not only saves time but also enhances the debugging capabilities by providing a controlled and reproducible environment. For detailed instructions and more examples, check out the example repository and start enhancing your testing workflow today!