GoogleTest (gtest) test reporting

gtest-tesults is a header-only Google Test event listener that depends on the Tesults C++ library. Both can be added via CMake FetchContent.

CMake FetchContent (recommended)

Add the following to your CMakeLists.txt:

include(FetchContent)

FetchContent_Declare(
  tesults
  GIT_REPOSITORY https://github.com/tesults/cpp.git
  GIT_TAG        main
  GIT_SHALLOW    TRUE
)
FetchContent_MakeAvailable(tesults)

FetchContent_Declare(
  gtest_tesults
  GIT_REPOSITORY https://github.com/tesults/gtest-tesults.git
  GIT_TAG        main
  GIT_SHALLOW    TRUE
)
FetchContent_MakeAvailable(gtest_tesults)

target_link_libraries(your_tests PRIVATE
  tesults
  gtest_tesults
  GTest::gtest
)

Manual copy

Alternatively, copy the single header file gtest_tesults.h directly from the GitHub repository into your project. Ensure that both the Tesults C++ library and GoogleTest headers are on your include path.

System dependencies

The Tesults C++ library requires libcurl and OpenSSL. macOS (Homebrew):

brew install curl openssl

Linux (apt):

apt install libcurl4-openssl-dev libssl-dev

gtest-tesults automatically registers its listener at startup — no changes to your test code or main() are required. Just set the TESULTS_TARGET environment variable and run your tests as usual.

Environment variable (recommended)

Set TESULTS_TARGET to your Tesults target token before running your tests:

TESULTS_TARGET=token ./your_tests

The test suite name is taken from the first argument to TEST or TEST_F and the test case name from the second.

TEST(CalculatorTest, Addition) {
  EXPECT_EQ(2 + 2, 4);
}

TEST(CalculatorTest, Subtraction) {
  EXPECT_EQ(10 - 3, 7);
}

CalculatorTest is reported as the suite and Addition / Subtraction as the test case names.

Config file (optional)

Instead of putting the token directly in TESULTS_TARGET you can use a key name and point to a config file. This keeps tokens out of scripts and CI environment definitions.

# Tesults target tokens
target1=eyJ0eXAiOiJ...
web-qa=eyJ0eXAiOiK...
ios-staging=eyJ0eXAiOiL...

TESULTS_TARGET=target1 TESULTS_CONFIG=tesults.cfg ./your_tests

Command-line args (alternative)

If you prefer to pass the token as a command-line argument rather than an environment variable, you can provide a custom main(). Call config_from_args before testing::InitGoogleTest so GoogleTest does not see the unknown --tesults-* flags:

#include <gtest/gtest.h>
#include <gtest_tesults/gtest_tesults.h>

int main(int argc, char* argv[]) {
  auto cfg = gtest_tesults::config_from_args(argc, argv);
  testing::InitGoogleTest(&argc, argv);
  if (!cfg.target.empty()) {
    testing::UnitTest::GetInstance()->listeners().Append(
      new gtest_tesults::TesultsListener(cfg)
    );
  }
  return RUN_ALL_TESTS();
}

./your_tests --tesults-target=token

A config file can also be used with the key method:

./your_tests --tesults-target=target1 --tesults-config=tesults.cfg

When using a custom main(), pass the token via --tesults-target rather than the TESULTS_TARGET env var to avoid registering the listener twice.

Call these functions from inside any TEST or TEST_F body to attach additional data to the test case. No arguments or state object is needed — gtest-tesults identifies the current test automatically.

file

Attach a file to the current test case. Call multiple times to attach more than one file.

gtest_tesults::file("/path/to/log.txt");

description

Set a description for the current test case.

gtest_tesults::description("Verifies that addition returns the correct sum");

custom

Add a custom field and value to the current test case.

gtest_tesults::custom("environment", "staging");

step

Add a step to the current test case. Steps are reported in order.

gtest_tesults::step({"setup", "pass", "Initialise connection", ""})
gtest_tesults::step({"request", "pass", "Send HTTP request", ""})
gtest_tesults::step({"assert", "fail", "Check response code", "Expected 200 got 404"})

A Step has four fields in order: name, result ("pass", "fail", or "unknown"), desc, and reason.

Complete example

TEST(PaymentTest, SuccessfulCharge) {
  gtest_tesults::description("Verifies a valid card is charged successfully");
  gtest_tesults::custom("environment", "staging");
  gtest_tesults::step({"setup", "pass", "Create payment intent", ""})

  // run the test ...
  EXPECT_EQ(charge_result, "success");

  gtest_tesults::file("/tmp/charge-response.json");
}

--tesults-filesOptional

Provide the top-level directory where files generated during testing are saved. Files including logs, screenshots, and other artifacts will be automatically uploaded to Tesults.

TESULTS_TARGET=token TESULTS_FILES=/path/to/files ./your_tests

Or with command-line args if using a custom main():

./your_tests --tesults-target=token --tesults-files=/path/to/files

Files must be saved within a specific directory structure during the test run:

files-path/
  SuiteName/
    TestName/
      file.log
      screenshot.png

For build files the suite is always [build]:

files-path/
  [build]/
    BuildName/
      build.log

Caution: If uploading files the time taken to upload is entirely dependent on your network speed. Typical office upload speeds of 100 - 1000 Mbps should allow upload of even hundreds of files quite quickly, just a few seconds, but if you have slower access it may take hours. We recommend uploading a reasonable number of files for each test case. When starting out test without files first to ensure everything is setup correctly.

• temporary folder
• Test Suite A
• Test 1
• test.log
• screenshot.png
• Test 2
• test.log
• screenshot.png
• Test Suite B
• Test 3
• metrics.csv
• error.log
• Test 4
• test.log

--tesults-build-nameOptional

Use this to report a build version or name for reporting purposes.

--tesults-build-name=1.0.0

--tesults-build-resultOptional

Use this to report the build result, must be one of [pass, fail, unknown].

--tesults-build-result=pass

--tesults-build-descriptionOptional

Use this to report a build description for reporting purposes.

--tesults-build-description=added new feature

--tesults-build-reasonOptional

Use this to report a build failure reason.

--tesults-build-reason=build error line 201 somefile.cpp

Result interpretation is not currently supported by this integration. If you are interested in support please contact help@tesults.com.