idf-wokwi 1.0.0__tar.gz

idf_wokwi-1.0.0/.editorconfig

@@ -0,0 +1,19 @@
+# EditorConfig helps maintain consistent coding styles between editors & IDEs
+# https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# Keep README & docs within the same column width as code
+[*.{py,toml,yaml,yml,md}]
+max_line_length = 100
+
+# Make makes you use tabs
+[Makefile]
+indent_style = tab

idf_wokwi-1.0.0/.github/workflows/ci.yaml

@@ -0,0 +1,93 @@
+name: CI
+
+on:
+    push:
+    pull_request:
+        branches:
+            - main
+    workflow_dispatch:
+
+env:
+    ESP_IDF_BRANCH: release/v6.0
+    ESP_IDF_TARGET: esp32
+
+jobs:
+    lint:
+        runs-on: ubuntu-24.04
+        steps:
+            - uses: actions/checkout@v6
+            - uses: actions/setup-python@v6
+              with:
+                  python-version: "3.12"
+            - run: pip install hatch
+            - run: hatch run ruff format --check .
+            - run: hatch run ruff check .
+            - run: hatch run mypy .
+
+    test:
+        strategy:
+            fail-fast: false
+            matrix:
+                os: [ubuntu-24.04, windows-latest]
+                python-version: ["3.9", "3.12", "3.13"]
+
+        runs-on: ${{ matrix.os }}
+        steps:
+            - uses: actions/checkout@v6
+            - uses: actions/setup-python@v6
+              with:
+                  python-version: ${{ matrix.python-version }}
+            - run: pip install hatch
+            - run: hatch run dev:pytest tests/test_integration.py::test_action_extensions_structure
+
+    integration:
+        runs-on: ubuntu-24.04
+        steps:
+            - uses: actions/checkout@v6
+            - uses: actions/setup-python@v6
+              with:
+                  python-version: "3.12"
+
+            - uses: actions/cache@v4
+              id: cache-esp-idf
+              with:
+                  path: |
+                      ~/esp-idf
+                      ~/.espressif
+                  key: esp-idf-${{ env.ESP_IDF_BRANCH }}-${{ env.ESP_IDF_TARGET }}
+
+            - name: Install ESP-IDF
+              if: steps.cache-esp-idf.outputs.cache-hit != 'true'
+              run: |
+                  git clone --depth 1 --recursive --shallow-submodules -b $ESP_IDF_BRANCH https://github.com/espressif/esp-idf.git ~/esp-idf
+                  ~/esp-idf/install.sh $ESP_IDF_TARGET
+
+            - uses: actions/cache@v4
+              id: cache-build
+              with:
+                  path: test-project/build
+                  key: test-build-${{ env.ESP_IDF_TARGET }}-${{ hashFiles('test-project/**') }}-${{ env.ESP_IDF_BRANCH }}
+
+            - name: Build test project
+              if: steps.cache-build.outputs.cache-hit != 'true'
+              run: |
+                  . ~/esp-idf/export.sh
+                  cd test-project
+                  idf.py set-target $ESP_IDF_TARGET
+                  idf.py build
+
+            - name: Install idf-wokwi
+              run: |
+                  . ~/esp-idf/export.sh
+                  pip install .
+
+            - uses: wokwi/wokwi-ci-server-action@v1
+
+            - name: Test idf.py wokwi
+              run: |
+                  . ~/esp-idf/export.sh
+                  cd test-project
+                  idf.py wokwi --timeout 10000 --expect-text "Hello world!" 2>&1 | tee output.log
+                  grep -q "Expected text found: Hello world!" output.log
+              env:
+                  WOKWI_CLI_TOKEN: ${{ secrets.WOKWI_CLI_TOKEN }}

