ZeroAlloc.TestHelpers
1.4.0
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
<PackageReference Include="ZeroAlloc.TestHelpers" Version="1.4.0"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
<PackageVersion Include="ZeroAlloc.TestHelpers" Version="1.4.0" />
<PackageReference Include="ZeroAlloc.TestHelpers"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
paket add ZeroAlloc.TestHelpers --version 1.4.0
#r "nuget: ZeroAlloc.TestHelpers, 1.4.0"
#:package ZeroAlloc.TestHelpers@1.4.0
#addin nuget:?package=ZeroAlloc.TestHelpers&version=1.4.0
#tool nuget:?package=ZeroAlloc.TestHelpers&version=1.4.0
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)runsactioniterationstimes after a warmup and a forced GC. It throwsInvalidOperationExceptionif total allocations exceedbudgetBytes * iterations.AllocationGate.AssertBudgetValueTask<T>(int budgetBytes, int iterations, Func<ValueTask<T>> action, string label)is the same check for APIs that returnValueTask<T>. It throws if the suppliedValueTask<T>did not complete synchronously, because awaiter machinery would pollute the measurement.AllocationGate.MeasureBytesPerCall(int iterations, Action action)andAllocationGate.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)andAllocationGate.AssertNoMoreThanValueTask<T>(...)measure both paths in the same run. They throw ifcandidateallocates more in total thanbaseline. 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)andGeneratorSnapshot.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.
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 |