# How to Run GoogleTest Tests in Parallel: Sharding and Parallel Execution Guide

> Learn how to run GoogleTest tests in parallel using sharding and external tools. Speed up your C++ testing by executing tests concurrently. Get the guide now.

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

---

**GoogleTest executes tests sequentially within a single process, but supports parallel execution through built-in test sharding controlled by environment variables or via the external `gtest-parallel` tool.**

The google/googletest repository provides a deterministic sharding mechanism that distributes test cases across multiple processes without duplication. While the framework does not internally spawn threads for parallel test execution, its **sharding** protocol allows you to partition test suites across workers, significantly reducing total execution time in CI/CD pipelines.

## Understanding GoogleTest's Built-in Sharding Mechanism

The core sharding logic resides in `googletest/src/gtest.cc`, where the framework evaluates environment variables during initialization. According to the google/googletest source code, the sharding system uses two critical environment variables:

- **`GTEST_TOTAL_SHARDS`**: Specifies the total number of shards (parallel workers) participating in the test run. All processes must use the same value.
- **`GTEST_SHARD_INDEX`**: Defines the zero-based index of the current shard, ranging from `0` to `GTEST_TOTAL_SHARDS - 1`.

When these variables are set, the `TestInfo` class calculates a deterministic hash for each test case. If `TestInfo::is_in_another_shard()` returns `true`, the test is skipped entirely in the current process. This ensures every test executes exactly once across the entire shard set.

### Environment Variable Configuration

The sharding implementation reads these variables during `InitGoogleTest()` in `googletest/src/gtest.cc`. The framework parses `kTestTotalShards` and `kTestShardIndex` constants internally, converting their string values to integers before filtering the test list.

## Manual Parallel Execution Using Environment Variables

You can manually launch multiple processes to achieve parallel execution without additional tools. Each process runs the same test binary but only executes tests assigned to its specific shard index.

```bash

# Run a test binary across 4 parallel shards

export GTEST_TOTAL_SHARDS=4

# Launch each shard index in the background

for i in {0..3}; do
  GTEST_SHARD_INDEX=$i ./my_test_binary --gtest_output="xml:shard_$i.xml" &
done

# Wait for all parallel processes to complete

wait

```

**Important**: Each shard writes separate output files that require merging for unified reporting.

## Automated Parallelization with gtest-parallel

For local development or complex CI workflows, the **gtest-parallel** Python script automates the process of listing tests, partitioning them, and launching worker processes. This tool is maintained separately and provides better load balancing than manual sharding.

```bash

# Install gtest-parallel from the official repository

pip install git+https://github.com/google/gtest-parallel.git

# Execute tests using 8 parallel workers

gtest-parallel -j 8 ./my_test_binary

```

The script automatically sets the sharding environment variables and aggregates individual test results into a single summary.

## Programmatic Shard Detection

Test code can query whether it belongs to the current shard using the internal API documented in [`docs/reference/testing.md`](https://github.com/google/googletest/blob/main/docs/reference/testing.md).

```cpp
#include "gtest/gtest.h"

TEST(MySuite, ShardAwareTest) {
  if (testing::Test::IsInAnotherShard()) {
    GTEST_SKIP() << "Test belongs to a different shard.";
  }
  // Test implementation
}

```

This pattern is rarely necessary for standard usage but useful when tests require expensive setup that should only occur on the assigned shard.

## Summary

- **Sharding** is the primary mechanism for parallel test execution in GoogleTest, implemented in `googletest/src/gtest.cc`.
- Set **`GTEST_TOTAL_SHARDS`** and **`GTEST_SHARD_INDEX`** environment variables to partition tests across processes.
- The **`TestInfo::is_in_another_shard()`** method determines test eligibility based on deterministic hashing.
- Use **`gtest-parallel`** for automated parallel execution without manual environment configuration.
- Manual sharding requires merging output files from each shard for comprehensive reporting.

## Frequently Asked Questions

### Does GoogleTest support multi-threading within a single test process?

No, GoogleTest does not execute individual test cases concurrently within a single process. The framework is designed for single-threaded execution, and parallelization must occur at the process level through sharding or external tools like `gtest-parallel`. Attempting to run tests in multiple threads without proper synchronization can lead to race conditions in the test infrastructure.

### How does GoogleTest determine which tests belong to which shard?

The framework calculates a hash based on the test name and maps it to a shard index using the formula `hash(test_name) % GTEST_TOTAL_SHARDS == GTEST_SHARD_INDEX`. This logic is contained in the `ShouldRunTestOnShard()` function within `googletest/src/gtest.cc`, ensuring deterministic distribution across identical binary invocations.

### Can I combine sharding with gtest-parallel for distributed testing?

Yes, `gtest-parallel` uses the same sharding environment variables internally. When you specify the `-j` flag, the script launches multiple processes and sets appropriate `GTEST_SHARD_INDEX` values for each worker. For distributed testing across different machines, you must manually set the environment variables to ensure each physical node runs a distinct subset of tests.

### Where is the sharding logic implemented in the GoogleTest source code?

The sharding implementation is located in `googletest/src/gtest.cc`, specifically in functions parsing `kTestTotalShards` and `kTestShardIndex` environment variables. The API documentation for shard-aware test checking resides in [`docs/reference/testing.md`](https://github.com/google/googletest/blob/main/docs/reference/testing.md), while user-facing documentation explaining the sharding protocol is available in [`docs/advanced.md`](https://github.com/google/googletest/blob/main/docs/advanced.md) at the repository root.