idf_wokwi-1.0.0/.github/workflows/release.yaml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+    push:
+        tags:
+            - "v*.*.*"
+
+permissions:
+    id-token: write # OIDC token for trusted publishing
+    contents: write # For the release action
+
+jobs:
+    build-and-publish:
+        runs-on: ubuntu-24.04
+        environment: pypi
+        steps:
+            - uses: actions/checkout@v6
+
+            - uses: actions/setup-python@v6
+              with:
+                  python-version: "3.12"
+
+            - name: Build wheel & sdist
+              run: |
+                  pip install --quiet hatch
+                  hatch build
+
+            - name: Publish to PyPI
+              uses: pypa/gh-action-pypi-publish@release/v1
+              with:
+                  verbose: true
+
+            - uses: softprops/action-gh-release@v2
+              with:
+                  generate_release_notes: true
+                  files: |
+                      dist/*.whl
+                      dist/*.tar.gz

idf_wokwi-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+sdkconfig
+sdkconfig.old

idf_wokwi-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+    # Ruff: formatter + linter
+    - repo: https://github.com/astral-sh/ruff-pre-commit
+      rev: v0.12.0
+      hooks:
+          - id: ruff-format
+          - id: ruff
+            args: [--fix]
+
+    # mypy (strict)
+    - repo: https://github.com/pre-commit/mirrors-mypy
+      rev: v1.16.1
+      hooks:
+          - id: mypy
+
+    # Basic hygiene hooks (official, maintained)
+    - repo: https://github.com/pre-commit/pre-commit-hooks
+      rev: v5.0.0
+      hooks:
+          - id: end-of-file-fixer
+          - id: trailing-whitespace
+
+default_language_version:
+    python: python3.12

idf_wokwi-1.0.0/.ruff.toml

@@ -0,0 +1,23 @@
+# https://docs.astral.sh/ruff/configuration/
+target-version = "py39"
+line-length = 100
+src = ["src", "tests"]
+
+# Enable rule bundles
+lint.select = [
+    "E",  # pycodestyle errors
+    "F",  # pyflakes
+    "I",  # isort
+    "UP", # pyupgrade
+    "PL", # pylint-worthwhile subset
+]
+
+lint.ignore = [
+    "E501",    # handled by formatter
+    "PLC0415", # lazy imports for platform-specific modules are fine
+    "PLR0913", # callback signature dictated by idf.py extension API
+]
+
+# Per-folder overrides --------------------------------------------------------
+[lint.per-file-ignores]
+"tests/**/*.py" = ["PLR2004"] # magic-numbers okay in tests

idf_wokwi-1.0.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0 - 2026-02-10
+
+Initial release.

idf_wokwi-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+## Setup
+
+```bash
+pip install hatch
+```
+
+## Development
+
+Lint and type-check:
+
+```bash
+hatch run ruff format --check .
+hatch run ruff check .
+hatch run mypy .
+```
+
+Run tests:
+
+```bash
+hatch run dev:pytest
+```
+
+## Pre-commit hooks
+
+```bash
+pip install pre-commit
+pre-commit install
+```

idf_wokwi-1.0.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: idf-wokwi
+Version: 1.0.0
+Summary: Wokwi simulation extension for ESP-IDF (idf.py wokwi)
+Project-URL: Source, https://github.com/wokwi/idf-wokwi
+Project-URL: Issues, https://github.com/wokwi/idf-wokwi/issues
+Author-email: Uri Shaked <uri@wokwi.com>
+License-Expression: Apache-2.0
+Keywords: esp-idf,esp32,idf.py,simulation,wokwi
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Emulators
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: wokwi-client>=0.1.0
+Description-Content-Type: text/markdown
+
+# idf-wokwi
+
+Wokwi simulation extension for ESP-IDF. Adds `idf.py wokwi` command.
+
+## Installation
+
+```bash
+pip install idf-wokwi
+```
+
+## Usage
+
+Set `WOKWI_CLI_TOKEN` to your [Wokwi API token](https://wokwi.com/dashboard/ci?utm_source=idf-wokwi).
+
+```bash
+export WOKWI_CLI_TOKEN="your-token-here"
+
+# Build and simulate
+idf.py build
+idf.py wokwi
+
+# CI mode: exit when expected text appears
+idf.py wokwi --timeout 10000 --expect-text "Hello world!"
+```
+
+## Options
+
+| Option           | Description                                                    |
+| ---------------- | -------------------------------------------------------------- |
+| `--diagram-file` | Path to `diagram.json` (defaults to project root)              |
+| `--timeout`      | Simulation timeout in milliseconds (exit code 42 on timeout)   |
+| `--expect-text`  | Exit successfully when this text appears in serial output      |
+| `--fail-text`    | Exit with error when this text appears in serial output        |
+| `--expect-regex` | Exit successfully when this regex matches a serial output line |
+| `--fail-regex`   | Exit with error when this regex matches a serial output line   |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).

