# Backend Tests

## Scope

These rules apply to everything under `backend/tests/`.

## Agent Guidance

- When working anywhere under `backend/tests/`, load and use the `tunit-testing` skill as the primary source of testing guidance, patterns, and conventions.
- Use the skill before adding or changing tests, test fixtures, assertions, lifecycle hooks, ASP.NET Core integration tests, or Aspire-based test infrastructure.

## Test Framework

- Use `TUnit` everywhere.
- Use `[Test]` for single-case tests.
- Use TUnit-native data-driven attributes such as `[Arguments(...)]` for parameterized tests.

## Assertions

- Prefer native awaited `Assert.That(...)` assertions for new tests.
- Keep assertions direct and readable.
- Assert the behavior that matters most: output, persisted state, ordering, filtering, and errors.

## Test Design

- Follow `Arrange / Act / Assert`.
- Prefer one clear behavior per test.
- Use descriptive test names in the form `Method_Scenario_ExpectedResult`.
- Keep test setup minimal; extract helpers only when reused.

## Isolation

- Tests must be deterministic and independent.
- Do not rely on execution order.
- For API/data tests, keep per-test isolation through the provided schema/fixture infrastructure.
- Do not share mutable state between tests unless it is explicitly managed by the existing TUnit shared fixture/data source infrastructure.

## Infrastructure

- Reuse existing test infrastructure in `Infrastructure/` before adding new helpers.
- For `Kds.Ai.ApiService.Tests` and `Kds.Ai.Data.Tests`, use the shared PostgreSQL/Testcontainers TUnit fixture pattern already present.
- If a test requires Docker/Testcontainers, make that dependency explicit and keep the test focused.

## TUnit Patterns

- Use `[Before(Test)]` and `[After(Test)]` for per-test setup and cleanup.
- Use `[ClassDataSource<T>(Shared = SharedType.PerTestSession)]` for shared infrastructure such as PostgreSQL containers.
- Keep live tests opt-in by gating them with `Skip.Test(...)` unless `KDSAI_RUN_LIVE_TESTS=1`, then use `Skip.Test(...)` again when required configuration is missing.
- Prefer `CancellationToken` test method parameters for async flows that need cancellation.

## Verification

- Run tests with `dotnet test --project <path-to-test-csproj>`.
- Prefer validating one backend test project at a time.
- After test changes, run the relevant `dotnet test --project ...` command.
- Run live tests when changing the logic they cover or at the end of the task.
- If backend code was changed together with tests, finish with a solution build when possible.
- Do not run `dotnet build` and `dotnet test` at the same time for overlapping backend projects.
- Do not run multiple build/test commands in parallel against the same project outputs because file locks can cause false failures.

## Live Test Execution

- Live tests run only when `KDSAI_RUN_LIVE_TESTS=1`.
- Do not set `KDSAI_RUN_LIVE_TESTS` in CI workflows such as `.github/workflows/build-and-test.yml`.
- PowerShell session example:

```powershell
$env:KDSAI_RUN_LIVE_TESTS="1"
dotnet test --project "backend/tests/Kds.Ai.Data.Tests/Kds.Ai.Data.Tests.csproj"
```

- Single-command PowerShell example:

```powershell
pwsh -NoProfile -Command '$env:KDSAI_RUN_LIVE_TESTS="1"; dotnet test --project "backend/tests/Kds.Ai.Integrations.BrinkPos.Tests/Kds.Ai.Integrations.BrinkPos.Tests.csproj"'
```