> 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/tdd-operating-model.md).

# TDD Operating Model

## Purpose

AIC uses test-driven development as a design and quality practice.

TDD is not mandatory for every line of code, but test-first thinking is expected for business rules, complex logic, bug fixes and security-sensitive code.

## Red Green Refactor

### Red

Write a failing test that describes the required behaviour.

### Green

Write the simplest production code that passes the test.

### Refactor

Improve the design while keeping tests green.

## When TDD Is Mandatory

TDD or test-first delivery is expected for:

* domain rules
* validation logic
* pricing or calculation logic
* access decisions
* workflow state transitions
* defect fixes
* security-sensitive decisions
* complex mapping
* parsing
* integration adapters with known edge cases

## Test Naming

Use behaviour-focused names:

```csharp
[Fact]
public void AssignTo_WhenUserIsNotVetted_ReturnsInvalidResult()
{
    // Arrange

    // Act

    // Assert
}
```

## Arrange Act Assert

Tests should be structured clearly:

```csharp
[Fact]
public void Create_WhenTitleIsEmpty_ReturnsValidationError()
{
    var command = new CreateCaseCommand("", "owner-1");
    var handler = new CreateCaseHandler();

    var result = handler.Handle(command);

    result.IsValid.ShouldBeFalse();
    result.Errors.ShouldContain("Title is required.");
}
```

## TDD Quality Rules

* Tests must be deterministic.
* Tests must not depend on execution order.
* Unit tests must be fast.
* Tests must have clear failure messages.
* Avoid testing implementation details.
* Do not mock simple value objects.
* Use integration tests for database and HTTP behaviour.
* Every bug fix should include a regression test where practical.

## TDD Evidence

A good PR shows:

* tests added or updated
* production code changed
* bug or story reference
* edge cases considered
* coverage preserved or improved