Testing and Requirements📋

// Era 1: Code — tests exist, but what do they verify?
public class UserServiceTests
{
    private readonly UserService _sut;
    private readonly Mock<IUserRepository> _repo;
    private readonly Mock<IRoleRepository> _roleRepo;

    public UserServiceTests()
    {
        _repo = new Mock<IUserRepository>();
        _roleRepo = new Mock<IRoleRepository>();
        _sut = new UserService(_repo.Object, _roleRepo.Object);
    }

    [Fact]
    public async Task AssignRole_ShouldWork()
    {
        // Arrange
        var admin = new User { Id = Guid.NewGuid(), Role = "Admin" };
        var target = new User { Id = Guid.NewGuid(), Role = "Viewer" };
        _repo.Setup(r => r.GetByIdAsync(admin.Id))
            .ReturnsAsync(admin);
        _repo.Setup(r => r.GetByIdAsync(target.Id))
            .ReturnsAsync(target);

        // Act
        var result = await _sut.AssignRoleAsync(
            admin.Id, target.Id, "Editor");

        // Assert
        result.IsSuccess.Should().BeTrue();
        _repo.Verify(r => r.UpdateAsync(
            It.Is<User>(u => u.Role == "Editor")), Times.Once);
    }

    [Fact]
    public async Task AssignRole_NonAdmin_ShouldFail()
    {
        var viewer = new User { Id = Guid.NewGuid(), Role = "Viewer" };
        var target = new User { Id = Guid.NewGuid(), Role = "Viewer" };
        _repo.Setup(r => r.GetByIdAsync(viewer.Id))
            .ReturnsAsync(viewer);
        _repo.Setup(r => r.GetByIdAsync(target.Id))
            .ReturnsAsync(target);

        var result = await _sut.AssignRoleAsync(
            viewer.Id, target.Id, "Editor");

        result.IsSuccess.Should().BeFalse();
        result.Error.Should().Be("Only admins can assign roles");
    }

    [Fact]
    public async Task GetUser_ShouldReturnUser()
    {
        var user = new User { Id = Guid.NewGuid(), Role = "Admin" };
        _repo.Setup(r => r.GetByIdAsync(user.Id))
            .ReturnsAsync(user);

        var result = await _sut.GetByIdAsync(user.Id);

        result.Should().NotBeNull();
        result!.Id.Should().Be(user.Id);
    }

    [Fact]
    public async Task DeleteUser_ShouldSoftDelete()
    {
        var user = new User { Id = Guid.NewGuid(), IsDeleted = false };
        _repo.Setup(r => r.GetByIdAsync(user.Id))
            .ReturnsAsync(user);

        await _sut.DeleteAsync(user.Id);

        _repo.Verify(r => r.UpdateAsync(
            It.Is<User>(u => u.IsDeleted)), Times.Once);
    }

    [Fact]
    public async Task ListUsers_ShouldFilterDeleted()
    {
        _repo.Setup(r => r.GetAllAsync())
            .ReturnsAsync(new[]
            {
                new User { Id = Guid.NewGuid(), IsDeleted = false },
                new User { Id = Guid.NewGuid(), IsDeleted = true },
            });

        var result = await _sut.ListActiveUsersAsync();

        result.Should().HaveCount(1);
    }
}

// Era 2: Configuration — string-based Trait metadata
public class UserServiceTests
{
    private readonly UserService _sut;
    private readonly Mock<IUserRepository> _repo;
    private readonly Mock<IRoleRepository> _roleRepo;

    public UserServiceTests()
    {
        _repo = new Mock<IUserRepository>();
        _roleRepo = new Mock<IRoleRepository>();
        _sut = new UserService(_repo.Object, _roleRepo.Object);
    }

