# Testing (/docs/guides/testing)

Build and run the C++ harness, select cases and preserve packet layout contracts.

## Run C++ tests [#run-c-tests]

From the repository root:

```bash
cmake -B build -S . -DCHUDCS2_BUILD_TESTS=ON
make -j"$(nproc)" -C build
ctest --test-dir build --output-on-failure
```

`CHUDCS2_BUILD_TESTS` defaults to `OFF`. CMake builds `unit_tests` from the existing harness in `tests/cpp/test_main.cpp` when enabled. The registered cases run without CS2, a display or root access.

List registered cases without running them:

```bash
ctest --test-dir build -N
```

Run only configuration and packet bounds cases:

```bash
ctest --test-dir build --output-on-failure -R 'test_(config_.*|shm_reader_bounds)$'
```

The harness covers distance calculations, ESP limits, packet bounds, flash alpha, hitbox parsing, BVH raycasts, color conversion, configuration, trigger math, proximity beeps, smoke wireframes, hit features, menu search, focus monitoring and offset scanning. AimAssist tests are registered when its implementation is present.

## Add a regression case [#add-a-regression-case]

Tests are opt-in. Add one for non-obvious pure logic, parsing, a data contract or a specific regression. Extend `tests/cpp/test_main.cpp` and register the case with `add_test` in `CMakeLists.txt`. State why the case is needed in the commit message.

Do not add tests that launch the overlay, need CS2, a display, root or network access, assert log strings, or compile source at runtime. Keep the existing C++ harness. Do not introduce a new framework or Python suite.

## Packet alignment [#packet-alignment]

Keep packed definitions and size assertions in `src/overlay/game_reader.hpp` synchronized with the C++ harness. See [Packet layout](/docs/reference/shared-memory).

The current tree has no Python E2E suite or shared-memory simulation fixtures. The `test_shm_reader_bounds` name refers to internal packet bounds.

## Documentation checks [#documentation-checks]

The documentation site has a separate Bun workflow. See [Documentation development](/docs/guides/development#documentation-site) for checks and editor setup.