Custom Test Runner

Setting the test_framework option to the custom will instruct PlatformIO to look for a file located in the current (running) test folder. If the file is not found, PlatformIO will check the parent folders in a tree until reaches the test_dir.

If you plan to use a custom test framework for ALL tests, please put the file at the root of test_dir. Otherwise, use Test Hierarchy and put it to the test folder or to the group of tests that depend on it.

The is a Python-based script. It must contain the CustomTestRunner class. See a base example of

from platformio.public import TestRunnerBase

class CustomTestRunner(TestRunnerBase):

In case you want to override the functionality of the existing testing framework, you have to inherit its class. For example, let’s override a “testing” stage for the Unity:

from platformio.public import TestCase, TestCaseSource, TestStatus, UnityTestRunner

class CustomTestRunner(UnityTestRunner):
    def stage_testing(self):
        # 1. Gather test results from Serial, HTTP, Socket, or other sources
        # 2. Report test results (add cases)

        # Exmaple: Report succeed result with duration (optional)
            TestCase(name="test_connectivity", status=TestStatus.PASSED, duration=1.34)

        # Example: Report failed result with source file
                message="Expected 32 Was 33",
                stdout="test/test_desktop/test_calculator.cpp:43:test_calculator_division:FAIL: Expected 32 Was 33",
                    file="test/test_desktop/test_calculator.cpp", line=43

See more custom test runner Examples.