Skip to main content

Wokwi Automation Scenarios

Automation scenarios allow you to automate the simulation, push buttons, change the state of the sensors, and check the serial output. You can use automation scenarios to test your firmware in a realistic environment, and verify that it behaves as expected.

Each automation scenario is a YAML file that describes a sequence of actions that the simulator should take. You can use the --scenario CLI option to load an automation scenario file.

Scenario File Structure​

The basic structure of an automation scenario file is as follows:

name: 'Your scenario name'
version: 1
author: 'Your name'

steps:
  # List of steps:
  - set-control:
      part-id: btn1
      control: pressed
      value: 1
  - delay: 500ms
  - wait-serial: 'Button 1 pressed'
注意

Automation scenarios are currently in alpha. The API is not fully documented yet, and may change in the future. You can use the example projects as a reference.

Available Steps​

These can be used as a sequence of actions to perform when running the scenario. Use these to build a list of steps for testing your project.

Wait (delay)​

Wait for an amount of time.

Parameters​

NameDescription
valueAmount of time to wait for. Units are required (e.g. 200ms)

Example Usage​

delay: 30ms

Assert Pin Value (expect-pin)​

Check if a pin is set to an expected value.

Parameters​

NameDescription
part-idID of the target compontent
pinName of pin to check
valueExpected value of the pin

Example Usage​

expect-pin:
  part-id: esp
  pin: 2
  expected: 1

Control a Part (set-control)​

Set a controllable part of a compontent to a specified value. View part documentation for available controls or see a list of supported parts below.

Parameters​

NameDescription
part-idID of the target compontent
controlAspect of the target compontent to modify (e.g. temperature, humidity)
valueValue to set the control to

Example Usage​

set-control:
  part-id: dht
  control: humidity
  value: 39

Wait and Match Text from Serial (wait-serial)​

Wait for serial console output which matches a given string.

Parameters​

NameDescription
textString to wait and match for

Example Usage​

wait-serial: 'Ready for testing!'

Write to Serial (write-serial)​

Write text or an array of numbers to the serial console.

Parameters​

NameDescription
valueThe string or array of numbers to write to the serial console

Example Usage​

write-serial: 'Ready for testing!'

Take a Screenshot (take-screenshot)​

Take a screenshot of a specific component and compare it with an existing capture.

NameDescription
part-idID of the target compontent
save-toPath to save screenshot to
compare-withPath of a screenshot to compare with

This step requires part-id and save-to and/or compare-with.

Example usage:

take-screenshot:
  part-id: 'oled1'
  compare-with: 'screenshots/oled-1.png'

Running Scenarios​

To build the test projects and run the tests, you need to install PlatformIO Core and the Wokwi CLI, get a Wokwi CI token and set the WOKWI_CLI_TOKEN environment variable with the token.

You can then use pio run to compile the project and wokwi-cli . --scenario <scenraio_file>.yaml to run the tests. You can also use Wokwi for VS Code to interactively simulate the test projects.

Example Usage​

Example parts with test scenarios are available at the wokwi-part-tests GitHub repository. We will try to compile and run tests for the wokwi-dht22 part on the ESP32.

Begin with cloning the repository:

git clone https://github.com/wokwi/wokwi-part-tests

Navigate to the part in question:

cd wokwi-dht22/dht22-esp32

Build the required microcontroller firmware:

pio run

This can also be done via the PlatformIO VS Code extension - just click the build button.

Finally, run the test!

wokwi-cli . --scenario dht22.test.yaml

If successful, the output of the test looks as follows:

Wokwi CLI v0.18.3 (786fa8e49d9c)
Connected to Wokwi Simulation API 1.0.0-20251028-g60747fe2
Starting simulation...
ets Jul 29 2019 12:21:46
[DHT22 Sensor Test (ESP32)] Expected text matched: "ets Jul 29 2019 12:21:46"

rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0xee
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0030,len:1156
load:0x40078000,len:11456
ho 0 tail 12 room 4
load:0x40080400,len:2972
entry 0x400805dc
DHT22 test!
[DHT22 Sensor Test (ESP32)] Expected text matched: "DHT22 test!"
Humidity: 45.80%  Temperature: 23.50°C
[DHT22 Sensor Test (ESP32)] Expected text matched: "Humidity: 45.80%  Temperature: 23.50°C"
Humidity: 45.80%  Temperature: 23.50°C
[DHT22 Sensor Test (ESP32)] Expected text matched: "Humidity: 45.80%  Temperature: 23.50°C"
Humidity: 66.90%  Temperature: 21.50°C
[DHT22 Sensor Test (ESP32)] Expected text matched: "Humidity: 66.90%  Temperature: 21.50°C"
[DHT22 Sensor Test (ESP32)] Scenario completed successfully

Supported Parts with Automation Controls​

Several Wokwi parts support automation controls that can be controlled using automation scenarios. These controls allow you to programmatically change the state of sensors, press buttons, and modify component values during simulation.

Parts with Automation Controls​

Each part's documentation page contains detailed information about the specific automation controls available, including control names, types, and example usage.