# Testing

> Engine-owned documentation. This page maps the current engine test executable, generated test targets, coverage targets, and every `Source/Tests/Test_*.cpp` suite currently present in the checkout.

## Purpose

Use this page when choosing validation for an engine change or when adding/removing tests. The source-tree README at [../Source/Tests/README.md](../Source/Tests/README.md) is a short entry point; this page is the maintained full test map.

## Source paths inspected

- `Source/Applications/TestingApp.cpp`
- `Source/Tests/README.md`
- all current `Source/Tests/Test_*.cpp` files
- `BuildTools/cmake/stages/EngineSources.cmake`
- `BuildTools/cmake/stages/Applications.cmake`
- `BuildTools/cmake/stages/Init.cmake`
- `BuildTools/codecoverage.py`
- `BuildTools/validate.sh`
- `BuildTools/validate.cmd`
- parent VS Code task references where available

## Test runner model

`Source/Applications/TestingApp.cpp` is the test application entry point. It requires `FO_TESTING_APP`, initializes the application layer with `InitApp(-1, nullptr)`, marks `IsTestingInProgress`, and delegates execution to `Catch::Session().run(argc, argv)`.

`BuildTools/cmake/stages/EngineSources.cmake` owns `FO_TESTS_SOURCE`, the explicit list of test source files compiled into test builds. `BuildTools/cmake/stages/Applications.cmake` builds test executables through `SetupTestBuild(name)`:

- `UnitTests` when `FO_UNIT_TESTS` is enabled;
- `CodeCoverage` when `FO_CODE_COVERAGE` is enabled.

For an embedding project with dev name `LF`, the standard generated names are `LF_UnitTests`, `RunUnitTests`, `LF_CodeCoverage`, `RunCodeCoverage`, `GenerateCodeCoverageReport`, and `AnalyzeCodeCoverage`. Treat the prefix as project-generated, not universal.

## Running tests

Preferred local baseline from a configured build:

```bash
cmake --build . --config RelWithDebInfo --target RunUnitTests
```

The executable target can also be invoked directly when you need Catch2 arguments. In Last Frontier-style layouts, test binaries are emitted under `Binaries/Tests-*`, for example `Binaries/Tests-Windows-win64/LF_UnitTests.exe` or `Binaries/Tests-Linux-x64/LF_UnitTests`.

For broad validation scenarios, the BuildTools validators can run selected scenarios:

```bash
Engine/BuildTools/validate.sh unit-tests
Engine/BuildTools/validate.sh android-arm64-client linux-client linux-server
```

Use the smallest focused tests first, then the broader run target when the change crosses subsystem boundaries.

## Code coverage

When `FO_CODE_COVERAGE` is enabled, `BuildTools/cmake/stages/Init.cmake` selects the backend from the compiler:

- MSVC / clang-cl: MSVC-style coverage output;
- Clang: LLVM profile/coverage mapping;
- GCC: GCC/lcov-style coverage flags.

`BuildTools/cmake/stages/Applications.cmake` wires coverage command targets through `BuildTools/codecoverage.py`:

- `CleanCodeCoverageData`
- `RunCodeCoverage`
- `GenerateCodeCoverageReport`
- `AnalyzeCodeCoverage`

Coverage output is rooted under `CodeCoverage/<Toolchain>/<Platform-Config>/`; see [../Source/Tests/README.md](../Source/Tests/README.md) for current local task notes.

## Current test inventory

Current count: **79** `Test_*.cpp` suites.

### Essentials and low-level utilities

- `Source/Tests/Test_BaseLogging.cpp`
- `Source/Tests/Test_BasicCore.cpp`
- `Source/Tests/Test_CommonHelpers.cpp`
- `Source/Tests/Test_Compressor.cpp`
- `Source/Tests/Test_Containers.cpp`
- `Source/Tests/Test_DataSerialization.cpp`
- `Source/Tests/Test_DiskFileSystem.cpp`
- `Source/Tests/Test_ExceptionHandling.cpp`
- `Source/Tests/Test_ExtendedTypes.cpp`
- `Source/Tests/Test_GenericUtils.cpp`
- `Source/Tests/Test_GlobalData.cpp`
- `Source/Tests/Test_HashedString.cpp`
- `Source/Tests/Test_Logging.cpp`
- `Source/Tests/Test_MemorySystem.cpp`
- `Source/Tests/Test_NetSockets.cpp`
- `Source/Tests/Test_Platform.cpp`
- `Source/Tests/Test_SafeArithmetics.cpp`
- `Source/Tests/Test_SmartPointers.cpp`
- `Source/Tests/Test_StackTrace.cpp`
- `Source/Tests/Test_StringUtils.cpp`
- `Source/Tests/Test_StrongType.cpp`
- `Source/Tests/Test_TimeRelated.cpp`
- `Source/Tests/Test_WorkThread.cpp`

### Configuration, data sources, files, and caches

- `Source/Tests/Test_CacheStorage.cpp`
- `Source/Tests/Test_ConfigFile.cpp`
- `Source/Tests/Test_DataSource.cpp`
- `Source/Tests/Test_FileSystem.cpp`
- `Source/Tests/Test_Settings.cpp`

### Common runtime model