idf_wokwi-1.0.0/README.md

@@ -0,0 +1,39 @@
+# idf-wokwi
+
+Wokwi simulation extension for ESP-IDF. Adds `idf.py wokwi` command.
+
+## Installation
+
+```bash
+pip install idf-wokwi
+```
+
+## Usage
+
+Set `WOKWI_CLI_TOKEN` to your [Wokwi API token](https://wokwi.com/dashboard/ci?utm_source=idf-wokwi).
+
+```bash
+export WOKWI_CLI_TOKEN="your-token-here"
+
+# Build and simulate
+idf.py build
+idf.py wokwi
+
+# CI mode: exit when expected text appears
+idf.py wokwi --timeout 10000 --expect-text "Hello world!"
+```
+
+## Options
+
+| Option           | Description                                                    |
+| ---------------- | -------------------------------------------------------------- |
+| `--diagram-file` | Path to `diagram.json` (defaults to project root)              |
+| `--timeout`      | Simulation timeout in milliseconds (exit code 42 on timeout)   |
+| `--expect-text`  | Exit successfully when this text appears in serial output      |
+| `--fail-text`    | Exit with error when this text appears in serial output        |
+| `--expect-regex` | Exit successfully when this regex matches a serial output line |
+| `--fail-regex`   | Exit with error when this regex matches a serial output line   |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).

idf_wokwi-1.0.0/mypy.ini

@@ -0,0 +1,14 @@
+[mypy]
+python_version = 3.9
+strict = True
+show_error_codes = True
+pretty = True
+warn_unused_ignores = True
+warn_return_any = True
+warn_unreachable = True
+
+[mypy-wokwi_client.*]
+ignore_missing_imports = True
+
+[mypy-pytest.*]
+ignore_missing_imports = True

idf_wokwi-1.0.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "idf-wokwi"
+version = "1.0.0"
+description = "Wokwi simulation extension for ESP-IDF (idf.py wokwi)"
+readme = "README.md"
+authors = [{ name = "Uri Shaked", email = "uri@wokwi.com" }]
+license = "Apache-2.0"
+keywords = ["wokwi", "esp-idf", "simulation", "esp32", "idf.py"]
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Embedded Systems",
+    "Topic :: System :: Emulators",
+    "Typing :: Typed",
+]
+dependencies = ["wokwi-client>=0.1.0"]
+
+[project.urls]
+Source = "https://github.com/wokwi/idf-wokwi"
+Issues = "https://github.com/wokwi/idf-wokwi/issues"
+
+[project.entry-points.idf_extension]
+wokwi = "idf_wokwi.wokwi_ext:action_extensions"
+
+[tool.hatch.envs.default]
+dependencies = ["ruff>=0.12.0", "mypy>=1.16.1"]
+
+[tool.hatch.envs.dev]
+template = "default"
+extra-dependencies = ["pytest"]
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers"

idf_wokwi-1.0.0/src/idf_wokwi/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026, CodeMagic LTD

idf_wokwi-1.0.0/src/idf_wokwi/_log.py

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026, CodeMagic LTD
+
+from __future__ import annotations
+
+import sys
+
+
+def red_print(msg: str) -> None:
+    print(f"\033[31m{msg}\033[0m", file=sys.stderr)
+
+
+def yellow_print(msg: str) -> None:
+    print(f"\033[33m{msg}\033[0m", file=sys.stderr)

