# How to Skip Tests in GoogleTest: A Complete Guide to GTEST_SKIP()

> Learn how to skip tests in GoogleTest using GTEST_SKIP(). Effortlessly halt test execution, mark tests as skipped, and maintain successful test runs.

- Repository: [Google/googletest](https://github.com/google/googletest)
- Tags: how-to-guide
- Published: 2026-08-31

---

**Use the `GTEST_SKIP()` macro in your test code to immediately halt execution and mark the current test as skipped, which prevents it from being recorded as a failure while keeping the overall test run successful.**

GoogleTest provides a robust runtime skipping mechanism that allows developers to conditionally bypass tests when prerequisites aren't met. Whether you're dealing with missing hardware dependencies, unavailable external services, or platform-specific constraints, the library offers precise control over test execution flow. This guide examines the implementation details and practical patterns for effectively skipping tests in the `google/googletest` framework.

## Understanding the GTEST_SKIP() Macro

The skipping functionality centers on the `GTEST_SKIP()` macro, which expands to `GTEST_SKIP_("")` and is defined in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h) at lines 42-46. When invoked, this macro throws a special internal exception that aborts the current test function immediately—no subsequent code in the test body executes.

According to the GoogleTest source code, the skipped status is tracked via `UnitTest::skipped_test_count()`, implemented in `googletest/src/gtest.cc` at lines 1164-1166. This counter feeds into the final test report without affecting the success status of the overall test run.

## Where to Use GTEST_SKIP()

You can invoke the macro from multiple contexts within the GoogleTest framework.

### Inside Individual Test Bodies

The most common pattern involves checking runtime conditions at the start of a test. If a required resource is unavailable, call `GTEST_SKIP()` with an explanatory message stream:

```cpp
TEST(HardwareTest, SpecialDevice) {
  if (!std::filesystem::exists("/dev/special_device")) {
    GTEST_SKIP() << "Device not present on this platform";
  }
  // Test code only runs if device exists
  EXPECT_TRUE(InitializeDevice());
}

```

### In Test Fixture SetUp() and TearDown()

For fixture-based tests, placing the skip logic in `SetUp()` effectively skips all tests in that fixture when conditions fail. This pattern appears in `googletest/test/gtest_skip_test.cc` at lines 38-45:

```cpp
class DatabaseTest : public ::testing::Test {
 protected:
  void SetUp() override {
    if (!DatabaseAvailable()) {
      GTEST_SKIP() << "Database service is down";
    }
  }
};

TEST_F(DatabaseTest, InsertRow) {
  // Automatically skipped if SetUp() called GTEST_SKIP()
  EXPECT_TRUE(db.Insert(key, value));
}

```

### In Suite-Level SetUpTestSuite()

To skip an entire test suite before any individual tests run, override `SetUpTestSuite()` in your fixture class. This approach checks global conditions once rather than repeating checks per test:

```cpp
class PlatformSpecificTest : public ::testing::Test {
 public:
  static void SetUpTestSuite() {
    if (!RunningOnSupportedOS()) {
      GTEST_SKIP() << "Unsupported OS for this suite";
    }
  }
};

TEST_F(PlatformSpecificTest, FeatureA) { /* ... */ }
TEST_F(PlatformSpecificTest, FeatureB) { /* ... */ }

```

## How Skipped Tests Are Reported

GoogleTest distinguishes skipped tests from both passes and failures in all output formats. The `googletest/src/gtest.cc` implementation handles skipped test serialization differently depending on the output target.

For XML reports generated via `--gtest_output=xml`, skipped tests appear as `<skipped>` elements, as implemented around line 4280 in `gtest.cc`. When using JSON output, the same source file at line 4735 writes these entries as `"skipped"` status values.

The console output displays skipped tests distinctly, and the `skipped_test_count()` method provides programmatic access to the total number of skipped tests during a run. This allows CI/CD systems to track infrastructure issues separately from actual test failures.

## Summary

- **GTEST_SKIP()** is the primary macro for runtime test skipping, defined in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h)
- The macro immediately terminates test execution and marks the test as skipped rather than passed or failed
- Use it in test bodies, `SetUp()`, `TearDown()`, or `SetUpTestSuite()` to control skip granularity
- Skipped tests are tracked via `UnitTest::skipped_test_count()` in `googletest/src/gtest.cc`
- Output formats include `<skipped>` XML tags and `"skipped"` JSON entries as implemented in `gtest.cc` lines 4280 and 4735
- The overall test run remains successful unless actual test failures occur

## Frequently Asked Questions

### What is the difference between GTEST_SKIP() and returning early from a test?

Returning early with a `return` statement causes the test to be recorded as **passed**, which can mask missing test coverage. `GTEST_SKIP()` explicitly marks the test as skipped in the report, alerting you to unexecuted code paths while maintaining a successful test run status. This distinction is critical for accurate test metrics and CI/CD monitoring.

### Can I skip tests at compile time instead of runtime?

GoogleTest does not provide a built-in compile-time skip mechanism equivalent to `#ifdef` preprocessing. However, you can achieve similar results by conditionally compiling test definitions using preprocessor directives. Runtime skipping via `GTEST_SKIP()` is preferred when the skip condition depends on dynamic factors like environment variables, network availability, or hardware presence.

### How do skipped tests affect the overall test run result?

Skipped tests do not cause the test suite to fail. According to the implementation in `googletest/src/gtest.cc`, the skip counter is separate from the failure counter in the `UnitTest` class. The test process exits with code 0 (success) as long as no actual test failures occur, regardless of how many tests were skipped. This makes skipping ideal for handling optional or platform-specific functionality.

### Can I provide a custom message when skipping a test?

Yes, the `GTEST_SKIP()` macro supports the streaming operator `<<` to attach descriptive messages. These messages appear in the test output alongside the skip status, making it easier to diagnose why specific tests were bypassed. For example: `GTEST_SKIP() << "Requires CUDA device, none detected";` provides clear context in both console and XML reports.