    [Fact]
    [Trait("Feature", "FEATURE-456")]
    [Trait("AC", "AdminCanAssignRoles")]
    [Trait("Priority", "High")]
    public async Task AssignRole_AdminCanAssign_ShouldSucceed()
    {
        var admin = new User { Id = Guid.NewGuid(), Role = "Admin" };
        var target = new User { Id = Guid.NewGuid(), Role = "Viewer" };
        _repo.Setup(r => r.GetByIdAsync(admin.Id))
            .ReturnsAsync(admin);
        _repo.Setup(r => r.GetByIdAsync(target.Id))
            .ReturnsAsync(target);

        var result = await _sut.AssignRoleAsync(
            admin.Id, target.Id, "Editor");

        result.IsSuccess.Should().BeTrue();
    }

    [Fact]
    [Trait("Feature", "FEATURE-456")]
    [Trait("AC", "AdminCanAssignRoles")]
    public async Task AssignRole_NonAdmin_ShouldBeRejected()
    {
        var viewer = new User { Id = Guid.NewGuid(), Role = "Viewer" };
        var target = new User { Id = Guid.NewGuid(), Role = "Viewer" };
        _repo.Setup(r => r.GetByIdAsync(viewer.Id))
            .ReturnsAsync(viewer);
        _repo.Setup(r => r.GetByIdAsync(target.Id))
            .ReturnsAsync(target);

        var result = await _sut.AssignRoleAsync(
            viewer.Id, target.Id, "Editor");

        result.IsSuccess.Should().BeFalse();
    }

    [Fact]
    [Trait("Feature", "FEATURE-456")]
    [Trait("AC", "ViewerHasReadOnlyAccess")]
    public async Task Viewer_CannotModifyResources()
    {
        var viewer = new User { Id = Guid.NewGuid(), Role = "Viewer" };

        var result = await _sut.UpdateResourceAsync(
            viewer.Id, Guid.NewGuid(), "new value");

        result.IsSuccess.Should().BeFalse();
        result.Error.Should().Contain("read-only");
    }

    [Fact]
    [Trait("Feature", "FEAT-456")]  // Typo: FEAT vs FEATURE
    [Trait("AC", "RoleChangeImmediate")]
    public async Task RoleChange_TakesEffectWithoutRestart()
    {
        var user = new User { Id = Guid.NewGuid(), Role = "Viewer" };
        _repo.Setup(r => r.GetByIdAsync(user.Id))
            .ReturnsAsync(user);

        await _sut.AssignRoleAsync(
            Guid.NewGuid(), user.Id, "Editor");

        // Verify the change is immediately visible
        var updated = await _sut.GetByIdAsync(user.Id);
        updated!.Role.Should().Be("Editor");
    }
}

MyApp.Tests/
├── Features/
│   ├── UserRoles/
│   │   ├── AdminCanAssignRoles_Tests.cs
│   │   ├── ViewerHasReadOnlyAccess_Tests.cs
│   │   └── RoleChangeTakesEffectImmediately_Tests.cs
│   ├── OrderProcessing/
│   │   ├── OrderCanBeCreated_Tests.cs
│   │   ├── OrderCanBeCancelled_Tests.cs
│   │   ├── OrderTotalIsCalculatedCorrectly_Tests.cs
│   │   └── PaymentIsProcessedOnSubmission_Tests.cs
│   ├── Notifications/
│   │   ├── UserReceivesEmailOnOrderConfirmation_Tests.cs
│   │   └── AdminReceivesAlertOnCriticalError_Tests.cs
│   └── Authentication/
│       ├── TokensExpireAfterOneHour_Tests.cs
│       ├── RefreshTokenExtendsSession_Tests.cs
│       └── InvalidCredentialsReturnUnauthorized_Tests.cs
├── Integration/
│   └── ...
└── Smoke/
    └── ...

// Era 3: Convention — folder = feature, class = AC, name = behavior
namespace MyApp.Tests.Features.UserRoles;

/// <summary>
/// Convention: class name = AC name + "_Tests"
/// Convention: folder = feature name
/// Convention: each method tests one scenario of the AC
/// </summary>
public class AdminCanAssignRoles_Tests : IClassFixture<TestFixture>
{
    private readonly TestFixture _fixture;

    public AdminCanAssignRoles_Tests(TestFixture fixture)
    {
        _fixture = fixture;
    }

