Command-Line Options

This page provides a complete reference for all command-line options supported by pytest-embedded and its service extensions.

You can also inspect these options from your terminal at any time by running:

pytest --help

Core Options

Options in the embedded group configure fundamental framework behaviors, multi-device topologies, and reporting.

Option	Type	Default	Description
--embedded-services	string	""	Comma-separated list of services to activate (e.g. "serial", "esp,idf", "idf,qemu").
--count	integer	1	Number of DUTs required for multi-device test cases. When greater than 1, fixtures become tuples.
--app-path	string	None	Path to the application directory or binary file under test.
--build-dir	string	"build"	Name or relative path of the build directory inside --app-path.
--with-timestamp	bool (y/n)	True	Enable or disable timestamp prefixes on live console log output.
--logfile-extension	string	".log"	File extension format for saved log files.
--metric-path	string	None	File path to save Prometheus/OpenMetrics text benchmarks recorded via log_metric.
--root-logdir	string	temp dir	Base directory where session log files are saved.
--cache-dir	string	temp dir	Base directory for caching test metadata and binary hashes across tests.
--parallel-count	integer	1	Total number of parallel jobs when splitting the test suite in CI.
--parallel-index	integer	1	1-based index of the current parallel CI job.
--check-duplicates	bool (y/n)	False	Verify and reject duplicate test case or test script names.
--prettify-junit-report	bool (y/n)	False	Format and indent JUnit XML reports cleanly.
--unity-test-report-mode	choice	"replace"	Behavior for Unity test cases in the JUnit report: "replace" (default) or "merge".

Serial Options

Options in the embedded-serial group configure physical UART serial connections.

Option	Type	Default	Description
--port	string	None	Path to target serial port (e.g. /dev/ttyUSB0, COM3). Can be set via ESPPORT.
--port-location	string	None	USB device location string (format: <bus>-<port>[-<port>]...) to match dynamic ports.
--baud	integer	115200	Baud rate for serial communication with the target.

Espressif SoC Options

Options in the embedded-esp group configure Espressif-specific target identification and flashing via esptool.

Option	Type	Default	Description
--target	string	"auto"	Target chip family (e.g. esp32, esp32c3, esp32s3). Auto-detected if set to "auto".
--beta-target	string	same as target	Chip type for beta target revisions.
--flash-port	string	None	Dedicated serial port for flashing if different from the monitoring port.
--esptool-baud	integer	921600	Baud rate used when flashing firmware via esptool. Can be set via ESPBAUD.
--port-mac	string	None	MAC address of the target board used to select the correct port among multiple boards.
--port-serial-number	string	None	Comma-separated list of USB serial numbers to filter available COM ports.
--skip-autoflash	bool (y/n)	False	Skip flashing the firmware binary onto the target chip before running the test.
--erase-all	bool (y/n)	False	Completely erase the target flash memory before flashing.
--esp-flash-force	flag	False	Pass force mode flag to esptool during flashing.
--add-target-as-marker-with-amount	bool (y/n)	False	Dynamically attach target chip name and device count as a test marker.

ESP-IDF Options

Options in the embedded-idf group configure ESP-IDF build parsing, partition tables, and panic decoding.

Option	Type	Default	Description
--supported-targets	string	None	Comma-separated list of officially supported target chips for the test suite.
--preview-targets	string	None	Comma-separated list of preview/experimental target chips for the test suite.
--part-tool	string	IDF default	Path to the partition table generator script (gen_esp32part.py).
--confirm-target-elf-sha256	bool (y/n)	False	Verify the SHA256 of the flashed binary against the local ELF before skipping flashing.
--erase-nvs	bool (y/n)	False	Erase NVS partition blocks when flashing the target board.
--skip-check-coredump	bool (y/n)	False	Disable automatic panic trace decoding and flash/UART core dump checking on test failure.

JTAG & OpenOCD Options

Options in the embedded-jtag group configure on-chip debugging with OpenOCD and GDB.

Option	Type	Default	Description
--openocd-prog-path	string	"openocd"	Path to the OpenOCD executable.
--openocd-cli-args	string	"-f board/esp32-wrover-kit-3.3v.cfg"	Command-line arguments passed to OpenOCD.
--gdb-prog-path	string	"xtensa-esp32-elf-gdb"	Path to architecture-specific GDB executable.
--gdb-cli-args	string	"--quiet"	Command-line arguments passed to GDB.
--no-gdb	bool (y/n)	False	Skip creating a GDB instance when only OpenOCD is required.

QEMU Options

Options in the embedded-qemu group configure virtual machine execution under QEMU.

Option	Type	Default	Description
--qemu-image-path	string	"<app_path>/flash_image.bin"	Path to the bootable QEMU flash image.
--qemu-prog-path	string	"qemu-system-xtensa"	Path to the QEMU binary executable.
--qemu-cli-args	string	"-nographic -machine esp32"	Default base arguments for QEMU.
--qemu-extra-args	string	None	Additional CLI arguments appended to the QEMU invocation command.
--qemu-efuse-path	string	None	Path to a virtual eFuse data file.
--skip-regenerate-image	bool (y/n)	False	Skip rebuilding the QEMU flash image if one is already present.
--encrypt	bool (y/n)	False	Enable flash pre-encryption simulation workflow.
--keyfile	string	None	Key file used for the pre-encrypted flash workflow.

esp-emu Options

Options in the embedded-espemu group configure lightweight ESP RISC-V SoC emulation.

Option	Type	Default	Description
--espemu-image-path	string	merged bin path	Path to an existing merged flash binary for esp-emu.
--espemu-prog-path	string	"esp-emu"	Path to the esp-emu executable binary.
--espemu-cli-args	string	None	Base arguments passed to esp-emu.
--espemu-extra-args	string	None	Extra arguments appended to the esp-emu command line.

Arduino Options

Options in the embedded-arduino group configure Arduino sketch testing.

Option	Type	Default	Description
--no-fast-flash	bool (y/n)	False	Disable fast differential flashing (--diff-with) and write the entire flash.

Wokwi Options

Options in the embedded-wokwi group configure Wokwi web/API simulation.

Option	Type	Default	Description
--wokwi-diagram	string	None	Path to a custom Wokwi diagram JSON file.
--wokwi-usb-serial-jtag	bool (y/n)	False	Use USB Serial JTAG interface instead of standard UART in the Wokwi diagram.