Installation

Create a small API and a working integration test suite with the template. Run the commands in order:

Start from the template

The template creates a small ASP.NET Core API and a suite for it. The default starter needs the .NET 10 SDK.

dotnet new install ProtoTest.Templates
dotnet new prototest -n Shop
cd Shop
dotnet test

The run passes. The test project leaves Shop.Tests/bin/Debug/net10.0/TestResults/prototest-{runId}.prototrace and Shop.html. Each run writes its own trace, so a rerun never overwrites the previous one. Open the report for the run's verdict and the routes it covered, or drop the trace on trace.prototest.dev.

ProtoTest ships as small NuGet packages: your runner package, ProtoTest.Core, and one package per integration you use. The runner and integration packages target .NET 8, 9 and 10. ProtoTest.Cli targets .NET 8 only. ProtoTest.Analyzers and ProtoTest.Templates are netstandard2.0.

The suite is written for NUnit. Pass --runner xunit, --runner xunit3, --runner tunit or --runner mstest to generate it for another runner, and --framework net8.0 or --framework net9.0 to target an older framework.

What the template creates

Two projects, one setup file picked by the runner, and four order scenarios against a tiny API:

Shop/
├── Shop.slnx
├── global.json                    # xunit3 and tunit only: the Microsoft.Testing.Platform opt-in
├── README.md
├── Shop.Api/
│   ├── Shop.Api.csproj
│   ├── Program.cs                 # POST /api/orders, GET /api/orders/{id}, in-memory store
│   └── Orders.cs                  # NewOrder, Order, OrderStore
└── Shop.Tests/
    ├── Shop.Tests.csproj          # the runner package plus AspNetCore, Rest, Reporting
    ├── Setup.cs                   # hosts the API in-process, registers REST, tracing, the HTML report
    └── OrderTests.cs              # four tests: create, read back, validation, not found

Setup.cs starts as Setup.{runner}.cs and is renamed for the runner you picked. The test project always adds ProtoTest.AspNetCore, ProtoTest.Rest and ProtoTest.Reporting next to the runner package; TUnit also sets OutputType to Exe, as TUnit requires.

Flag	Values	Default
--runner	nunit, xunit, xunit3, tunit, mstest	nunit
--framework	net10.0, net9.0, net8.0	net10.0

Next: Your first test walks the same path one step at a time and ends at a failure and its trace.

Add ProtoTest to your own project

	Template (fastest)	Your own project (control)
Start with	dotnet new prototest -n Shop	the dotnet add package lines below
You get	a working API, suite, trace and report	ProtoTest inside a project you already have
Pick the other when	you already have an application or a suite	you want the composed example to copy from

A suite is one runner package, ProtoTest.Core, and one package per integration. Infrastructure hangs off the integration it serves:

your suite = runner (1 of 5) + Core + 1 package per integration
  runner:        ProtoTest.NUnit, .Xunit, .Xunit3, .MSTest, .TUnit (pick one)
  integrations:  Rest, GraphQL, Grpc, Data, Sql, Sheets, OpenApi, ...
  infrastructure: Sql.Testcontainers or Messaging.RabbitMq.Testcontainers,
                  next to the Sql or Messaging integration they serve

Pick one package per integration you use, plus infrastructure and extras where you need them:

terminal

dotnet add package ProtoTest.Core   # host, context, hooks, attributes, trace
dotnet add package ProtoTest.NUnit  # NUnit

The runner packages are ProtoTest.NUnit, ProtoTest.Xunit (v2), ProtoTest.Xunit3, ProtoTest.MSTest and ProtoTest.TUnit. Each one needs a small setup class; see Test runners.

The NUnit adapter needs NUnit 4.6.1 or newer; the standard dotnet new nunit template pins an older version, so update it first:

dotnet add package NUnit --version 4.6.1

Preview packages

The preview set works but its surface can change before the next minor release: Sheets, WireMock, the devices family, Aspire, the MassTransit bridge, the agent layer (Mcp, Diagnosis, Verification, Feedback, Cli) and Analyzers. Add one per need the same way:

dotnet add package ProtoTest.Sheets
dotnet add package ProtoTest.WireMock
dotnet add package ProtoTest.Aspire

What comes along

You add	You also get	Add it directly when you
any package	ProtoTest.Core	your code names Core types: a hook, an attribute, a context extension
ProtoTest.Rest, ProtoTest.GraphQL, ProtoTest.Grpc	ProtoTest.Http, ProtoTest.Json	you build on the shared HTTP layer or shape constraints without those integrations
ProtoTest.Sheets	ProtoTest.Json	you use shape constraints outside Sheets
ProtoTest.Web.Playwright, ProtoTest.Web.Selenium	ProtoTest.Web	you write a backend on the shared web layer
ProtoTest.Messaging.RabbitMq	ProtoTest.Messaging	you write an adapter on the messaging layer
ProtoTest.Sql.EntityFrameworkCore	ProtoTest.Sql	you use the per-test connection without EF Core
ProtoTest.Sql.Testcontainers, ProtoTest.Messaging.RabbitMq.Testcontainers	ProtoTest.Testcontainers	you write a container of your own
ProtoTest.OpenApi	ProtoTest.Rest	you call the REST layer the coverage reads

ProtoTest.Http is the shared HTTP client and authentication layer behind REST, GraphQL and gRPC. Application suites reference the integration, not the layer.

Browsers for Playwright

Set InstallBrowsers to download the browser before the first launch. A clean machine or CI runner then needs no extra install step. Which backend to pick is on Which backend.

Where to next

• Your first test: the first test, the first failure and the trace.
• The Learn track: the same start with a real sample and recorded traces.