    [Fact]
    public async Task Admin_Assigns_Editor_Role_To_Viewer()
    {
        // Arrange
        var admin = await _fixture.CreateUserAsync("Admin");
        var viewer = await _fixture.CreateUserAsync("Viewer");

        // Act
        var result = await _fixture.UserService
            .AssignRoleAsync(admin.Id, viewer.Id, "Editor");

        // Assert
        result.IsSuccess.Should().BeTrue();
        var updated = await _fixture.UserService
            .GetByIdAsync(viewer.Id);
        updated!.Role.Should().Be("Editor");
    }

    [Fact]
    public async Task NonAdmin_Cannot_Assign_Roles()
    {
        var viewer = await _fixture.CreateUserAsync("Viewer");
        var target = await _fixture.CreateUserAsync("Viewer");

        var result = await _fixture.UserService
            .AssignRoleAsync(viewer.Id, target.Id, "Editor");

        result.IsSuccess.Should().BeFalse();
        result.Error.Should().Be("Only admins can assign roles");
    }

    [Fact]
    public async Task Admin_Cannot_Assign_NonExistent_Role()
    {
        var admin = await _fixture.CreateUserAsync("Admin");
        var target = await _fixture.CreateUserAsync("Viewer");

        var result = await _fixture.UserService
            .AssignRoleAsync(admin.Id, target.Id, "SuperGod");

        result.IsSuccess.Should().BeFalse();
        result.Error.Should().Contain("Role 'SuperGod' does not exist");
    }
}

<!-- wiki/test-conventions.md — the document every team writes -->

# Test Organization Conventions

## Folder Structure
- All feature tests live under `Features/{FeatureName}/`
- Feature folder names must match the Jira feature title (PascalCase, no spaces)
- Each acceptance criterion gets its own test class: `{ACName}_Tests.cs`
- Integration tests live under `Integration/{FeatureName}/`
- Smoke tests live under `Smoke/`

## Naming Conventions
- Test class: `{AcceptanceCriterionName}_Tests`
- Test method: `{Scenario}_Should_{ExpectedResult}` or `{Given}_{When}_{Then}`
- Fixture class: `{FeatureName}Fixture`

## Requirement Coverage
- Every feature in Jira MUST have a corresponding folder in `Features/`
- Every AC in Jira MUST have a corresponding test class
- Minimum 2 test methods per AC (happy path + at least one failure path)
- Coverage gate: 80% line coverage minimum per feature folder

## When Adding a New Feature
1. Create folder: `Features/{FeatureName}/`
2. Create one test class per AC
3. Write minimum 2 tests per AC class
4. Verify coverage meets 80% threshold
5. Update the requirements matrix spreadsheet (SharePoint)

## When Modifying an Existing Feature
1. Check if AC list in Jira has changed
2. Add/remove test classes to match
3. Update tests in affected AC classes
4. Re-verify coverage threshold
5. Update the requirements matrix spreadsheet (SharePoint)

## Exceptions
- Utility tests (helpers, extensions) go in `Utilities/`
- Performance tests go in `Performance/` with `[Trait("Type", "Perf")]`
- Tests that span multiple features go in `CrossCutting/` with Traits for each feature

// Convention enforcement: architecture tests that verify test organization
public class TestConventionTests
{
    private static readonly string[] KnownFeatures = new[]
    {
        "UserRoles", "OrderProcessing", "Notifications",
        "Authentication", "Payments", "Inventory",
        "Reporting", "AuditLog"
        // Manually maintained. Always out of date.
    };

    [Fact]
    public void Every_Feature_Has_A_Test_Folder()
    {
        var testAssembly = typeof(TestConventionTests).Assembly;
        var testNamespaces = testAssembly.GetTypes()
            .Where(t => t.Namespace?.Contains("Features") == true)
            .Select(t => t.Namespace!.Split('.').Last())
            .Distinct()
            .ToHashSet();

        foreach (var feature in KnownFeatures)
        {
            testNamespaces.Should().Contain(feature,
                $"Feature '{feature}' must have a test folder " +
                $"under Features/");
        }
    }