idf_wokwi-1.0.0/src/idf_wokwi/diagram.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026, CodeMagic LTD
+
+"""Diagram generation and discovery for Wokwi simulations."""
+
+from __future__ import annotations
+
+import json
+import os
+
+from ._log import red_print
+
+TARGET_WOKWI_PARTS: dict[str, str] = {
+    "esp32": "board-esp32-devkit-c-v4",
+    "esp32s2": "board-esp32-s2-devkitm-1",
+    "esp32s3": "board-esp32-s3-devkitc-1",
+    "esp32c3": "board-esp32-c3-devkitm-1",
+    "esp32c5": "board-esp32-c5-devkitc-1",
+    "esp32c6": "board-esp32-c6-devkitc-1",
+    "esp32h2": "board-esp32-h2-devkitm-1",
+    "esp32p4": "board-esp32-p4-function-ev",
+}
+
+
+def generate_diagram(target: str) -> str:
+    """Return a minimal diagram.json string for the given target."""
+    part_type = TARGET_WOKWI_PARTS.get(target, f"board-{target}-devkit")
+    diagram = {
+        "version": 1,
+        "author": "idf-wokwi",
+        "editor": "wokwi",
+        "parts": [{"type": part_type, "id": "esp"}],
+        "connections": [
+            ["esp:TX", "$serialMonitor:RX", "", []],
+            ["esp:RX", "$serialMonitor:TX", "", []],
+        ],
+        "serialMonitor": {"display": "terminal"},
+    }
+    return json.dumps(diagram)
+
+
+def find_diagram(project_path: str, diagram_file: str) -> str:
+    """Locate diagram.json - returns path or empty string if auto-generation needed."""
+    if diagram_file:
+        if not os.path.isabs(diagram_file):
+            diagram_file = os.path.join(project_path, diagram_file)
+        if not os.path.exists(diagram_file):
+            red_print(f"Diagram file not found: {diagram_file}")
+            raise SystemExit(1)
+        return diagram_file
+
+    default = os.path.join(project_path, "diagram.json")
+    if os.path.exists(default):
+        return default
+
+    return ""

idf_wokwi-1.0.0/src/idf_wokwi/expect_engine.py

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026, CodeMagic LTD
+
+"""Line-based serial text/regex matcher"""
+
+from __future__ import annotations
+
+import re
+import threading
+import time
+
+from ._log import red_print, yellow_print
+
+TIMEOUT_EXIT_CODE = 42
+
+_MAX_LINE_LENGTH = 10_000
+
+
+class ExpectEngine:
+    """Buffer chars until newline, then test the complete line against patterns."""
+
+    def __init__(
+        self,
+        expect_text: str = "",
+        fail_text: str = "",
+        expect_regex: str = "",
+        fail_regex: str = "",
+    ) -> None:
+        self.expect_text = expect_text
+        self.fail_text = fail_text
+        self._expect_re = re.compile(expect_regex) if expect_regex else None
+        self._fail_re = re.compile(fail_regex) if fail_regex else None
+        self.match_event = threading.Event()
+        self.fail_event = threading.Event()
+        self.active = bool(expect_text or fail_text or self._expect_re or self._fail_re)
+        self._current_line: list[str] = []
+
+    def _test_line(self, line: str) -> None:
+        if self.expect_text and self.expect_text in line:
+            self.match_event.set()
+        if self._expect_re and self._expect_re.search(line):
+            self.match_event.set()
+        if self.fail_text and self.fail_text in line:
+            self.fail_event.set()
+        if self._fail_re and self._fail_re.search(line):
+            self.fail_event.set()
+
+    def feed(self, data: bytes) -> None:
+        """Feed raw serial bytes - prints to stdout and tests for pattern matches."""
+        text = data.decode("utf-8", errors="replace")
+        print(text, end="", flush=True)
+
+        if not self.active:
+            return
+
+        for ch in text:
+            if ch == "\n":
+                self._test_line("".join(self._current_line))
+                self._current_line.clear()
+            elif len(self._current_line) < _MAX_LINE_LENGTH:
+                self._current_line.append(ch)
+
+    def wait(self, timeout_ms: int) -> None:
+        """Block until a match/fail is found or timeout elapses. Raises SystemExit."""
+        deadline = time.monotonic() + timeout_ms / 1000.0 if timeout_ms else float("inf")
+
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                red_print(f"Timeout after {timeout_ms} ms")
+                raise SystemExit(TIMEOUT_EXIT_CODE)
+
+            if self.fail_event.is_set():
+                msg = self.fail_text or str(self._fail_re and self._fail_re.pattern)
+                red_print(f"Fail text detected: {msg}")
+                raise SystemExit(1)
+
+            if self.match_event.is_set():
+                msg = self.expect_text or str(self._expect_re and self._expect_re.pattern)
+                yellow_print(f"Expected text found: {msg}")
+                return
+
+            time.sleep(min(remaining, 0.1))