- `Source/Tests/Test_AnyData.cpp`
- `Source/Tests/Test_Common.cpp`
- `Source/Tests/Test_EngineMetadata.cpp`
- `Source/Tests/Test_EntityLifecycle.cpp`
- `Source/Tests/Test_EntityProtos.cpp`
- `Source/Tests/Test_Geometry.cpp`
- `Source/Tests/Test_LineTracer.cpp`
- `Source/Tests/Test_MapLoader.cpp`
- `Source/Tests/Test_Movement.cpp`
- `Source/Tests/Test_PathFinding.cpp`
- `Source/Tests/Test_Properties.cpp`
- `Source/Tests/Test_ProtoManager.cpp`
- `Source/Tests/Test_TextPack.cpp`
- `Source/Tests/Test_Timer.cpp`
- `Source/Tests/Test_TwoDimensionalGrid.cpp`

### Networking and server/client integration

- `Source/Tests/Test_ClientDataValidation.cpp`
- `Source/Tests/Test_ClientEngine.cpp`
- `Source/Tests/Test_ClientRuntimeApi.cpp`
- `Source/Tests/Test_ClientServerIntegration.cpp`
- `Source/Tests/Test_DataBase.cpp`
- `Source/Tests/Test_FogOfWar.cpp`
- `Source/Tests/Test_LocationAndEntityMgmt.cpp`
- `Source/Tests/Test_NetBuffer.cpp`
- `Source/Tests/Test_NetworkClient.cpp`
- `Source/Tests/Test_NetworkServer.cpp`
- `Source/Tests/Test_NetworkUdp.cpp`
- `Source/Tests/Test_ServerAdvancedOps.cpp`
- `Source/Tests/Test_ServerEngine.cpp`
- `Source/Tests/Test_ServerItems.cpp`
- `Source/Tests/Test_ServerMapOperations.cpp`

### Scripting and script-visible APIs

- `Source/Tests/Test_AngelScriptAttributes.cpp`
- `Source/Tests/Test_AngelScriptBytecode.cpp`
- `Source/Tests/Test_CommonScriptMethods.cpp`
- `Source/Tests/Test_ScriptBuiltins.cpp`
- `Source/Tests/Test_ScriptEntityOps.cpp`
- `Source/Tests/Test_ServerScriptMethods.cpp`

### Bakers and tools

- `Source/Tests/Test_AngelScriptBaker.cpp`
- `Source/Tests/Test_BakerSetup.cpp`
- `Source/Tests/Test_ConfigBaker.cpp`
- `Source/Tests/Test_EffectBaker.cpp`
- `Source/Tests/Test_ImageBaker.cpp`
- `Source/Tests/Test_MapBaker.cpp`
- `Source/Tests/Test_MetadataBaker.cpp`
- `Source/Tests/Test_ModelBaker.cpp`
- `Source/Tests/Test_ProtoBaker.cpp`
- `Source/Tests/Test_ProtoTextBaker.cpp`
- `Source/Tests/Test_RawCopyBaker.cpp`
- `Source/Tests/Test_TextBaker.cpp`
- `Source/Tests/Test_TextureAtlas.cpp`

### Rendering/frontend smoke tests

- `Source/Tests/Test_Rendering.cpp`

## Validation routing by change type

- Essentials utilities: start with [Essentials.md](Essentials.md) and the essentials tests listed above.
- Config, file lookup, caches, resource packs: [ConfigurationAndDataSources.md](ConfigurationAndDataSources.md), parser/filesystem/cache tests, and affected bake/runtime consumers.
- BuildTools/CMake/generation: [BuildToolsPipeline.md](BuildToolsPipeline.md), [GeneratedApiAndMetadata.md](GeneratedApiAndMetadata.md), codegen/property/metadata tests, and at least one generated target.
- Bakers/resources: [BakingPipeline.md](BakingPipeline.md) and the matching baker tests.
- Runtime entity/map/persistence/networking: [EntityModel.md](EntityModel.md), [MapsMovementGeometry.md](MapsMovementGeometry.md), [Persistence.md](Persistence.md), [Networking.md](Networking.md), and the focused runtime tests.
- Client/frontend/server: [ClientRuntime.md](ClientRuntime.md), [FrontendAndRendering.md](FrontendAndRendering.md), [ServerRuntime.md](ServerRuntime.md), and the matching integration/smoke tests.
- Scripting: [Scripting.md](Scripting.md), [ScriptMethodsMap.md](ScriptMethodsMap.md), [Nullability.md](Nullability.md), and the script/baker/method tests.

## Adding or removing tests

1. Add the new `Source/Tests/Test_*.cpp` file with deterministic Catch2 tests.
2. Add it to `FO_TESTS_SOURCE` in `BuildTools/cmake/stages/EngineSources.cmake`.
3. Update this page and [../Source/Tests/README.md](../Source/Tests/README.md) so the inventory stays complete.
4. Run the focused test binary and, when practical, `RunUnitTests`.
5. If coverage behavior changed, verify the relevant coverage target.

## Validation checklist

1. Every current `Source/Tests/Test_*.cpp` file should appear in this page.
2. No deleted/nonexistent test file should be listed.
3. Target names should be described as generated from `FO_DEV_NAME`, not hard-coded as universal engine names.
4. If `TestingApp.cpp`, `FO_TESTS_SOURCE`, or coverage target wiring changes, update this page in the same change.