# Tests and Experiments

This directory contains automated tests, manual diagnostic programs, and standalone experiments. It is separate from `src` so test-only dependencies and exploratory code are not included in production assemblies.

## Directory map

| Directory | Purpose |
| --- | --- |
| `StgSharpDebug` | Executable test harness for manual debugging and stress testing of allocators, matrices, rendering, NGRA, and other subsystems. This is not an automated unit-test suite. |
| `STgSharpTest` | Older MSTest-based tests for the former Script/EXPRESS and related projects. Some references and machine-specific test data are legacy and may require repair before the project can run. |
| `SingleFile` | Standalone source experiments and generated-code samples that are not part of a project or the normal build. |

Run the active debug harness directly when investigating a subsystem:

```powershell
dotnet run --project test/StgSharpDebug/StgSharpDebug.csproj
```

## Archived Text Regex diagnostics

The Text Regex analyzer and source-generator preview are frozen. Their original source files
are retained under [StgSharpDebug/Legacy/TextRegex](StgSharpDebug/Legacy/TextRegex) and excluded
from compilation, packaging, and build/publish copying. `Main` no longer calls them, and
`--regex-preview` is not an active entry point.

The corresponding runtime, text-specific AST/parser, and generator are archived under
[src/Nitload.RegularAnalysis/Legacy](../src/Nitload.RegularAnalysis/Legacy/README.md).
Generic AST and token infrastructure remain active. See the
[NGRA transformation plan](../future/NGRA_Transformation_Plan.md) for the new NFA direction.

## Native builds

Building the debug project still builds its normal project references, including Graphics and
Mathematics, and prepares the native library with CMake. `BuildNativeBeforeManaged` defaults
to true; Debug selects `clang-debug`, and other configurations select `clang-release`.
`RequireNativeLibrary` reports a missing DLL at build time instead of allowing execution to
fail later.

For a managed-only build without a native toolchain or DLL, pass
`-p:BuildNativeBeforeManaged=false -p:RequireNativeLibrary=false`.
This does not make debug routines that use native services runnable without the native library.

New repeatable tests should use a test project and avoid machine-specific paths, external mutable data, and dependencies on previous test execution. Keep one-off investigations in `SingleFile` or the manual debug harness until their expected behavior is stable enough for automation.