# How GoogleTest Test Sharding Works with `--gtest_shard_index` and `--gtest_total_shards`

> Understand GoogleTest test sharding with --gtest_shard_index and --gtest_total_shards. Learn how to distribute tests across processes and machines efficiently. Each test runs exactly once.

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

---

**GoogleTest distributes test execution across multiple processes or machines by partitioning the test list using `--gtest_shard_index` and `--gtest_total_shards`, applying a deterministic modulo algorithm in `ShouldRunTestOnShard` to guarantee each test runs exactly once.**

The `google/googletest` framework provides native support for distributed testing through command-line flags that split a single test binary into disjoint subsets called *shards*. This mechanism allows CI pipelines to parallelize large suites without splitting source code, ensuring deterministic load balancing across workers.

## The Sharding Flags and Entry Points

Sharding is controlled by two integer flags defined in [`googletest/src/gtest.cc`](https://github.com/google/googletest/blob/main/googletest/src/gtest.cc) around lines 411–420:

```cpp
GTEST_DEFINE_int32_(total_shards, -1,
    "Total number of shards. -1 means disabled.");
GTEST_DEFINE_int32_(shard_index, -1,
    "Index of the shard to run. -1 means disabled.");

```

- **`--gtest_total_shards`**: Specifies the total number of shards (must be greater than 1 to enable sharding).
- **`--gtest_shard_index`**: Specifies the zero-based index of the current shard (must be between 0 and `total_shards - 1`).

When both flags are set to valid values, GoogleTest prints a diagnostic note during initialization. The output logic resides near [line 3495](https://github.com/google/googletest/blob/main/googletest/src/gtest.cc#L3495-L3498):

```

Note: This is test shard 2 of 5.

```

If either flag remains at its default value of `-1`, the framework executes the entire test suite normally.

## The Shard Assignment Algorithm

The core logic that decides whether a specific test belongs to the current shard lives in the function `ShouldRunTestOnShard`, implemented in [`googletest/src/gtest.cc`](https://github.com/google/googletest/blob/main/googletest/src/gtest.cc) around line 6283:

```cpp
bool ShouldRunTestOnShard(int total_shards,
                          int shard_index,
                          int test_id) {
  return (test_id % total_shards) == shard_index;
}

```

**Key implementation details:**

- **Test ID assignment**: As the test framework builds the list of runnable tests, it assigns each test a monotonically increasing integer identifier (`test_id`).
- **Modulo partitioning**: The algorithm uses the modulo operator to map each `test_id` to exactly one shard index. This creates a strict partition—no test appears in more than one shard, and every test appears in exactly one shard.
- **Load balancing**: Because `test_id` values are sequential, the distribution is balanced such that the number of tests per shard differs by at most one.

The correctness of this approach is validated by unit tests in [`googletest/test/gtest_unittest.cc`](https://github.com/google/googletest/blob/main/googletest/test/gtest_unittest.cc) around lines 1884–1910. These tests verify that for any valid `total_shards`, the union of all shards covers the full test set with no overlaps.

## Interaction with Test Shuffling

Sharding operates correctly alongside `--gtest_shuffle` (or the `GTEST_SHUFFLE` environment variable), but the order of operations matters:

1. **Shuffle phase**: When enabled, GoogleTest randomizes the test order before assigning `test_id` values.
2. **Shard assignment**: The `ShouldRunTestOnShard` logic runs against the shuffled sequence.

Consequently, enabling shuffling changes which specific tests land on which shard for a given index, but the *partitioning guarantee* remains intact. This design allows teams to combine random ordering with distributed execution to surface order-dependent failures across different shard configurations.

## Practical Usage Examples

To execute a test binary across three parallel workers, run the following commands on separate machines or processes:

```bash

# Worker 0 (first shard)

./my_test --gtest_total_shards=3 --gtest_shard_index=0

# Worker 1 (second shard)

./my_test --gtest_total_shards=3 --gtest_shard_index=1

# Worker 2 (third shard)

./my_test --gtest_total_shards=3 --gtest_shard_index=2

```

Each worker independently executes only the tests whose `test_id % 3` equals the worker's index. To combine with randomization:

```bash
./my_test --gtest_total_shards=3 --gtest_shard_index=0 --gtest_shuffle

```

## Summary

- **Sharding flags**: `--gtest_shard_index` (zero-based) and `--gtest_total_shards` are defined in `googletest/src/gtest.cc` and default to `-1` (disabled).
- **Assignment algorithm**: `ShouldRunTestOnShard` uses `(test_id % total_shards) == shard_index` to create a deterministic, balanced partition.
- **Partition guarantees**: Each test runs on exactly one shard, and the distribution differs by at most one test per shard.
- **Shuffle compatibility**: Sharding occurs after shuffling, preserving partition integrity while allowing randomized execution order across distributed workers.

## Frequently Asked Questions

### What happens if I only set `--gtest_shard_index` without `--gtest_total_shards`?

GoogleTest requires both flags to enable sharding. If you set only `--gtest_shard_index` while `--gtest_total_shards` remains at its default value of `-1`, the framework ignores the shard index and runs the full test suite. Both values must be non-negative, and `total_shards` must be greater than 1 for sharding to activate.

### How does GoogleTest ensure that no test is skipped or executed twice across shards?

The `ShouldRunTestOnShard` function implements a mathematical partition using the modulo operator. For any given `test_id`, the expression `test_id % total_shards` yields exactly one integer between `0` and `total_shards - 1`. The test runs only when this result matches the current `--gtest_shard_index`, guaranteeing mutual exclusivity and complete coverage across all shards.

### Can I use test sharding with `--gtest_filter`?

Yes. GoogleTest applies the filter before sharding. The framework first builds the list of tests matching the filter criteria, assigns sequential `test_id` values to that filtered subset, and then applies the shard logic. This means each shard receives a partition of the *filtered* tests, not the entire binary.

### Why is my shard index zero-based instead of one-based?

GoogleTest follows C++ convention by using zero-based indexing for `shard_index` to align with the modulo arithmetic in `ShouldRunTestOnShard`. Valid indices range from `0` to `total_shards - 1`. Attempting to use a negative index or an index equal to or greater than `total_shards` results in undefined behavior or no tests being selected.