> For the complete documentation index, see [llms.txt](https://framework.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://framework.aic.io/technical-guidelines-code-standards-and-tech-stack/test-driven-development-and-quality-engineering/unit-test-standards.md).

# Unit Test Standards

## Purpose

Unit tests verify small pieces of behaviour quickly and deterministically.

## AIC Standard

* xUnit is the default test framework for new AIC .NET projects.
* Tests must be deterministic and isolated.
* Tests should run from the command line using `dotnet test`.
* Tests should not depend on external services.
* Unit tests must not use production databases, real message brokers or real customer services.

## Naming

Use behaviour-based names:

```csharp
public sealed class AccessDecisionServiceTests
{
    [Fact]
    public void CanReadCase_WhenUserHasMatchingClearance_ReturnsTrue()
    {
    }
}
```

## Structure

Use Arrange, Act, Assert:

```csharp
[Fact]
public void CalculatePriority_WhenCaseIsUrgent_ReturnsHigh()
{
    var caseRecord = CaseRecordBuilder.New().WithUrgency(Urgency.Urgent).Build();
    var calculator = new CasePriorityCalculator();

    var priority = calculator.Calculate(caseRecord);

    priority.ShouldBe(Priority.High);
}
```

## Test Data Builders

Use builders to make intent clear:

```csharp
var caseRecord = CaseRecordBuilder.New()
    .WithStatus(CaseStatus.Open)
    .WithOwner("user-123")
    .Build();
```

## Mocking Rules

* Mock external dependencies, not value objects.
* Prefer real domain objects.
* Do not over-mock internal implementation.
* Avoid verifying every method call unless behaviour requires it.
* Mock time through `IClock` or `TimeProvider`.

## Unit Test Gate

Unit tests must:

* run quickly
* be included in PR pipeline
* be named clearly
* fail for one understandable reason
* use stable data
* avoid sleeps and timing assumptions