ZeroAlloc.TestHelpers 1.4.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package ZeroAlloc.TestHelpers --version 1.4.0
                    
NuGet\Install-Package ZeroAlloc.TestHelpers -Version 1.4.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ZeroAlloc.TestHelpers" Version="1.4.0">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="ZeroAlloc.TestHelpers" Version="1.4.0" />
                    
Directory.Packages.props
<PackageReference Include="ZeroAlloc.TestHelpers">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add ZeroAlloc.TestHelpers --version 1.4.0
                    
#r "nuget: ZeroAlloc.TestHelpers, 1.4.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package ZeroAlloc.TestHelpers@1.4.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=ZeroAlloc.TestHelpers&version=1.4.0
                    
Install as a Cake Addin
#tool nuget:?package=ZeroAlloc.TestHelpers&version=1.4.0
                    
Install as a Cake Tool

ZeroAlloc.TestHelpers

Source-distributed test helpers for the ZeroAlloc.* ecosystem.

Usage

<PackageReference Include="ZeroAlloc.TestHelpers" Version="1.*">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>contentfiles;build</IncludeAssets>
</PackageReference>

The package has no runtime DLL. It ships two source files that compile directly into your assembly as internal static classes in the ZeroAlloc.TestHelpers namespace:

File Needs Compiled into your project
AllocationGate.cs the BCL only always
GeneratorSnapshot.cs Microsoft.CodeAnalysis only when your project references Roslyn

Keep build in IncludeAssets. The package's build/ZeroAlloc.TestHelpers.targets decides whether GeneratorSnapshot.cs is compiled. Without it, GeneratorSnapshot.cs is always compiled, and a project with no Roslyn reference fails with CS0234: The type or namespace name 'CodeAnalysis' does not exist in the namespace 'Microsoft'.

Choosing whether GeneratorSnapshot is compiled

By default the targets file checks your resolved references. GeneratorSnapshot.cs is compiled only when Microsoft.CodeAnalysis.dll is among them, whether it comes from a direct Microsoft.CodeAnalysis.CSharp reference or arrives transitively. Source-generator test projects already reference Roslyn, so they need no configuration. A Native AOT smoke app or a plain unit-test project gets AllocationGate alone and does not pull in the compiler.

To override the check, set ZeroAllocTestHelpersIncludeGeneratorSnapshot:

<PropertyGroup>
  
  <ZeroAllocTestHelpersIncludeGeneratorSnapshot>false</ZeroAllocTestHelpersIncludeGeneratorSnapshot>
</PropertyGroup>

API

AllocationGate

  • AllocationGate.AssertBudget(int budgetBytes, int iterations, Action action, string label) runs action iterations times after a warmup and a forced GC. It throws InvalidOperationException if total allocations exceed budgetBytes * iterations.
  • AllocationGate.AssertBudgetValueTask<T>(int budgetBytes, int iterations, Func<ValueTask<T>> action, string label) is the same check for APIs that return ValueTask<T>. It throws if the supplied ValueTask<T> did not complete synchronously, because awaiter machinery would pollute the measurement.
  • AllocationGate.MeasureBytesPerCall(int iterations, Action action) and AllocationGate.MeasureBytesPerCallValueTask<T>(int iterations, Func<ValueTask<T>> action) return the bytes one call allocates, after the same warmup and forced GC. The average is rounded up, so a call that allocates at all never reads as 0.
  • AllocationGate.AssertNoMoreThan(int iterations, Action baseline, Action candidate, string label) and AllocationGate.AssertNoMoreThanValueTask<T>(...) measure both paths in the same run. They throw if candidate allocates more in total than baseline. Use them for relative gates, such as "a DI-resolved client allocates no more than a hand-built one".

GeneratorSnapshot

Snapshot testing for source-generator output. The file format matches Verify.SourceGenerators, so existing *.verified.cs files are reused unchanged.

  • GeneratorSnapshot.Verify(GeneratorDriver driver) and GeneratorSnapshot.Verify(GeneratorDriverRunResult runResult) compare every generated source against {TestClass}.{TestMethod}#{hintName}.verified.cs. They fail on a mismatch, on a missing snapshot, and on a snapshot for output the generator no longer emits.
  • GeneratorSnapshot.VerifyText(string content, string extension = "txt") compares one string against {TestClass}.{TestMethod}.verified.{extension}.

Snapshots live in a Snapshots directory beside the test project's .csproj. The test name comes from the [Fact] or [Theory] method on the call stack, so calls routed through a shared helper still get per-test names. On a mismatch, a .received file is written next to the snapshot. Run the tests with ZA_SNAPSHOT_UPDATE=1 to accept the current output.

Why source-only

Test infrastructure should never appear on a consumer package's public API surface. By compiling into the consumer's assembly as internal, the helpers are scoped to each consumer and cost nothing at the consumer's runtime. GeneratorSnapshot also depends on this: [CallerFilePath] has to resolve to the consumer's test file.

Package probes

tests/PackageProbes/run.sh packs the package and builds two consumer projects against the nupkg. One has no Roslyn reference and uses only AllocationGate. The other references Roslyn and runs GeneratorSnapshot tests. CI runs it with --aot, which also publishes the first project with Native AOT.

There are no supported framework assets in this package.

Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.10.0 12,845 11/6/2026
1.9.0 1,907 10/30/2026
1.8.2 827 10/30/2026
1.8.1 429 10/29/2026
1.8.0 3,088 10/17/2026
1.7.3 2,968 10/17/2026
1.7.2 1,128 10/16/2026
1.7.1 901 10/15/2026
1.7.0 1,242 10/12/2026
1.6.2 606 10/12/2026
1.6.1 1,302 10/11/2026
1.6.0 1,972 10/10/2026
1.5.1 1,023 10/7/2026
1.5.0 534 10/2/2026
1.4.0 394 10/1/2026
1.3.3 3,837 9/24/2026
1.3.2 994 9/20/2026
1.3.1 416 9/20/2026
1.3.0 196 9/20/2026
1.2.3 3,804 9/19/2026
Loading failed