Skip to content

Commit 4294405

Browse files
krisjdevkrisjdev
committed
docs(wokwi-ci/automation): add available steps and running instructions
1 parent 4409ed0 commit 4294405

File tree

1 file changed

+176
-0
lines changed

1 file changed

+176
-0
lines changed

‎docs/wokwi-ci/automation-scenarios.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,15 @@ sidebar_label: Automation Scenarios
44
description: Automate simulations in Wokwi using YAML-based automation scenarios. Simulate button presses, sensor input, and verify serial output to test firmware programmatically.
55
keywords: [automation, simulation testing, YAML automation scenarios, embedded simulation, automated firmware testing, sensor state simulation]
66
---
7+
import Tabs from '@theme/Tabs';
8+
import TabItem from '@theme/TabItem';
79

810
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.
911

1012
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.
1113

14+
## Scenario File Structure
15+
1216
The basic structure of an automation scenario file is as follows:
1317

1418
```yaml
@@ -30,6 +34,178 @@ steps:
3034
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](github-actions#examples) as a reference.
3135
:::
3236
37+
## Available Steps
38+
39+
These can be used as a sequence of actions to perform when running the scenario. Use these to build a list of steps for
40+
testing your project.
41+
42+
### Wait (`delay`)
43+
Wait for an amount of time.
44+
45+
#### Parameters
46+
| Name | Description |
47+
| :- | :- |
48+
| `value` | Amount of time to wait for. Units are required (e.g. `200ms`) |
49+
50+
#### Example Usage
51+
```yaml
52+
delay: 30ms
53+
```
54+
55+
### Assert Pin Value (`expect-pin`)
56+
Check if a pin is set to an expected value.
57+
58+
#### Parameters
59+
| Name | Description |
60+
| :- | :- |
61+
| `part-id` | ID of the target compontent |
62+
| `pin` | Name of pin to check |
63+
| `value` | Expected value of the pin |
64+
65+
#### Example Usage
66+
```yaml
67+
expect-pin:
68+
part-id: esp
69+
pin: 2
70+
expected: 1
71+
```
72+
73+
### Control a Part (`set-control`)
74+
Set a controllable part of a compontent to a specified value. View part documentation for available controls or see a
75+
list of [supported parts](#supported-parts-with-automation-controls) below.
76+
77+
#### Parameters
78+
| Name | Description |
79+
| :- | :- |
80+
| `part-id` | ID of the target compontent |
81+
| `control` | Aspect of the target compontent to modify (e.g. temperature, humidity) |
82+
| `value` | Value to set the `control` to |
83+
84+
#### Example Usage
85+
```yaml
86+
set-control:
87+
part-id: dht
88+
control: humidity
89+
value: 39
90+
```
91+
92+
### Wait and Match Text from Serial (`wait-serial`)
93+
Wait for serial console output which matches a given string.
94+
95+
#### Parameters
96+
| Name | Description |
97+
| :- | :- |
98+
| `text` | String to wait and match for |
99+
100+
#### Example Usage
101+
```yaml
102+
wait-serial: 'Ready for testing!'
103+
```
104+
105+
### Write to Serial (`write-serial`)
106+
Write text or an array of numbers to the serial console.
107+
108+
#### Parameters
109+
| Name | Description |
110+
| :- | :- |
111+
| `value` | The string or array of numbers to write to the serial console |
112+
113+
#### Example Usage
114+
<Tabs>
115+
<TabItem value="write-serial-string-example" label="String">
116+
```json
117+
write-serial: 'Ready for testing!'
118+
```
119+
</TabItem>
120+
<TabItem value="write-serial-array-example" label="Array">
121+
```json
122+
write-serial: [87, 111, 107, 119, 105]
123+
```
124+
</TabItem>
125+
</Tabs>
126+
127+
### Take a Screenshot (`take-screenshot`)
128+
Take a screenshot of a specific component and compare it with an existing capture.
129+
130+
| Name | Description |
131+
| :- | :- |
132+
| `part-id` | ID of the target compontent |
133+
| `save-to` | Path to save screenshot to |
134+
| `compare-with` | Path of a screenshot to compare with |
135+
136+
This step requires `part-id` and `save-to` and/or `compare-with`.
137+
138+
Example usage:
139+
```yaml
140+
take-screenshot:
141+
part-id: 'oled1'
142+
compare-with: 'screenshots/oled-1.png'
143+
```
144+
145+
## Running Scenarios
146+
147+
To build the test projects and run the tests, you need to install [PlatformIO Core](https://platformio.org/install/cli)
148+
and the [Wokwi CLI](https://docs.wokwi.com/wokwi-ci/cli-installation), get a [Wokwi CI token](https://wokwi.com/dashboard/ci)
149+
and set the `WOKWI_CLI_TOKEN` environment variable with the token.
150+
151+
You can then use `pio run` to compile the project and `wokwi-cli . --scenario <scenraio_file>.yaml` to run the tests.
152+
You can also use [Wokwi for VS Code](https://docs.wokwi.com/vscode/getting-started) to interactively simulate the test
153+
projects.
154+
155+
### Example Usage
156+
157+
Example parts with test scenarios are available at the [wokwi-part-tests](https://github.com/wokwi/wokwi-part-tests)
158+
GitHub repository. We will try to compile and run tests for the `wokwi-dht22` part on the ESP32.
159+
160+
Begin with cloning the repository:
161+
```bash
162+
git clone https://github.com/wokwi/wokwi-part-tests
163+
```
164+
165+
Navigate to the part in question:
166+
```bash
167+
cd wokwi-dht22/dht22-esp32
168+
```
169+
170+
Build the required microcontroller firmware:
171+
```bash
172+
pio run
173+
```
174+
This can also be done via the PlatformIO VS Code extension - just click the build button.
175+
176+
Finally, run the test!
177+
```bash
178+
wokwi-cli . --scenario dht22.test.yaml
179+
```
180+
181+
If successful, the output of the test looks as follows:
182+
```text
183+
Wokwi CLI v0.18.3 (786fa8e49d9c)
184+
Connected to Wokwi Simulation API 1.0.0-20251028-g60747fe2
185+
Starting simulation...
186+
ets Jul 29 2019 12:21:46
187+
[DHT22 Sensor Test (ESP32)] Expected text matched: "ets Jul 29 2019 12:21:46"
188+
189+
rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
190+
configsip: 0, SPIWP:0xee
191+
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
192+
mode:DIO, clock div:2
193+
load:0x3fff0030,len:1156
194+
load:0x40078000,len:11456
195+
ho 0 tail 12 room 4
196+
load:0x40080400,len:2972
197+
entry 0x400805dc
198+
DHT22 test!
199+
[DHT22 Sensor Test (ESP32)] Expected text matched: "DHT22 test!"
200+
Humidity: 45.80% Temperature: 23.50°C
201+
[DHT22 Sensor Test (ESP32)] Expected text matched: "Humidity: 45.80% Temperature: 23.50°C"
202+
Humidity: 45.80% Temperature: 23.50°C
203+
[DHT22 Sensor Test (ESP32)] Expected text matched: "Humidity: 45.80% Temperature: 23.50°C"
204+
Humidity: 66.90% Temperature: 21.50°C
205+
[DHT22 Sensor Test (ESP32)] Expected text matched: "Humidity: 66.90% Temperature: 21.50°C"
206+
[DHT22 Sensor Test (ESP32)] Scenario completed successfully
207+
```
208+
33209
## Supported Parts with Automation Controls
34210

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

0 commit comments

Comments
 (0)