macalbert/envilder/dotnet-testing

Testing Conventions (.NET)

This skill defines the MANDATORY testing conventions for .NET projects. These are rules, not guidelines.

Documentation Rules

NO Comments Except AAA Markers

• NEVER write XML summaries on test methods or test classes
• NEVER write explanatory comments: code must be self-explanatory
• Only `// Arrange`, `// Act`, `// Assert` comments are allowed in tests
• The test name Should_X_When_Y already documents the intent

Libraries

Core Principles

1. AAA Pattern (Arrange – Act – Assert)

ALL tests MUST follow the AAA pattern, separated by inline comments.

Rules

• Each phase MUST be separated with comments
• Never mix phases
• **Each comment (// Arrange, // Act, // Assert) appears AT MOST ONCE

per test**: if you need two actions or two asserts, write two tests

• Act = one single invocation on the SUT. Multiple statements in Act only

if they are genuinely part of the same logical action (rare and exceptional). Two independent operations = two tests.

• All assertions belong in Assert only. No .Should() in Arrange or Act.

If you need a precondition check, extract it to a separate test or use a guard clause that throws: not an assertion.

• AAA markers are mandatory in ALL tests: including structural guards,

static completeness checks, and data validation tests. No exceptions.

• No `if`, `switch`, or conditional logic inside Arrange, Act, or Assert
• No `try/catch/finally` inside tests: use IAsyncLifetime or

IDisposable for teardown

• No `// Act & Assert` combined blocks: Act and Assert are ALWAYS separate
• For exceptions: act.Should().ThrowAsync<T>() (AwesomeAssertions)
• Omit comment if section is empty
• If a test needs branching, split it into separate tests

xUnit Example

[Fact(Timeout = CancellationTokenForTest.ShortTimeout)]
public async Task Should_CreateGroup_When_RequestIsValid()
{
    // Arrange
    var request = new CreateGroupRequest { Name = "Test Group" };
    var command = new CreateGroupCommand(request);
 
    // Act
    var actual = await _sut.Handle(command, CancellationToken.None);
 
    // Assert
    actual.Should().NotBeNull();
    actual.GroupId.Should().NotBeEmpty();
    _repository.Received(1).AddGroup(Arg.Any<Group>());
}

2. Test Naming Convention

Should_{ExpectedBehavior}_When_{Condition}

Rules

• PascalCase for both parts
• NO natural language
• NO vague names (Should_Work, TestHandler)
• NO missing When clause
• Method names only: xUnit uses [Fact] or [Theory], not description strings

3. Variable Naming (MANDATORY)

Test Class Structure

public class CreateGroupCommandHandlerTests
{
    private readonly Fixture _fixture;
    private readonly IEnvilderRepository _repository;
    private readonly CreateGroupCommandHandler _sut;
 
    public CreateGroupCommandHandlerTests()
    {
        _fixture = new();
        _repository = Substitute.For<IEnvilderRepository>();
        _sut = new(_repository);
    }
}

Exception Testing

Act and Assert MUST be separate.

✅ CORRECT

[Fact(Timeout = CancellationTokenForTest.ShortTimeout)]
public async Task Should_ThrowNotFound_When_GroupDoesNotExist()
{
    // Arrange
    _repository.GetByIdAsync(Arg.Any<Guid>(), Arg.Any<CancellationToken>())
        .Returns((Group?)null);
 
    // Act
    var act = () => _sut.Handle(query, CancellationToken.None);
 
    // Assert
    await act.Should().ThrowAsync<NotFoundException>();
}

❌ FORBIDDEN

// Act & Assert   ← NEVER
await Assert.ThrowsAsync<NotFoundException>(
    () => _sut.Handle(query, CancellationToken.None));

Teardown & Cleanup

Never use `try/finally` in tests. Use framework mechanisms:

public class MyTests : IAsyncLifetime
{
    private (string Name, string? Value)[] _originalEnvValues = [];
 
    public Task InitializeAsync()
    {
        _originalEnvValues = EnvVarNames
            .Select(v => (Name: v, Value: Environment.GetEnvironmentVariable(v)))
            .ToArray();
        return Task.CompletedTask;
    }
 
    public Task DisposeAsync()
    {
        foreach (var (name, value) in _originalEnvValues)
        {
            Environment.SetEnvironmentVariable(name, value);
        }
        return Task.CompletedTask;
    }
}

Verification Commands

Completion Criteria

• Test names follow Should_<Expected>_When_<Condition>
• AAA markers present (except structural guards), each at most once
• _sut/actual/expected used consistently
• All mock interactions verified with .Received()
• No try/catch/finally or control flow in test bodies
• Tests run green: dotnet test
• No format regressions: dotnet format --verify-no-changes