Preview CI Behavior Locally

This guide shows how to preview CI behavior locally without running a full pipeline.

Build Stage

The build stage builds project binaries and test binaries. It uses settings from .idf_build_apps.toml; see Build Config File.

We split the build stage into two parts:

Test-related build: builds test binaries to be executed later in the test stage.
Non-test-related build: builds project binaries for compilation checks.

Preview the build stage locally:

idf-ci build run --dry-run

Preview only the test-related build:

idf-ci build run --dry-run --only-test-related

Preview only the non-test-related build:

idf-ci build run --dry-run --only-non-test-related

Test Stage

The test stage runs pytest. Because idf-ci integrates as a pytest plugin, you can preview tests using either idf-ci test collect or standard pytest options. Pytest settings live in pytest.ini; see Test Config File.

Preview test collection with idf-ci:

# Collect all tests
idf-ci test collect

# Collect tests for a specific target
idf-ci test collect -t esp32

# Collect tests matching a marker (e.g. QEMU emulator tests)
idf-ci test collect -m "qemu"

You can also use standard pytest collection options:

pytest --collect-only

Filter by test name with -k:

pytest --collect-only -k test_func_name

Filter by markers with -m:

pytest --collect-only -m "not host_test"

For multi-DUT tests, pass a comma-separated list of targets:

pytest --collect-only --target esp32,esp32s2

Increase log verbosity:

pytest --collect-only --log-cli-level DEBUG

The default log level is WARNING. Python logging levels are DEBUG < INFO < WARNING < ERROR < CRITICAL. Only messages at or above the selected level are shown.