idf_wokwi-1.0.0/src/idf_wokwi/interactive.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026, CodeMagic LTD
+
+"""Interactive mode - forward stdin to simulation, platform-aware."""
+
+from __future__ import annotations
+
+import sys
+
+from wokwi_client import WokwiClientSync
+
+from ._log import yellow_print
+
+if sys.platform == "win32":
+    import msvcrt
+
+    def _platform_loop(client: WokwiClientSync) -> None:
+        try:
+            while True:
+                ch = msvcrt.getch()
+                if ch == b"\x1d":  # Ctrl+]
+                    break
+                client.serial_write(ch)
+        except OSError:
+            pass
+
+else:
+    import os
+    import termios
+    import tty
+
+    def _platform_loop(client: WokwiClientSync) -> None:
+        stdin_fd = sys.stdin.fileno()
+        old_settings = termios.tcgetattr(stdin_fd)
+        try:
+            tty.setcbreak(stdin_fd)
+            while True:
+                ch = os.read(stdin_fd, 1)
+                if ch == b"\x1d":  # Ctrl+]
+                    break
+                client.serial_write(ch)
+        except OSError:
+            pass
+        finally:
+            termios.tcsetattr(stdin_fd, termios.TCSADRAIN, old_settings)
+
+
+def interactive_loop(client: WokwiClientSync) -> None:
+    yellow_print("Press Ctrl+] to stop the simulation")
+    _platform_loop(client)

idf_wokwi-1.0.0/src/idf_wokwi/wokwi_ext.py

