xUnit v3
E2E.XUnit.V3 holds E2E.XUnit.V3.E2ETest, an xUnit v3 base class. It implements IAsyncLifetime: InitializeAsync starts an engine session for each test, and DisposeAsync commits the replay cache from the xUnit result. The tests use the same App, Agent, Screen, and Expect as every framework. See Testing frameworks for how xUnit v3 compares with NUnit and TUnit.
xUnit v2 is not supported. It cannot read a test’s result during cleanup, and the replay cache needs that result.
Prerequisites
Section titled “Prerequisites”- The .NET 10 or 11 SDK.
- A model to sign in to, unless the tests never call the agent. See Before you start.
- An app to test. The example below runs against the live Dariten demo.
1. Create the test project
Section titled “1. Create the test project”Run e2e init MyApp.E2ETests --framework xunit to scaffold the project, an example test, and the config in one step. Or create it by hand. The package list is the one the repo’s own xUnit v3 sample uses, on the VSTest runner:
dotnet new console -n MyApp.E2ETestscd MyApp.E2ETestsdotnet add package Microsoft.NET.Test.Sdkdotnet add package xunit.v3.mtp-offdotnet add package xunit.runner.visualstudiodotnet add package E2Edotnet add package E2E.XUnit.V3xUnit v3 generates the program’s entry point, so delete the Program.cs the console template wrote. Then set the project properties:
<PropertyGroup> <OutputType>Exe</OutputType> <IsTestProject>true</IsTestProject> <!-- The session already stops on the xUnit cancellation token, so each call does not pass it. --> <NoWarn>$(NoWarn);xUnit1051</NoWarn></PropertyGroup>
<ItemGroup> <Using Include="E2E" /> <Using Include="Xunit" /></ItemGroup>xunit.v3.mtp-offkeeps the project on the VSTest runner, so the--filtercommands below work. The package needsxunit.v3.extensibility.core4.0.1 or later, whichE2E.XUnit.V3brings.xUnit1051is the analyzer warning that asks every async call to passTestContext.Current.CancellationToken. The session already stops on that token, so calls onApp,Screen,Agent,Browser, andExpect.Thatneed none. Turning the warning off avoids noise.E2Ein the implicit usings means tests need nousing E2E;.
2. Point at your app
Section titled “2. Point at your app”Put e2e.config.json next to the .csproj. Step 2 of Web has the file and the CopyToOutputDirectory item. For this example, use the Dariten target:
{ "targets": [{ "name": "dariten", "platform": "web", "app": { "url": "https://dariten.vercel.app" } }], "actionTimeout": 15000, "assertionTimeout": 10000, "agents": { "default": { "provider": "copilot", "model": "claude-sonnet-5.5", "context": "Dariten is a personal finance demo. Never add, edit, or delete data." } }, "cache": { "dir": ".e2e/cache" }}3. Write a test
Section titled “3. Write a test”Derive from E2ETest. Add a file named DaritenTests.cs:
using E2E.XUnit.V3;
namespace MyApp.E2ETests;
public sealed class DaritenTests : E2ETest{ [Fact] public async Task The_dashboard_links_to_the_transaction_register() { await App.OpenAsync("/"); await Expect.That(Screen.GetByRole("heading", "Dashboard")).ToBeVisibleAsync();
await Screen.GetByRole("link", "Transactions").ClickAsync();
await Expect.That(Screen.GetByRole("heading", "Transactions")).ToBeVisibleAsync(); }
[Fact] [Trait("TestCategory", "RealModel")] public async Task An_agent_filters_the_register_by_category() { await App.OpenAsync("/transactions");
await Agent.ActAsync("filter the register to show only the Groceries category");
await Agent.AssertAsync("every transaction listed is in the Groceries category, or the register says no transactions match"); await Expect.That(Screen.GetByRole("heading", "Transactions")).ToBeVisibleAsync(); }}The first test uses locators only, so it needs no model. The second calls a model, so it carries the TestCategory trait. Write one class per feature and one test per behavior. The longer version is samples/E2E.XUnit.V3.Sample.
4. Run
Section titled “4. Run”dotnet testdotnet test --filter "FullyQualifiedName~DaritenTests" # one classdotnet test --filter "TestCategory!=RealModel" # skip the model testsdotnet test --filter "TestCategory=RealModel" # only the model testsThe trait name is the filter name: [Trait("TestCategory", "RealModel")] is what TestCategory!=RealModel matches. Run from the project’s folder, or pass its path: dotnet test tests/MyApp.E2ETests. The first run asks the model to perform each ActAsync. A passing run records the steps a later check confirmed in .e2e/cache, and the next run replays them with no model call. See Caching and self-healing.
On Microsoft.Testing.Platform, --filter does not exist: use --filter-class or --filter-method. They match the full type name, so write dotnet test --filter-class "*.DaritenTests", not the bare name. Use --report-trx --report-trx-filename e2e.trx and --output Detailed in place of the --logger options. xUnit v3 also needs the TRX package: dotnet add package Microsoft.Testing.Extensions.TrxReport. How to turn MTP on.
5. xUnit v3 specifics
Section titled “5. xUnit v3 specifics”Hooks and their order
Section titled “Hooks and their order”- A constructor runs before the session exists, so do not use
ApporScreenthere. - To run code before or after each test, override
InitializeAsyncorDisposeAsyncand call the base method. Call it first inInitializeAsync. Call it last inDisposeAsync, inside afinally, so the session is always closed. - A check in
DisposeAsyncafter a failure verifies nothing, so it never lets a step be recorded. - The members are protected properties of the base class:
App,Agent,Screen,Browser,Secrets, andContext. - Override a virtual member to change one value for a class:
CreateEngine(),CreateModel(),CreateJudge(),CreateAgents(),BaseUrl,ActionTimeout,CacheMode, and more.
Attributes
Section titled “Attributes”[Fact]marks a test.[Theory]rows work too. Each row keeps its own replay, keyed by the class, the method, and every argument.- xUnit has no retry, so every test is a first attempt and can replay.
Assert.Skip(reason)orAssert.SkipWhen(condition, reason)skips a test from inside its body.
Parallelism
Section titled “Parallelism”The adapter adds no parallelism rule. Each test gets its own instance of the class and its own session.
Cancellation token
Section titled “Cancellation token”The session stops on xUnit’s token. Expect.Poll matchers do not see the session, so pass the token to ToSatisfyAsync or ToBeAsync, so a cancelled run stops them. Write Xunit.TestContext in full, because using E2E; brings in E2E.TestContext too.
Soft checks and polls
Section titled “Soft checks and polls”Expect.Soft keeps each failure on the session. The body runs on, and the test fails when it is disposed, with every failure in one message. There is no ToMatchAsync: Expect.Poll takes a predicate through ToSatisfyAsync, or a value through ToBeAsync.
[Fact]public async Task The_count_settles(){ await App.OpenAsync("/"); await Expect.Soft(Screen.GetByRole("heading", "Dashboard")).ToBeVisibleAsync(); await Expect.Soft(Screen.GetByText("Net worth")).ToBeVisibleAsync();
await Expect.Poll(() => ReadCountAsync()) .ToSatisfyAsync(count => count > 3, cancellationToken: Xunit.TestContext.Current.CancellationToken);}ReadCountAsync stands for your own method.
Saved sessions
Section titled “Saved sessions”Sign in once, then start other tests signed in. Mark the sign-in test [E2ESetup("title", Saves = ["admin"])] instead of [Fact]. Its body signs in, checks that it worked, and calls SaveSessionAsync("admin") once for each name in Saves. Mark a test or a class [E2ESession("admin")] to restore it before the body runs.
public sealed class Dashboard : E2ETest{ [E2ESetup("authenticate as admin", Saves = ["admin"])] public async Task Authenticate() { var admin = Credentials.User("admin"); await App.OpenAsync("/login"); await Screen.GetByLabel("Username").FillAsync(admin.Username); await Screen.GetByLabel("Password").FillAsync(admin.Password); await Screen.GetByRole("button", "Sign in").TapAsync(); await Expect.That(Browser).ToHaveURLAsync("/dashboard"); await SaveSessionAsync("admin"); }
[Fact] [E2ESession("admin")] public async Task Opens_the_dashboard_directly() { await App.OpenAsync("/dashboard"); }}E2ETestorders the setup tests of a class before its other tests, with a test method orderer. A class with its own[TestMethodOrderer]loses that. A test that restores a session nobody has saved yet runs the setup test that declares it first, once per run, so a dependent can run alone.- Exactly one setup test of the test assembly must declare the name. With none, or with two, the restore fails with
SESSION_UNAVAILABLE. A name saved twice, a name not inSaves, or a name inSavesthe body never saved fails the setup test withSESSION_CONTRACT. - A restore leaves no page open, so call
App.OpenAsyncfirst. A session holds what the browser keeps (cookies, local storage, IndexedDB), not server state. - A session lasts one run. It is encrypted with a key held in memory and kept under
.e2e/sessions/<run id>. The run fixture below deletes it when the run ends.
The run fixture
Section titled “The run fixture”Register E2ERunFixture as an assembly fixture. It stops the app commands your targets declare when the last test ends, calls the reporters of e2e.config.json, and deletes saved sessions:
using E2E.XUnit.V3;
[assembly: AssemblyFixture(typeof(E2ERunFixture))]To leave out the tests a change cannot affect, derive a fixture, override Filters (and ChangedSince), and register that type instead. E2ERunFixture is not sealed for this. You can also set E2E_CHANGED_SINCE=origin/main. A test a filter leaves out is skipped with the filter’s reason. See Test filters.
6. Mobile and Windows
Section titled “6. Mobile and Windows”Install the package for the platform in place of E2E.XUnit.V3, and derive from its base class:
dotnet add package E2E.Mobile.XUnit.V3 # MobileAppTest, in E2E.Mobile.XUnit.V3dotnet add package E2E.WinApp.XUnit.V3 # WinAppTest, in E2E.WinApp.XUnit.V3A left-out xUnit v3 mobile test is skipped before it makes the shared hosted engine. A Windows test needs an unlocked desktop with one window in the foreground at a time. The steps are on the Mobile, .NET MAUI, and Windows pages.