test_framework = googletest

Native Tests:


Embedded Tests:

Yes* (only for Espressif 8266 and Espressif 32)

Mocking Support:


GoogleTest is a testing framework developed by the Testing Technology team with Google’s specific requirements and constraints in mind. Whether you work on Linux, Windows, or a Mac, if you write C++ code, GoogleTest can help you.

Getting Started

To get started with the GoogleTest all you need is to set the test_framework option in your “platformio.ini” (Project Configuration File) to the googletest and implement your own main() function:


test_framework = googletest

platform = native

platform = espressif32
framework = arduino
test_framework = googletest


#include <gtest/gtest.h>
// uncomment line below if you plan to use GMock
// #include <gmock/gmock.h>

// TEST(...)
// TEST_F(...)

#if defined(ARDUINO)
#include <Arduino.h>

void setup()
    // should be the same value as for the `test_speed` option in "platformio.ini"
    // default value is test_speed=115200

    // if you plan to use GMock, replace the line above with
    // ::testing::InitGoogleMock();

void loop()
  // Run tests
  if (RUN_ALL_TESTS())

  // sleep for 1 sec

int main(int argc, char **argv)
    ::testing::InitGoogleTest(&argc, argv);
    // if you plan to use GMock, replace the line above with
    // ::testing::InitGoogleMock(&argc, argv);

    if (RUN_ALL_TESTS())

    // Always return zero-code and allow PlatformIO to parse results
    return 0;

Now, you can run tests using the pio test command. If you need a full output from the GoogleTest, please use pio test --verbose option.


Please check the complete GoogleTest example using GTest, GMock, and PlatformIO.

Useful links

  • GoogleTest Primer - Teaches you how to write simple tests using GoogleTest. Read this first if you are new to GoogleTest

  • GoogleTest Advanced - Read this when you’ve finished the Primer and want to utilize GoogleTest to its full potential

  • GoogleTest Samples - Describes some GoogleTest samples

  • GoogleTest FAQ - Have a question? Want some tips? Check here first

  • Mocking for Dummies - Teaches you how to create mock objects and use them in tests

  • Mocking Cookbook - Includes tips and approaches to common mocking use cases

  • Mocking Cheat Sheet - A handy reference for matchers, actions, invariants, and more

  • Mocking FAQ - Contains answers to some mocking-specific questions.


The GoogleTest can be configured using system environment variables. See supported GoogleTest environment variables.

GoogleTest CLI

The GoogleTest works quite nicely without any command-line options at all - but for more control a few of them are available. See GoogleTest CLI guide.

There are two options for how to pass extra arguments to the testing program:

  1. Using PlatformIO Core CLI and pio test --program-arg option

  2. Overriding test_testing_command with a custom command.


Let’s run everything in a test suite FooTest except FooTest.Bar.

Stop executing test cases after the first error and include successful assertions in the output. We will use the --gtest_filter GoogleTest’s CLI option.

  1. Using CLI and pio test --program-arg option:

    > pio test --program-arg "--gtest_filter=FooTest.*-FooTest.Bar"
    # or short format
    > pio test -a "--gtest_filter=FooTest.*-FooTest.Bar"
  2. Overriding test_testing_command with custom command.

    platform = native
    test_testing_command =

Test Runner

If you would like to change the default PlatformIO’s Test Runner for the GoogleTest, please implement your Custom Testing Framework runner extending GooglestTestRunner class. See Custom Testing Framework for examples.