HOWTO.md

How-to Guides

Contents

• Add to a Test Binary
• Write Assertions
• Run Setup and Cleanup Hooks
• Skip a Test
• Mark a Test as Expected to Fail
• Set a Per-test Timeout
• Isolate a Test in a Separate Process
• Run Every Test in a Separate Process
• Filter Tests
• Suppress Test Output
• Disable Color Output
• Use a Per-test Temporary Directory
• Generate a GTest XML Report

Add to a Test Binary

Add include to the compiler include path and include mytest.h.

#define MYTEST_CONFIG_USE_MAIN
#include <mytest.h>

TEST(Smoke, Runs) {
  ASSERT(true);
}

MYTEST_CONFIG_USE_MAIN creates a main() that calls RUN_ALL_TESTS(argc, argv). For a custom main():

#include <mytest.h>

int main(int argc, char* argv[]) {
  return RUN_ALL_TESTS(argc, argv);
}

Write Assertions

Use ASSERT_* to stop the test on failure. Use EXPECT_* to keep running and report more than one failure.

TEST(Assertions, Values) {
  ASSERT_EQ(4, 2 + 2);
  EXPECT_NE(5, 2 + 2);
  ASSERT(true);
  EXPECT(true);
}

Run Setup and Cleanup Hooks

Hooks are registered per group. The group is the first argument to TEST.

static int counter = 0;

TEST_BEFORE(Counter) {
  counter = 0;
}

TEST_BEFORE_EACH(Counter) {
  ++counter;
}

TEST(Counter, First) {
  ASSERT_EQ(counter, 1);
}

TEST_AFTER_EACH(Counter) {
  ASSERT(counter > 0);
}

TEST_AFTER(Counter) {
  counter = 0;
}

Use TEST_AFTER_ALL(group) for final cleanup or verification after all TEST_ISOLATE tests in the group finish. TEST_AFTER(group) runs after each isolated test, not once at the end.

Skip a Test

Call TEST_SKIP() or TEST_SKIP("reason").

TEST(Feature, DisabledCase) {
  TEST_SKIP("waiting for dependency");
  ASSERT(false);
}

By default, execution stops at the skip point. The -f CLI option keeps running.

Mark a Test as Expected to Fail

Call TEST_EXPECT_FAILURE() before the expected failure.

TEST(Parser, RejectsInvalidInput) {
  TEST_EXPECT_FAILURE();
  ASSERT_EQ(Parse("bad input"), true);
}

Failure becomes success. Success becomes failure.

Set a Per-test Timeout

Pass a timeout in milliseconds as the optional third argument.

TEST(Network, TimesOut, 1000) {
  TEST_EXPECT_FAILURE();
  std::this_thread::sleep_for(std::chrono::seconds(2));
}

The default is 60000 ms. Override it for one run with the -t CLI option.

Isolate a Test in a Separate Process

Use TEST_ISOLATE for tests that may crash or mutate process-global state.

static int global_counter = 0;

TEST_ISOLATE(Process, MutatesGlobal) {
  global_counter = 100;
  ASSERT_EQ(global_counter, 100);
}

TEST(Process, ParentStillClean) {
  ASSERT_EQ(global_counter, 0);
}

Output is forwarded in real time. Crashes are reported by signal.

Run Every Test in a Separate Process

Use the -j CLI option to run selected tests separately, one process each:

./test.x -j

Use files, sockets, or shared memory when these isolated tests need shared state.

Filter Tests

Use the -p PATTERN CLI option to include tests whose full name matches a regular expression. Test names have the form Group:Name.

./test.x -p "^Parser:"
./test.x -p "^Parser:RejectsInvalidInput$"

Use the -p -PATTERN CLI option to exclude matches:

./test.x -p "-Slow"

Exclusions take precedence.

Suppress Test Output

Use the -s CLI option to hide stdout and stderr from test bodies.

./test.x -s

For scoped suppression:

TEST(Output, HideNoisySection) {
  printf("visible\n");
  {
    MyTest::SilenceScope silence;
    printf("hidden\n");
  }
  printf("visible again\n");
}

Disable Color Output

Use the -c CLI option when comparing output in snapshots or logs:

./test.x -c

Use a Per-test Temporary Directory

Call TEST_TEMP_PATH() to get a directory for the current test.

TEST(Files, WritesTemporaryData) {
  auto path = TEST_TEMP_PATH() / "data.txt";
  std::ofstream(path) << "hello";
  ASSERT(std::filesystem::exists(path));
}

Repeated calls in the same test return the same path. The directory is removed after the test, including isolated tests, timeouts, and crashes.

Generate a GTest XML Report

Include mytest-report.h, register a reporter, and run with the -r CLI option.

#include <mytest.h>
#include <mytest-report.h>

int main(int argc, char* argv[]) {
  SET_REPORTER(mytest::GTestXmlReporter);
  return RUN_ALL_TESTS(argc, argv);
}

./test.x -r

./test.x -r report.xml

The default path is test_report.xml.