Repository Docs & Knowledge Base

Consolidated Spensara documentation repository (722 Markdown & architecture documents in ../repository)

Built Word Documents (.docx): Spensara Overview (.docx) Capability Assessment (.docx) Brink POS Ingestion Analysis (.docx) The Borg Ingestion Architecture (.docx)

Agent Tooling (71)

Automation workflows, orchestration references, and developer tooling guides.

agent-tooling/backend/tests/AGENTS.md 3,387 bytes · Updated Oct 23, 2026 10:44 AM EDT

Raw File

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: