👁 Image
Atc.Test 3.0.0

Introduction

👁 NuGet Version

Atc.Test is a .NET helper library that streamlines authoring tests with xUnit v3, AutoFixture, NSubstitute, and AwesomeAssertions. It provides rich data attributes, automatic specimen customization, and ergonomic frozen value reuse to reduce ceremony and improve test readability.

Why Atc.Test

You can “just wire everything manually” with plain xUnit and hand‑rolled mocks—so why use this instead?

When It Delivers the Most Value

• Mid/large test suites (hundreds+ of theory cases).
• Domain services with evolving constructor graphs / dependencies.
• Teams that value refactor safety and consistent test style.
• Situations where only a few parameters per test truly matter.

When Bare xUnit (+ manual mocks) May Be Enough

• Very small or short‑lived codebases.
• Highly bespoke object graphs where you override almost every generated value anyway.
• Educational contexts emphasizing explicit wiring for learning.

Summary

Atc.Test trades a tiny amount of initial abstraction for compounding savings in refactors, readability, and consistency. AI can quickly generate boilerplate; this library’s value is eliminating the need for that boilerplate in the first place—and giving you a single, policy‑driven locus for customization and reuse.

Table of Content

• Introduction
  • Why Atc.Test
• Table of Content
  • Features
  • Getting Started
    • Install Package
    • Why xUnit Must Be Referenced Directly
    • First Test Examples
  • Advanced Usage
    • Frozen Reuse Scenarios
    • Auto Registration of Customizations
    • Helper Extensions
  • Requirements
  • How to Contribute

Features

• Data attributes integrating AutoFixture + NSubstitute: AutoNSubstituteData, InlineAutoNSubstituteData, MemberAutoNSubstituteData, ClassAutoNSubstituteData.
• Automatic interface/abstract substitution via NSubstitute.
• Exact-type frozen promotion for member data (reuse supplied instance across later [Frozen] parameters).
• Deterministic fixture configuration with opt‑in auto-registration of custom ICustomization / ISpecimenBuilder via [AutoRegister].
• Convenience extensions: equivalency options, substitute inspection helpers, task timeout helpers, object protected member access.
• Clear separation of concerns: you own the xUnit runner/version.

Getting Started

Install Package

Add Atc.Test to your test project along with explicit references to xUnit and the test SDK:

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
 <TargetFramework>net10.0</TargetFramework>
 <OutputType>Exe</OutputType>
 <UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner>
 </PropertyGroup>
 <ItemGroup>
 <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.6.0" />
 <PackageReference Include="xunit.v3" Version="3.2.2" />
 <PackageReference Include="Atc.Test" Version="$(LatestOrPinned)" />
 </ItemGroup>
</Project>

Why xUnit Must Be Referenced Directly

Atc.Test depends on xunit.v3.extensibility.core (the extensibility surface) but intentionally does not bring in the xunit.v3 meta-package:

• Avoid forcing a specific xUnit runner/meta-package on your project.
• Let you pin or float the xUnit version independently.
• Keep framework + runner decisions in your test project for predictable upgrades.
• Preserve the library’s focus: providing attributes/utilities instead of prescribing test infrastructure.

If you want a different xUnit patch/minor version, change the <PackageReference Include="xunit.v3" ... /> line—no changes to Atc.Test required.

xUnit v3 Only (Incompatible With v2)

Atc.Test relies on xUnit v3 extensibility APIs:

• Async data attribute signature: ValueTask<IReadOnlyCollection<ITheoryDataRow>> GetData(...).
• ITheoryDataRow & metadata (Label, Explicit, Timeout) preservation.
• DisposalTracker parameter passed to data attributes.

These do not exist in xUnit v2. Attempting to use a v2 framework or runner will result in discovery failures or compile errors.

Optional guard rails (not included by default):

<Target Name="ValidateXunitV3" BeforeTargets="Build">
 <Error Condition="!Exists('$(NuGetPackageRoot)xunit.v3/')"
 Text="Atc.Test requires an explicit PackageReference to xunit.v3 in the test project." />
</Target>

“Why no v2 support?” the answer is simply that the library embraces the cleaner v3 data extensibility model; back-porting would require a parallel code path and reduce clarity.

First Test Examples

