Skip to content

NUnit

E2E.NUnit holds E2E.NUnit.E2ETest, an NUnit base class. Its [SetUp] starts an engine session for each test, and its [TearDown] commits the replay cache from the NUnit result. The tests use the same App, Agent, Screen, and Expect as every framework. See Testing frameworks for how NUnit compares with xUnit v3 and TUnit.

  • 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.

Run e2e init MyApp.E2ETests to scaffold the project, an example test, and the config in one step. Or create it by hand:

Terminal window
dotnet new nunit -n MyApp.E2ETests
cd MyApp.E2ETests
dotnet add package E2E
dotnet add package E2E.NUnit
dotnet add package NUnit
dotnet add package NUnit3TestAdapter

E2E.NUnit needs NUnit 5, and the template pins an older NUnit. Without the NUnit line, restore fails with NU1605. The template already references NUnit.Analyzers, which you can keep.

Add E2E to the implicit usings, so tests need no using E2E;:

<ItemGroup>
<Using Include="E2E" />
<Using Include="NUnit.Framework" />
</ItemGroup>

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" }
}

Derive from E2ETest. Add a file named DaritenTests.cs:

using E2E.NUnit;
namespace MyApp.E2ETests;
public sealed class DaritenTests : E2ETest
{
[Test]
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();
}
[Test]
[Category("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 [Category("RealModel")]. Write one class per feature and one test per behavior. The longer version is samples/E2E.Sample.

Terminal window
dotnet test
dotnet test --filter "FullyQualifiedName~DaritenTests" # one class
dotnet test --filter "Name=The_dashboard_links_to_the_transaction_register"
dotnet test --filter "TestCategory!=RealModel" # skip the model tests
dotnet test --filter "TestCategory=RealModel" # only the model tests

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 works as above. Use --report-trx --report-trx-filename e2e.trx and --output Detailed in place of the --logger options. NUnit also needs the TRX package: dotnet add package Microsoft.Testing.Extensions.TrxReport. How to turn MTP on.

  • Your own [SetUp] runs after the base class’s, so App, Agent, and Screen are ready there.
  • Your own [TearDown] runs before the base class’s. A check there after 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, and Context.
  • Override a virtual member to change one value for a class: CreateEngine(), CreateModel(), CreateJudge(), CreateAgents(), BaseUrl, ActionTimeout, CacheMode, and more.
  • [Test] marks a test. [TestCase] rows work too.
  • [Retry(n)]: the first attempt can replay the cache. Later attempts run live and still record. Each [Repeat] iteration is a first attempt.
  • Assert.Ignore(reason) or Assume.That(...) skips a test from inside its body.

NUnit shares one fixture instance among its tests. A class with ParallelScope.Children or All fails at setup, because its tests would share one session. Add [FixtureLifeCycle(LifeCycle.InstancePerTestCase)] to it, or use [Parallelizable(ParallelScope.Fixtures)] to run fixtures in parallel.

Expect.Soft records each failure on the NUnit result, as inside Assert.EnterMultipleScope. The body runs on, and the test fails when it ends, with every failure listed.

Expect.Poll(read) retries a value. E2E.NUnit adds ToMatchAsync, which takes any NUnit constraint. ToBeAsync and ToSatisfyAsync(predicate) work too:

[Test]
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()).ToMatchAsync(Is.GreaterThan(3));
}

ReadCountAsync stands for your own method. ToMatchAsync and ToSatisfyAsync take an optional CancellationToken.

Sign in once, then start other tests signed in. Mark the sign-in test [E2ESetup("title", Saves = ["admin"])] instead of [Test]. 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");
}
[Test]
[E2ESession("admin")]
public async Task Opens_the_dashboard_directly()
{
await App.OpenAsync("/dashboard");
}
}
  • A setup test gets an early [Order], so it runs before the other tests of its fixture. 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 in Saves, or a name in Saves the body never saved fails the setup test with SESSION_CONTRACT.
  • A restore leaves no page open, so call App.OpenAsync first. 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.

Add a [SetUpFixture] outside any namespace. 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.NUnit;
[SetUpFixture]
public sealed class AppCommands : E2ERunFixture;

To leave out the tests a change cannot affect, override Filters and ChangedSince on the fixture, or set E2E_CHANGED_SINCE=origin/main. A test a filter leaves out is ignored with the filter’s reason. See Test filters.

Install the package for the platform in place of E2E.NUnit, and derive from its base class:

Terminal window
dotnet add package E2E.Mobile.NUnit # MobileAppTest, in E2E.Mobile.NUnit
dotnet add package E2E.WinApp.NUnit # WinAppTest, in E2E.WinApp.NUnit

MobileAppTest makes one shared engine for a hosted run in [OneTimeSetUp], and the run leases the device when the first test starts. For a Windows project, put [assembly: NonParallelizable] in the project, so one window is in the foreground at a time. The steps are on the Mobile, .NET MAUI, and Windows pages.