# How to Skip Tests in GoogleTest Using `GTEST_SKIP()` and `IsSkipped()`

> Learn how to skip tests in GoogleTest using GTEST_SKIP() and check skip status with IsSkipped(). Optimize your test suite efficiently.

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

---

**GoogleTest allows runtime test skipping via the `GTEST_SKIP()` macro, which immediately returns from the test body with a special skip status, while `Test::IsSkipped()` queries the underlying `TestResult` to report whether the current test was skipped.**

The `google/googletest` framework provides a clean, exception-free mechanism for aborting test execution when prerequisites are not met. Understanding how `GTEST_SKIP()` interacts with the test runner's state machine helps you write robust conditional tests and custom event listeners that react to skipped scenarios.

## How `GTEST_SKIP()` Works Internally

When your test code invokes `GTEST_SKIP()`, the macro expands to `GTEST_SKIP_("")` as defined in [`googletest/include/gtest/gtest.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/gtest.h) at line 1745. This internal macro resides in [`googletest/include/gtest/internal/gtest-internal.h`](https://github.com/google/googletest/blob/main/googletest/include/gtest/internal/gtest-internal.h) (line 1308) and expands to:

```cpp
GTEST_MESSAGE_(msg, ::testing::TestPartResult::kSkip)

```

This creates a `TestPartResult` object with status `kSkip` and returns it immediately from the current function scope. Because this return statement exits the test body prematurely, any code following the `GTEST_SKIP()` call remains unreachable. The skip result propagates to the current `TestResult` object, setting an internal boolean flag that persists for the remainder of the test case lifecycle.

## Runtime Skip Detection with `IsSkipped()`

The static method `testing::Test::IsSkipped()` provides programmatic access to the skip state. Implemented in `googletest/src/gtest.cc` at line 2802, the method forwards the query to the current test result:

```cpp
bool Test::IsSkipped() {
  return internal::GetUnitTestImpl()->current_test_result()->Skipped();
}

```

The underlying `TestResult::Skipped()` method (defined around line 3010 in the same file) returns the boolean flag set during the earlier `GTEST_SKIP()` invocation. This design allows external observers, such as custom test event listeners or test fixtures, to check whether the active test was skipped without accessing private implementation details.

## Test Execution Flow and Skip Guards

The test runner checks the skip status at a critical junction in `googletest/src/gtest.cc` (line 2746). After `SetUp()` completes but before invoking `TestBody()`, the framework validates:

```cpp
if (!HasFatalFailure() && !IsSkipped()) {
  // Invoke TestBody()
}

```

This guard ensures that skipped tests do not execute their test bodies, even if the skip occurred during `SetUp()`. The check also prevents skipped tests from being reported as failed, maintaining clean separation between skip and failure semantics.

## Practical Usage Examples

### Conditional Skipping with Custom Messages

Use `GTEST_SKIP()` with the streaming operator to provide context when prerequisites are missing:

```cpp
TEST(NetworkTest, RequiresInternet) {
  if (!IsConnectedToInternet()) {
    GTEST_SKIP() << "Skipping test because network is unreachable";
  }
  
  EXPECT_TRUE(DownloadData());
}

```

The test framework reports this case as skipped rather than passed or failed, and the diagnostic message appears in the test output log.

### Querying Skip State from Tests

While calling `IsSkipped()` inside the same test body that triggered the skip is unreachable (due to the immediate return), you can verify the API behavior across test boundaries or from fixture teardown:

```cpp
TEST(SkipDemo, ForceSkip) {
  GTEST_SKIP() << "Intentional skip for demonstration";
  // This line never executes
  EXPECT_FALSE(true);
}

TEST(SkipDemo, VerifyPreviousSkip) {
  // This is a separate test; IsSkipped() refers to THIS test, not the previous one
  // To check if a specific test was skipped, use a custom TestEventListener
  EXPECT_FALSE(testing::Test::IsSkipped());  // Returns false for current test
}

```

For programmatic verification of skip states across tests, implement a `testing::EmptyTestEventListener` and override `OnTestEnd()` to inspect `test_info->result()->Skipped()`.

## Summary

- **`GTEST_SKIP()`** is a macro defined in [`gtest/gtest.h`](https://github.com/google/googletest/blob/main/gtest/gtest.h) that returns a `TestPartResult` with `kSkip` status, immediately exiting the test body.
- **Skip state** is stored in the `TestResult` object associated with the current test and accessed via `TestResult::Skipped()`.
- **`Test::IsSkipped()`** provides a public static interface to query this state, implemented in `src/gtest.cc`.
- The test runner guards `TestBody()` execution with `!IsSkipped()` checks to prevent running tests marked for skipping during `SetUp()`.
- Skip handling uses return-based control flow rather than exceptions, ensuring compatibility with environments where exception handling is disabled.

## Frequently Asked Questions

### What happens to code after calling `GTEST_SKIP()`?

The macro expands to a return statement that exits the test function immediately. Any statements following `GTEST_SKIP()` are unreachable and never execute, similar to an early return statement in C++.

### Can I call `IsSkipped()` inside the same test that calls `GTEST_SKIP()`?

No. Because `GTEST_SKIP()` returns immediately from the test body, any subsequent lines—including calls to `IsSkipped()`—are unreachable during that test execution. Query the skip state from `TearDown()`, global test listeners, or subsequent tests instead.

### How does `GTEST_SKIP()` differ from simply returning early from a test?

Returning early manually marks the test as successful (passed), whereas `GTEST_SKIP()` marks it with a distinct skip status. This distinction appears in test reports and allows build systems to differentiate between passed, failed, and skipped tests for metrics and required-success policies.

### Where is the skip state actually stored?

The boolean flag resides in the `TestResult` class defined in `googletest/src/gtest.cc`. `Test::IsSkipped()` retrieves this by accessing the current test result through `internal::GetUnitTestImpl()->current_test_result()->Skipped()`, as implemented at line 2802 of `gtest.cc`.