# 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
```

## NGRA generation preview

`StgSharpDebug/TestRegexGenerate.cs` contains a standalone debugging routine that calls the
existing NGRA emitter without Roslyn attribute binding. Select it from the debug `Main`:

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

This branch returns before `World` or native-memory initialization. Without the switch, the
existing debug flow is unchanged. You can also call `TestRegexGenerate.Run()` directly from
`Main` while debugging; pass a pattern to `Run("abc")` for a single preview.
The switch only selects runtime behavior; 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 the default runtime path to fail later.

For managed-only preview work without a native toolchain or DLL, add
`-p:BuildNativeBeforeManaged=false -p:RequireNativeLibrary=false` before `--` in the run command.

Enter raw regular expressions without C# string delimiters. The routine prints only the emitted
code, without status headers or file output. Exceptions propagate directly to the caller/debugger.
Use `:exit` or end-of-input to leave the loop. Empty input is an empty regex. For one-shot mode:

```powershell
dotnet run --project test/StgSharpDebug/StgSharpDebug.csproj -- --regex-preview 'a{2,3}'
```

Set breakpoints in `TestRegexGenerate.cs` or any existing `Generate*` method. The output is a
method-body fragment; this routine does not compile or execute it.

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.