public class CalculatorTests
{
 [Theory]
 [AutoNSubstituteData]
 public void AutoData_Generates_Specimens(int a, int b, Calculator sut)
 => sut.Add(a, b).Should().Be(a + b);

 [Theory]
 [InlineAutoNSubstituteData(2, 3)]
 public void InlineAutoData_Mixes_Inline_And_Auto(int a, int b, Calculator sut)
 => sut.Add(a, b).Should().Be(5);

 public static IEnumerable<object?[]> MemberSource()
 {
 yield return new object?[] { 1, 2 };
 yield return new object?[] { 10, 20 };
 }

 [Theory]
 [MemberAutoNSubstituteData(nameof(MemberSource))]
 public void MemberAutoData_Augments_Member_Data(int a, int b, Calculator sut)
 => sut.Add(a, b).Should().Be(a + b);
}

All remaining parameters (after inline/member supplied ones) are created via an AutoFixture IFixture that substitutes interfaces/abstract classes using NSubstitute.

Note NSubstitute is used automatically when the requested type is an interface or abstract class.

Advanced Usage

Frozen Reuse Scenarios

When you decorate a parameter with [Frozen], its resolved instance is reused for other specimens requiring that exact type. MemberAutoNSubstituteData adds exact-type promotion: reusing an earlier supplied value for a later [Frozen] parameter when that later slot was not part of the member row.

Example: Positional Reuse

[Theory]
[InlineAutoNSubstituteData(42)]
public void Positional_Frozen_Reuses_Inline_Value(
 [Frozen] int number,
 SomeConsumer consumer)
{
 consumer.NumberDependency.Should().Be(number);
}

Example: Exact-Type Promotion (Member Data)

public static IEnumerable<object?[]> ServiceRow()
{
 yield return new object?[] { Substitute.For<IMyService>() }; // supplies parameter 0 only
}

[Theory]
[MemberAutoNSubstituteData(nameof(ServiceRow))]
public void Promotion_Reuses_Earlier_Same_Type(
 IMyService supplied,
 [Frozen] IMyService frozenLater,
 NeedsService consumer)
{
 frozenLater.Should().BeSameAs(supplied);
 consumer.Service.Should().BeSameAs(supplied);
}

Example: Non-Promotion Across Different Interfaces

public interface IFoo {}
public interface IBar {}
public class DualImpl : IFoo, IBar {}

public static IEnumerable<object?[]> DualRow()
{
 yield return new object?[] { new DualImpl() }; // supplies IFoo parameter only
}

[Theory]
[MemberAutoNSubstituteData(nameof(DualRow))]
public void Different_Interface_Not_Promoted(
 IFoo foo,
 [Frozen] IBar bar,
 UsesBar consumer)
{
 bar.Should().NotBeSameAs(foo); // separate instance
 consumer.Bar.Should().BeSameAs(bar); // consumer wired to frozen IBar
}

Design Rationale:

• Class data is usually fully positional—implicit promotion might hide mistakes.
• Member data often supplies only a prefix—promotion reduces duplication while staying explicit.
• Exact-type restriction avoids cross-interface bleed (e.g., dual implementations hijacking unrelated abstractions).

Auto Registration of Customizations

Any ICustomization or ISpecimenBuilder decorated with [AutoRegister] is added automatically to the fixture created by FixtureFactory.Create().

Example:

[AutoRegister]
public class GuidCustomization : ICustomization
{
 public void Customize(IFixture fixture) => fixture.Register(() => Guid.NewGuid());
}

Helper Extensions

Requirements

Migrating from FluentAssertions

As of v3.0.0, Atc.Test depends on AwesomeAssertions (the Apache-2.0 community fork of FluentAssertions 7.x) instead of FluentAssertions, whose v8+ releases require a paid commercial license. To upgrade a consuming project:

1. Replace using FluentAssertions; with using AwesomeAssertions; (and likewise for the .Equivalency, .Primitives, .Execution, and .Extensions sub-namespaces, plus any <Using Include="FluentAssertions" /> global usings in your .csproj).
2. Remove any direct <PackageReference Include="FluentAssertions" ... /> from your test projects — Atc.Test brings in AwesomeAssertions transitively.
3. Your .Should()... assertions need no changes; the API is identical to FluentAssertions 7.x.

How to Contribute

Contribution Guidelines
Coding Guidelines