pio-test

Run automated tests within PlatformIO projects

TLDR

Run all tests in all environments of the current PlatformIO project

$ pio test

Test only specific environments

$ pio test --environment [environment1] --environment [environment2]

Run only tests whose name matches a specific glob pattern

$ pio test --filter "[pattern]"

Ignore tests whose name matches a specific glob pattern

$ pio test --ignore "[pattern]"

Specify a port for firmware uploading

$ pio test --upload-port [upload_port]

Specify a custom configuration file for running the tests

$ pio test --project-conf [path/to/platformio.ini]

-e, --environment
    Test specified environments defined in `platformio.ini`. Multiple environments can be specified.

-t, --test
    Run only specified tests within the specified environment.

--test-filter
    Filter tests by pattern (e.g., `--test-filter *unit*`)

-d, --project-dir

    Specify a custom project directory.

--upload-port
    Manually override an upload port.

--test-port
    Manually override a test port.

--without-uploading
    Do not upload firmware before testing.

--no-reset
    Do not reset target board before testing.

--monitor-rts
    Set initial RTS line state for monitor during the test.

--monitor-dtr
    Set initial DTR line state for monitor during the test.

--verbose
    Increase verbosity for detailed logging.

--color
    Force colored output.

--list-tests
    List available tests for specified environments.

DESCRIPTION

The `pio test` command in PlatformIO is used to execute tests within a PlatformIO project. It facilitates the automated testing of your embedded projects, ensuring code quality and functionality. This command allows you to specify different testing environments defined in your `platformio.ini` configuration file. It supports various frameworks and integrates seamlessly with the PlatformIO ecosystem. The test results are displayed in the terminal, showing pass/fail status, execution time, and any error messages. This allows for rapid feedback during development, enabling developers to identify and fix issues quickly. By leveraging `pio test`, you can establish a robust continuous integration (CI) workflow for your PlatformIO projects.

CAVEATS

Requires a correctly configured `platformio.ini` with defined test environments and test files. The test framework needs to be properly installed and configured for the target platform.

TEST ENVIRONMENT CONFIGURATION

Test environments are defined within the `[env:...]` sections in your `platformio.ini` file, but with a `test_framework` directive. Example:
`[env:native]
platform = native
test_framework = googletest`

TEST FILE STRUCTURE

Test files are typically located in a `test/` directory at the root of the PlatformIO project. The structure will depend on the testing framework being used (e.g., `test/test_main.cpp` for a simple C++ test). Refer to your test framework documentation for the required test file structure.