    [Fact]
    public void Test_Classes_Follow_Naming_Convention()
    {
        var testTypes = typeof(TestConventionTests).Assembly
            .GetTypes()
            .Where(t => t.Namespace?.Contains("Features") == true)
            .Where(t => t.IsClass && t.IsPublic);

        foreach (var type in testTypes)
        {
            type.Name.Should().EndWith("_Tests",
                $"Test class '{type.Name}' must follow the " +
                $"'{{ACName}}_Tests' naming convention");
        }
    }

    [Fact]
    public void Each_Test_Class_Has_Minimum_Two_Tests()
    {
        var testTypes = typeof(TestConventionTests).Assembly
            .GetTypes()
            .Where(t => t.Namespace?.Contains("Features") == true)
            .Where(t => t.IsClass && t.IsPublic);

        foreach (var type in testTypes)
        {
            var factCount = type.GetMethods()
                .Count(m => m.GetCustomAttribute<FactAttribute>() != null
                    || m.GetCustomAttribute<TheoryAttribute>() != null);

            factCount.Should().BeGreaterOrEqualTo(2,
                $"Test class '{type.Name}' must have at least 2 " +
                $"test methods (happy + failure path)");
        }
    }
}

#!/bin/bash
# ci/check-test-coverage.sh — coverage gate per feature folder

THRESHOLD=80

# Run tests with coverage
dotnet test --collect:"XPlat Code Coverage" \
    --results-directory ./coverage

# Parse coverage per feature folder
for feature_dir in test/MyApp.Tests/Features/*/; do
    feature=$(basename "$feature_dir")
    coverage=$(reportgenerator \
        -reports:./coverage/**/coverage.cobertura.xml \
        -targetdir:./coverage/report \
        -reporttypes:TextSummary \
        -classfilters:"+MyApp.*$feature*" \
        | grep "Line coverage" \
        | grep -oP '\d+\.\d+')

    if (( $(echo "$coverage < $THRESHOLD" | bc -l) )); then
        echo "FAIL: Feature '$feature' coverage is ${coverage}% " \
             "(threshold: ${THRESHOLD}%)"
        exit 1
    fi
    echo "PASS: Feature '$feature' coverage: ${coverage}%"
done

# .github/workflows/test-compliance.yml
name: Test Compliance Check

on: [push, pull_request]

jobs:
  test-compliance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run tests with coverage
        run: |
          dotnet test --collect:"XPlat Code Coverage" \
            --results-directory ./coverage

      - name: Check feature folder coverage
        run: bash ci/check-test-coverage.sh

      - name: Verify test naming conventions
        run: |
          dotnet test --filter "FullyQualifiedName~TestConventionTests" \
            --logger "console;verbosity=detailed"

      - name: Generate requirements matrix
        run: |
          # Parse test results and cross-reference with requirements list
          python3 scripts/generate-requirements-matrix.py \
            --requirements requirements.csv \
            --test-results ./coverage \
            --output matrix-report.html

      - name: Upload compliance report
        uses: actions/upload-artifact@v4
        with:
          name: compliance-report
          path: matrix-report.html

      - name: Comment on PR with coverage gaps
        if: github.event_name == 'pull_request'
        run: |
          # Parse the matrix and post gaps as PR comment
          python3 scripts/post-coverage-gaps.py \
            --matrix matrix-report.html \
            --pr ${{ github.event.pull_request.number }}

// Requirements are types. ACs are abstract methods.
// This IS the single source of truth.
namespace MyApp.Requirements.Features;

public abstract record UserRolesFeature : Feature<PlatformScalabilityEpic>
{
    public override string Title => "User roles and permissions";
    public override RequirementPriority Priority => RequirementPriority.High;
    public override string Owner => "auth-team";

    // AC1: Admin users can assign roles to other users
    public abstract AcceptanceCriterionResult AdminCanAssignRoles(
        UserId actingUser, UserId targetUser, RoleId role);

