Common Testing Conventions

Testing Conventions Skill

Mandatory testing conventions across all stacks. Stack-specific libraries and examples are documented in dedicated supporting files.

Code Style Rules

NEVER write unnecessary comments or XML summaries. Exception: // Arrange, // Act, // Assert comments are REQUIRED in tests.

When to Use

• Writing unit tests for handlers, services, or components
• Writing integration tests with WebApplicationFactory
• Writing E2E tests with Playwright
• Setting up test class structure
• Verifying mock interactions

Supporting Files

Core Principles

1. Test Production Behavior; Diagnose Test Support Only When Necessary

Tests specify production behavior. Do not create tests whose subject is test-only code by default, including fixtures, mothers, builders, mocks, stubs, seeders, test containers, data loaders, or runner configuration. Shared, reusable, independently versioned, or public test-support code is still test-only code; those traits do not justify testing it directly.

Start by validating test-infrastructure changes through the production-behavior tests that consume them or a direct reproduction of the affected workflow. A focused test of support code is allowed only when those paths cannot identify a failure with enough diagnostic precision. It must target the smallest stable contract needed to localize the fault and state why consumer or workflow evidence is insufficient.

This is diagnostic instrumentation, not default behavioral verification. Never add it for coverage or to mirror implementation details.

2. AAA Pattern (Mandatory)

All tests MUST follow Arrange-Act-Assert with clear comments:

[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>());
}

Rules:

• Each comment (// Arrange, // Act, // Assert) appears AT MOST ONCE per test: if you need two actions, 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.
• AAA markers are mandatory in ALL tests: including structural guards, static completeness checks, and data validation tests. No exceptions.
• Each section clearly separated by comments
• Never mix phases
• All assertions belong in Assert only. No expect(), .Should(), assert, or any verification statement in Arrange or Act. If you feel tempted to assert in Arrange (precondition check), extract it to a separate test or use a guard clause that throws: not an assertion.
• No if, switch, or conditional logic inside Arrange, Act, or Assert blocks
• No try/catch/finally inside tests: use framework teardown (IAsyncLifetime, [ClassCleanup], pytest yield fixtures)
• No // Act & Assert combined blocks: Act and Assert are ALWAYS separate phases
• For exceptions: C# → AwesomeAssertions .Should().ThrowAsync<T>() | Python → lambda + pytest.raises() | Vitest → expect(...).rejects.toThrow()
• Omit comment if section is empty
• If a test needs branching, split it into separate test methods (one per scenario)