ZeroAlloc.TestHelpers
1.6.2
See the version list below for details.
dotnet add package ZeroAlloc.TestHelpers --version 1.6.2
NuGet\Install-Package ZeroAlloc.TestHelpers -Version 1.6.2
<PackageReference Include="ZeroAlloc.TestHelpers" Version="1.6.2"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
<PackageVersion Include="ZeroAlloc.TestHelpers" Version="1.6.2" />
<PackageReference Include="ZeroAlloc.TestHelpers"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
paket add ZeroAlloc.TestHelpers --version 1.6.2
#r "nuget: ZeroAlloc.TestHelpers, 1.6.2"
#:package ZeroAlloc.TestHelpers@1.6.2
#addin nuget:?package=ZeroAlloc.TestHelpers&version=1.6.2
#tool nuget:?package=ZeroAlloc.TestHelpers&version=1.6.2
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 three 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 |
TextSnapshot.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 and TextSnapshot without pulling 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 forced GC and then a warmup. 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 forced GC and warmup. The average is rounded up, so a call that allocates at all never reads as 0.- The forced GC comes before the warmup, so a pool that a GC trims, such as
ArrayPool.Sharedunder high memory load, is refilled by the warmup and not by the measured calls. 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".
TextSnapshot
Snapshot testing for a string. It needs no Roslyn reference, so a plain test project can use it.
TextSnapshot.VerifyText(string content, string extension = "txt")compares one string against{TestClass}.{TestMethod}.verified.{extension}.
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")forwards toTextSnapshot.VerifyTextand is kept for existing callers.
Both write the same snapshots. 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.
Finding the test reads attributes off the methods on the stack, and trimming can remove that metadata. So the snapshot methods are marked [RequiresUnreferencedCode]. That matters only in a project with trim analysis on, and only where it calls them. TextSnapshot.cs still compiles cleanly into a Native AOT app that never calls it.
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 three consumer projects against the nupkg:
- an app with no Roslyn reference that uses only
AllocationGate; - a test project with no Roslyn reference that runs
TextSnapshottests; - a test project that references Roslyn and runs
GeneratorSnapshottests.
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 |