    // AC2: Viewer users have read-only access
    public abstract AcceptanceCriterionResult ViewerHasReadOnlyAccess(
        UserId viewer, ResourceId resource);

    // AC3: Role changes take effect immediately
    public abstract AcceptanceCriterionResult RoleChangeTakesEffectImmediately(
        UserId user, RoleId previousRole, RoleId newRole);
}

// Era 4: Contention — typed requirement and AC references
namespace MyApp.Tests.Features;

[ForRequirement(typeof(UserRolesFeature))]
public class UserRolesFeature_Tests : IClassFixture<TestFixture>
{
    private readonly TestFixture _fixture;

    public UserRolesFeature_Tests(TestFixture fixture)
    {
        _fixture = fixture;
    }

    [Fact]
    [Verifies(nameof(UserRolesFeature.AdminCanAssignRoles))]
    public async Task Admin_Assigns_Editor_Role_To_Viewer()
    {
        var admin = await _fixture.CreateUserAsync("Admin");
        var viewer = await _fixture.CreateUserAsync("Viewer");

        var result = await _fixture.UserService
            .AssignRoleAsync(admin.Id, viewer.Id, "Editor");

        result.IsSuccess.Should().BeTrue();
        var updated = await _fixture.UserService
            .GetByIdAsync(viewer.Id);
        updated!.Role.Should().Be("Editor");
    }

    [Fact]
    [Verifies(nameof(UserRolesFeature.AdminCanAssignRoles))]
    public async Task NonAdmin_Cannot_Assign_Roles()
    {
        var viewer = await _fixture.CreateUserAsync("Viewer");
        var target = await _fixture.CreateUserAsync("Viewer");

        var result = await _fixture.UserService
            .AssignRoleAsync(viewer.Id, target.Id, "Editor");

        result.IsSuccess.Should().BeFalse();
        result.Error.Should().Be("Only admins can assign roles");
    }

    [Fact]
    [Verifies(nameof(UserRolesFeature.AdminCanAssignRoles))]
    public async Task Admin_Cannot_Assign_NonExistent_Role()
    {
        var admin = await _fixture.CreateUserAsync("Admin");
        var target = await _fixture.CreateUserAsync("Viewer");

        var result = await _fixture.UserService
            .AssignRoleAsync(admin.Id, target.Id, "SuperGod");

        result.IsSuccess.Should().BeFalse();
    }

    [Fact]
    [Verifies(nameof(UserRolesFeature.ViewerHasReadOnlyAccess))]
    public async Task Viewer_Cannot_Modify_Resources()
    {
        var viewer = await _fixture.CreateUserAsync("Viewer");

        var result = await _fixture.UserService
            .UpdateResourceAsync(viewer.Id, Guid.NewGuid(), "new value");

        result.IsSuccess.Should().BeFalse();
        result.Error.Should().Contain("read-only");
    }

    [Fact]
    [Verifies(nameof(UserRolesFeature.ViewerHasReadOnlyAccess))]
    public async Task Viewer_Can_Read_Resources()
    {
        var viewer = await _fixture.CreateUserAsync("Viewer");
        var resource = await _fixture.CreateResourceAsync();

        var result = await _fixture.UserService
            .GetResourceAsync(viewer.Id, resource.Id);

        result.IsSuccess.Should().BeTrue();
    }

    [Fact]
    [Verifies(nameof(UserRolesFeature.RoleChangeTakesEffectImmediately))]
    public async Task RoleChange_Is_Visible_Without_Restart()
    {
        var admin = await _fixture.CreateUserAsync("Admin");
        var user = await _fixture.CreateUserAsync("Viewer");

        await _fixture.UserService
            .AssignRoleAsync(admin.Id, user.Id, "Editor");

        // No restart. No cache invalidation. Immediate.
        var permissions = await _fixture.UserService
            .GetPermissionsAsync(user.Id);
        permissions.Should().Contain("edit");
    }
}

namespace MyApp.Requirements;