@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026, CodeMagic LTD
+
+"""
+ESP-IDF extension that adds ``idf.py wokwi`` for running Wokwi simulations.
+
+Install once with ``pip install idf-wokwi`` and the command is available in
+every ESP-IDF project.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from wokwi_client import GET_TOKEN_URL, WokwiClientSync
+
+from ._log import red_print, yellow_print
+from .diagram import find_diagram, generate_diagram
+from .expect_engine import TIMEOUT_EXIT_CODE, ExpectEngine
+from .interactive import interactive_loop
+
+__all__ = ["TIMEOUT_EXIT_CODE", "action_extensions", "wokwi_callback"]
+
+
+def _get_project_desc(build_dir: str) -> dict[str, Any]:
+    desc_path = os.path.join(build_dir, "project_description.json")
+    if not os.path.exists(desc_path):
+        red_print(f"Project description not found: {desc_path}")
+        red_print("Please build the project first with: idf.py build")
+        raise SystemExit(1)
+    with open(desc_path, encoding="utf-8") as f:
+        project_desc: dict[str, Any] = json.load(f)
+    return project_desc
+
+
+def _upload_artifacts(
+    client: WokwiClientSync,
+    project_desc: dict[str, Any],
+    build_dir: str,
+    diagram_path: str,
+    flasher_args_path: str,
+    elf_path: str,
+) -> tuple[str, str]:
+    """Upload diagram, firmware, and ELF to the simulator. Returns (firmware_name, elf_name)."""
+    if diagram_path:
+        client.upload_file("diagram.json", Path(diagram_path))
+        yellow_print(f"Uploaded diagram: {diagram_path}")
+    else:
+        target: str = project_desc.get("target", "esp32")
+        diagram_content = generate_diagram(target)
+        client.upload("diagram.json", diagram_content.encode("utf-8"))
+        yellow_print(f"Generated diagram for target: {target}")
+
+    firmware_name: str = client.upload_file("flasher_args.json", Path(flasher_args_path))
+    yellow_print("Uploaded firmware")
+
+    elf_name = ""
+    if elf_path and os.path.exists(elf_path):
+        elf_name = client.upload_file(os.path.basename(elf_path), Path(elf_path))
+        yellow_print(f"Uploaded ELF: {os.path.basename(elf_path)}")
+
+    return firmware_name, elf_name
+
+
+def wokwi_callback(
+    action: str,
+    ctx: Any,
+    args: Any,
+    diagram_file: str,
+    timeout: int,
+    expect_text: str,
+    fail_text: str,
+    expect_regex: str,
+    fail_regex: str,
+) -> None:
+    token = os.environ.get("WOKWI_CLI_TOKEN", "")
+    if not token:
+        red_print("WOKWI_CLI_TOKEN environment variable is not set.")
+        red_print(f"Get your token at: {GET_TOKEN_URL}")
+        raise SystemExit(1)
+
+    build_dir: str = args.build_dir
+    project_desc = _get_project_desc(build_dir)
+    project_path: str = project_desc.get("project_path", os.getcwd())
+
+    flasher_args_path = os.path.join(build_dir, "flasher_args.json")
+    if not os.path.exists(flasher_args_path):
+        red_print(f"flasher_args.json not found in {build_dir}")
+        red_print("Please build the project first with: idf.py build")
+        raise SystemExit(1)
+
+    elf_path = project_desc.get("app_elf", "")
+    if elf_path and not os.path.isabs(elf_path):
+        elf_path = os.path.join(build_dir, elf_path)
+
+    diagram_path = find_diagram(project_path, diagram_file)
+
+    server = os.environ.get("WOKWI_CLI_SERVER")
+    client = WokwiClientSync(token, server=server)
+
+    try:
+        hello = client.connect()
+        yellow_print(f"Connected to Wokwi Simulator (server {hello.get('version', '?')})")
+
+        firmware_name, elf_name = _upload_artifacts(
+            client, project_desc, build_dir, diagram_path, flasher_args_path, elf_path
+        )
+
+        engine = ExpectEngine(expect_text, fail_text, expect_regex, fail_regex)
+        client.serial_monitor(engine.feed)
+
+        client.start_simulation(firmware=firmware_name, elf=elf_name or None)
+        yellow_print("Simulation started")
+
+        if engine.active or timeout:
+            engine.wait(timeout)
+        else:
+            interactive_loop(client)
+
+    finally:
+        try:
+            client.disconnect()
+        except Exception:
+            pass
+
+
+def action_extensions(base_actions: dict[str, Any], project_path: str) -> dict[str, Any]:
+    return {
+        "version": "1",
+        "actions": {
+            "wokwi": {
+                "callback": wokwi_callback,
+                "help": "Run Wokwi simulation.",
+                "dependencies": ["all"],
+                "options": [
+                    {
+                        "names": ["--diagram-file"],
+                        "help": (
+                            "Path to diagram.json file. "
+                            "If not specified, looks for diagram.json in the project root."
+                        ),
+                        "is_flag": False,
+                        "default": "",
+                    },
+                    {
+                        "names": ["--timeout"],
+                        "help": (
+                            "Simulation timeout in milliseconds. "
+                            "Exits with code 42 on timeout. 0 means no timeout."
+                        ),
+                        "is_flag": False,
+                        "default": 0,
+                        "type": int,
+                    },
+                    {
+                        "names": ["--expect-text"],
+                        "help": "Exit successfully when this text appears in serial output.",
+                        "is_flag": False,
+                        "default": "",
+                    },
+                    {
+                        "names": ["--fail-text"],
+                        "help": "Exit with error when this text appears in serial output.",
+                        "is_flag": False,
+                        "default": "",
+                    },
+                    {
+                        "names": ["--expect-regex"],
+                        "help": "Exit successfully when this regex matches a serial output line.",
+                        "is_flag": False,
+                        "default": "",
+                    },
+                    {
+                        "names": ["--fail-regex"],
+                        "help": "Exit with error when this regex matches a serial output line.",
+                        "is_flag": False,
+                        "default": "",
+                    },
+                ],
+            }
+        },
+    }

idf_wokwi-1.0.0/test-project/CMakeLists.txt

@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 3.16)
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(hello_world)

idf_wokwi-1.0.0/test-project/main/CMakeLists.txt

@@ -0,0 +1 @@
+idf_component_register(SRCS "main.c" INCLUDE_DIRS ".")

idf_wokwi-1.0.0/test-project/main/main.c

@@ -0,0 +1,13 @@
+#include <stdio.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+void app_main(void)
+{
+    printf("Hello world!\n");
+    for (int i = 10; i >= 0; i--) {
+        printf("Restarting in %d seconds...\n", i);
+        vTaskDelay(1000 / portTICK_PERIOD_MS);
+    }
+    esp_restart();
+}

idf_wokwi-1.0.0/tests/test_integration.py

@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026, CodeMagic LTD
+
+from __future__ import annotations
+
+import os
+import threading
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+
+from idf_wokwi.wokwi_ext import TIMEOUT_EXIT_CODE, action_extensions, wokwi_callback
+
+
+def _hello_world_build_dir() -> str:
+    """Return path to a pre-built hello_world build directory.
+
+    Set BUILD_DIR env var to override.
+    """
+    explicit = os.environ.get("BUILD_DIR")
+    if explicit:
+        assert os.path.isfile(os.path.join(explicit, "flasher_args.json")), (
+            f"BUILD_DIR={explicit} does not contain flasher_args.json"
+        )
+        return explicit
+
+    idf_path = os.environ.get("IDF_PATH", "/workspace/esp-idf")
+    candidates = [
+        os.path.join(idf_path, "examples", "get-started", "hello_world", "build"),
+    ]
+    for c in candidates:
+        if os.path.isfile(os.path.join(c, "flasher_args.json")):
+            return c
+    pytest.fail("No hello_world build directory with flasher_args.json found")
+    raise AssertionError  # unreachable, helps mypy
+
+
+def test_action_extensions_structure() -> None:
+    result = action_extensions({}, "/tmp")
+    assert result["version"] == "1"
+    assert "wokwi" in result["actions"]
+    assert callable(result["actions"]["wokwi"]["callback"])
+    assert result["actions"]["wokwi"]["dependencies"] == ["all"]
+
+
+class TestWokwiIntegration:
+    """Integration tests that connect to a real Wokwi CI server."""
+
+    def _make_args(self, build_dir: str) -> Any:
+        mock = MagicMock()
+        mock.build_dir = build_dir
+        return mock
+
+    def _run_callback_in_thread(
+        self,
+        build_dir: str,
+        *,
+        timeout: int = 10000,
+        expect_text: str = "",
+        fail_text: str = "",
+        expect_regex: str = "",
+        fail_regex: str = "",
+        diagram_file: str = "",
+    ) -> int:
+        """Run wokwi_callback in a thread and return the exit code (0=success)."""
+        exit_code = 0
+
+        def _target() -> None:
+            nonlocal exit_code
+            try:
+                wokwi_callback(
+                    action="wokwi",
+                    ctx=None,
+                    args=self._make_args(build_dir),
+                    diagram_file=diagram_file,
+                    timeout=timeout,
+                    expect_text=expect_text,
+                    fail_text=fail_text,
+                    expect_regex=expect_regex,
+                    fail_regex=fail_regex,
+                )
+            except SystemExit as e:
+                exit_code = e.code if isinstance(e.code, int) else 1
+
+        t = threading.Thread(target=_target)
+        t.start()
+        t.join(timeout=30)
+        if t.is_alive():
+            exit_code = -1
+        return exit_code
+
+    def test_expect_text_hello_world(self) -> None:
+        """Simulation should find 'Hello world' in serial output."""
+        build_dir = _hello_world_build_dir()
+        code = self._run_callback_in_thread(build_dir, timeout=15000, expect_text="Hello world")
+        assert code == 0
+
+    def test_timeout_returns_42(self) -> None:
+        """A very short timeout should exit with code 42."""
+        build_dir = _hello_world_build_dir()
+        code = self._run_callback_in_thread(
+            build_dir, timeout=1, expect_text="this_text_will_never_appear"
+        )
+        assert code == TIMEOUT_EXIT_CODE
+
+    def test_fail_text(self) -> None:
+        """fail-text should cause exit code 1."""
+        build_dir = _hello_world_build_dir()
+        # "rst:0x1" appears early in ESP32 boot output
+        code = self._run_callback_in_thread(build_dir, timeout=15000, fail_text="rst:0x1")
+        assert code == 1
+
+    def test_expect_regex(self) -> None:
+        """expect-regex should match serial output with a pattern."""
+        build_dir = _hello_world_build_dir()
+        code = self._run_callback_in_thread(build_dir, timeout=15000, expect_regex=r"Hello\s+world")
+        assert code == 0
+
+    def test_fail_regex(self) -> None:
+        """fail-regex should cause exit code 1 on pattern match."""
+        build_dir = _hello_world_build_dir()
+        code = self._run_callback_in_thread(build_dir, timeout=15000, fail_regex=r"rst:0x[0-9a-f]+")
+        assert code == 1