/// <summary>
/// Links a test class to the requirement it verifies.
/// The type parameter must be a concrete requirement type.
/// </summary>
[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
public sealed class ForRequirementAttribute : Attribute
{
    public Type RequirementType { get; }

    public ForRequirementAttribute(Type requirementType)
    {
        RequirementType = requirementType;
    }
}

/// <summary>
/// Links a test method to the acceptance criterion it verifies.
/// The name must match an abstract method on the requirement type.
/// </summary>
[AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
public sealed class VerifiesAttribute : Attribute
{
    public string AcceptanceCriterionName { get; }

    public VerifiesAttribute(string acceptanceCriterionName)
    {
        AcceptanceCriterionName = acceptanceCriterionName;
    }
}

// Generated: RequirementComplianceMatrix.g.cs
// <auto-generated>
//   Generated by MyApp.Requirements.Analyzers
//   Do not edit manually.
// </auto-generated>

namespace MyApp.Tests.Generated;

public static class RequirementComplianceMatrix
{
    public static readonly IReadOnlyList<FeatureCompliance> Features = new[]
    {
        new FeatureCompliance(
            FeatureType: typeof(UserRolesFeature),
            Title: "User roles and permissions",
            Priority: RequirementPriority.High,
            AcceptanceCriteria: new[]
            {
                new ACCompliance(
                    Name: "AdminCanAssignRoles",
                    TestCount: 3,
                    Tests: new[]
                    {
                        "UserRolesFeature_Tests.Admin_Assigns_Editor_Role_To_Viewer",
                        "UserRolesFeature_Tests.NonAdmin_Cannot_Assign_Roles",
                        "UserRolesFeature_Tests.Admin_Cannot_Assign_NonExistent_Role"
                    }),
                new ACCompliance(
                    Name: "ViewerHasReadOnlyAccess",
                    TestCount: 2,
                    Tests: new[]
                    {
                        "UserRolesFeature_Tests.Viewer_Cannot_Modify_Resources",
                        "UserRolesFeature_Tests.Viewer_Can_Read_Resources"
                    }),
                new ACCompliance(
                    Name: "RoleChangeTakesEffectImmediately",
                    TestCount: 1,
                    Tests: new[]
                    {
                        "UserRolesFeature_Tests.RoleChange_Is_Visible_Without_Restart"
                    })
            },
            OverallCoverage: 1.0,  // 3/3 ACs have tests
            TotalTests: 6
        ),

        new FeatureCompliance(
            FeatureType: typeof(OrderProcessingFeature),
            Title: "Order processing and fulfillment",
            Priority: RequirementPriority.Critical,
            AcceptanceCriteria: new[]
            {
                new ACCompliance(
                    Name: "OrderCanBeCreated",
                    TestCount: 4,
                    Tests: new[] { /* ... */ }),
                new ACCompliance(
                    Name: "OrderCanBeCancelled",
                    TestCount: 2,
                    Tests: new[] { /* ... */ }),
                new ACCompliance(
                    Name: "OrderTotalIsCalculatedCorrectly",
                    TestCount: 5,
                    Tests: new[] { /* ... */ }),
                new ACCompliance(
                    Name: "PaymentIsProcessedOnSubmission",
                    TestCount: 0,      // ← No tests! Flagged.
                    Tests: Array.Empty<string>())
            },
            OverallCoverage: 0.75,  // 3/4 ACs have tests
            TotalTests: 11
        )
    };

    // Summary statistics
    public const int TotalFeatures = 8;
    public const int TotalACs = 24;
    public const int TestedACs = 21;
    public const int UntestedACs = 3;
    public const double OverallCoverage = 0.875;  // 87.5%
}

// Generated: RequirementComplianceReport.g.cs
// Also generates a human-readable summary as a doc comment

/// <summary>
/// REQUIREMENT COMPLIANCE REPORT
/// Generated: 2026-03-29 14:32:07 UTC
///
/// ┌────────────────────────────────┬──────────┬─────────┬──────────┐
/// │ Feature                        │ Priority │ ACs     │ Coverage │
/// ├────────────────────────────────┼──────────┼─────────┼──────────┤
/// │ User roles and permissions     │ High     │ 3/3     │ 100.0%   │
/// │ Order processing               │ Critical │ 3/4     │  75.0%   │
/// │ Notifications                  │ Medium   │ 2/2     │ 100.0%   │
/// │ Authentication                 │ Critical │ 3/3     │ 100.0%   │
/// │ Payments                       │ Critical │ 2/3     │  66.7%   │
/// │ Inventory                      │ High     │ 4/4     │ 100.0%   │
/// │ Reporting                      │ Low      │ 2/2     │ 100.0%   │
/// │ Audit log                      │ Medium   │ 2/3     │  66.7%   │
/// ├────────────────────────────────┼──────────┼─────────┼──────────┤
/// │ TOTAL                          │          │ 21/24   │  87.5%   │
/// └────────────────────────────────┴──────────┴─────────┴──────────┘
///
/// UNTESTED ACCEPTANCE CRITERIA:
///   ⚠ OrderProcessingFeature.PaymentIsProcessedOnSubmission (Critical)
///   ⚠ PaymentsFeature.RefundCanBeIssued (Critical)
///   ⚠ AuditLogFeature.EntriesAreImmutable (Medium)
/// </summary>
public static class RequirementComplianceReport { }

// REQ001: Feature with no test class
// Severity: Warning (configurable to Error)
// Fires when: a type inheriting Feature<> has no [ForRequirement] test class anywhere in the test assembly

warning REQ001: Feature 'PaymentsFeature' has no test class with
    [ForRequirement(typeof(PaymentsFeature))]. No acceptance criteria
    are being verified.
    --> src/MyApp.Requirements/Features/PaymentsFeature.cs(8,1)

// REQ002: [Verifies] references non-existent AC
// Severity: Error
// Fires when: the string in [Verifies("X")] does not match any abstract method on the requirement type

error REQ002: [Verifies("ProcessPaymnet")] on method
    'PaymentsFeature_Tests.Payment_Is_Processed' does not match any
    acceptance criterion on 'PaymentsFeature'. Did you mean
    'ProcessPayment'?
    --> test/MyApp.Tests/Features/PaymentsFeature_Tests.cs(24,6)

// REQ003: Test method without [Verifies]
// Severity: Info
// Fires when: a test method in a [ForRequirement] class has [Fact] or [Theory] but no [Verifies]

info REQ003: Test method 'PaymentsFeature_Tests.SomeHelperTest' in a
    [ForRequirement] class has no [Verifies] attribute. It will not
    appear in the compliance matrix.
    --> test/MyApp.Tests/Features/PaymentsFeature_Tests.cs(47,5)

// REQ004: AC with no test
// Severity: Warning (configurable to Error for Critical features)
// Fires when: an abstract method on a Feature type has no [Verifies] test method anywhere

warning REQ004: Acceptance criterion
    'OrderProcessingFeature.PaymentIsProcessedOnSubmission' has no
    test method with [Verifies("PaymentIsProcessedOnSubmission")].
    Feature priority: Critical.
    --> src/MyApp.Requirements/Features/OrderProcessingFeature.cs(22,5)

// The PM (or the tech lead) adds this to the requirement type:
public abstract AcceptanceCriterionResult RoleCanBeTemporarilyElevated(
    UserId user, RoleId elevatedRole, TimeSpan duration);

# .editorconfig — per-project analyzer configuration

# Strict mode: treat untested features as build errors
[test/MyApp.Tests/**]
dotnet_diagnostic.REQ001.severity = error   # Feature with no test class
dotnet_diagnostic.REQ002.severity = error   # Bad AC reference (always error)
dotnet_diagnostic.REQ003.severity = suggestion  # Test without [Verifies]
dotnet_diagnostic.REQ004.severity = error   # AC with no test

<!-- MyApp.Tests.csproj — MSBuild configuration for compliance thresholds -->
<PropertyGroup>
  <RequirementComplianceMinimum>90</RequirementComplianceMinimum>
  <TreatUntestedCriticalFeaturesAsErrors>true</TreatUntestedCriticalFeaturesAsErrors>
  <GenerateComplianceReport>true</GenerateComplianceReport>
  <ComplianceReportFormat>json;markdown</ComplianceReportFormat>
</PropertyGroup>

{
  "generated": "2026-03-29T14:32:07Z",
  "summary": {
    "totalFeatures": 8,
    "testedFeatures": 7,
    "totalACs": 24,
    "testedACs": 21,
    "overallCoverage": 0.875,
    "passingThreshold": true
  },
  "features": [
    {
      "type": "MyApp.Requirements.Features.UserRolesFeature",
      "title": "User roles and permissions",
      "priority": "High",
      "coverage": 1.0,
      "acceptanceCriteria": [
        {
          "name": "AdminCanAssignRoles",
          "testCount": 3,
          "tested": true
        },
        {
          "name": "ViewerHasReadOnlyAccess",
          "testCount": 2,
          "tested": true
        },
        {
          "name": "RoleChangeTakesEffectImmediately",
          "testCount": 1,
          "tested": true
        }
      ]
    },
    {
      "type": "MyApp.Requirements.Features.OrderProcessingFeature",
      "title": "Order processing and fulfillment",
      "priority": "Critical",
      "coverage": 0.75,
      "acceptanceCriteria": [
        {
          "name": "OrderCanBeCreated",
          "testCount": 4,
          "tested": true
        },
        {
          "name": "OrderCanBeCancelled",
          "testCount": 2,
          "tested": true
        },
        {
          "name": "OrderTotalIsCalculatedCorrectly",
          "testCount": 5,
          "tested": true
        },
        {
          "name": "PaymentIsProcessedOnSubmission",
          "testCount": 0,
          "tested": false
        }
      ]
    }
  ],
  "violations": [
    {
      "code": "REQ004",
      "feature": "OrderProcessingFeature",
      "ac": "PaymentIsProcessedOnSubmission",
      "priority": "Critical",
      "message": "Critical AC has no test coverage"
    }
  ]
}

// Optional: runtime compliance check via IHostedService
public class ComplianceValidationService : IHostedService
{
    private readonly ILogger<ComplianceValidationService> _logger;

    public ComplianceValidationService(
        ILogger<ComplianceValidationService> logger)
    {
        _logger = logger;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        var matrix = RequirementComplianceMatrix.Features;

        var untestedCritical = matrix
            .Where(f => f.Priority == RequirementPriority.Critical)
            .Where(f => f.OverallCoverage < 1.0)
            .ToList();

        if (untestedCritical.Count > 0)
        {
            foreach (var feature in untestedCritical)
            {
                var gaps = feature.AcceptanceCriteria
                    .Where(ac => ac.TestCount == 0)
                    .Select(ac => ac.Name);

                _logger.LogWarning(
                    "Critical feature '{Feature}' has untested ACs: {ACs}",
                    feature.Title,
                    string.Join(", ", gaps));
            }

            // In production: log and alert
            // In staging: throw to prevent deployment
            if (Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT")
                == "Staging")
            {
                throw new InvalidOperationException(
                    $"{untestedCritical.Count} critical features have " +
                    $"untested acceptance criteria. " +
                    $"Deployment blocked in Staging.");
            }
        }

        _logger.LogInformation(
            "Compliance check passed. {Tested}/{Total} ACs verified " +
            "({Coverage:P1})",
            RequirementComplianceMatrix.TestedACs,
            RequirementComplianceMatrix.TotalACs,
            RequirementComplianceMatrix.OverallCoverage);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
        => Task.CompletedTask;
}

// Registration — one line in Program.cs
services.AddHostedService<ComplianceValidationService>();

warn: ComplianceValidationService[0]
      Critical feature 'Order processing and fulfillment' has untested ACs:
      PaymentIsProcessedOnSubmission
fail: ComplianceValidationService[0]
      1 critical features have untested acceptance criteria.
      Deployment blocked in Staging.
Application startup exception: System.InvalidOperationException:
      1 critical features have untested acceptance criteria.
      Deployment blocked in Staging.