Skip to content

Testing frameworks

E2E for .NET runs inside your test framework. The framework finds the tests, runs them, and reports the result. E2E adds a base class that starts an engine session for each test and commits the replay cache from the test’s result.

Three frameworks are supported: NUnit, xUnit v3, and TUnit. xUnit v2 is not supported, because it cannot read a test’s result during cleanup and the replay cache needs that result. The test API is the same in all three: App, Agent, Screen, Browser, Secrets, Context, and the Expect and Credentials classes. What differs is the attributes, the hooks, and a few rules, listed below.

Every project references E2E and the adapter of its framework. The mobile and Windows packages hold a ready base class for a device or a desktop test, and they take the place of the web adapter in that project.

NUnit xUnit v3 TUnit
Web E2E.NUnit E2E.XUnit.V3 E2E.TUnit
Mobile E2E.Mobile.NUnit E2E.Mobile.XUnit.V3 E2E.Mobile.TUnit
Windows E2E.WinApp.NUnit E2E.WinApp.XUnit.V3 E2E.WinApp.TUnit
Base class E2E.NUnit.E2ETest E2E.XUnit.V3.E2ETest E2E.TUnit.E2ETest
Test attribute [Test], [TestCase] [Fact], [Theory] [Test], [Arguments]
Runner VSTest VSTest (xunit.v3.mtp-off) Microsoft.Testing.Platform
Project type Default <OutputType>Exe</OutputType> <OutputType>Exe</OutputType>
NUnit xUnit v3 TUnit
Instance of the class One per fixture, shared by its tests One per test One per test
Session starts The base class’s [SetUp] InitializeAsync A before-test hook
Cache commits The base class’s [TearDown] DisposeAsync An after-test hook
Your setup Your [SetUp] runs after the base class’s Override InitializeAsync and call the base first Your [Before(Test)] runs after the session starts
Your cleanup Your [TearDown] runs before the base class’s Override DisposeAsync and call the base last, in a finally Your [After(Test)] runs before the commit

In all three, a pass or a skip records the verified steps, a failure evicts the unverified ones, and a cancelled test leaves the cache alone. A check in your cleanup after a failure verifies nothing, so it never lets a step be recorded.

NUnit xUnit v3 TUnit
Retry [Retry(n)]. The first attempt can replay. Later attempts run live and still record. Each [Repeat] iteration is a first attempt. None. Every test is a first attempt. [Retry]. The first attempt can replay. Later attempts run live and still record.
Soft failures Expect.Soft records each failure on the NUnit result. The test fails when it ends, with every failure listed. A soft failure before Assert.Ignore(...) fails the test. The test fails when it is disposed, with every failure in one message. A soft failure before a skip fails the test. The test fails when its after-test hook runs, in one ASSERTION_FAILED. A soft failure before Skip.Test(...) fails the test.
Expect.Poll ToBeAsync, ToSatisfyAsync, and ToMatchAsync with any NUnit constraint ToBeAsync and ToSatisfyAsync ToBeAsync and ToSatisfyAsync
Cancellation ToMatchAsync takes an optional token The session stops on xUnit’s token. Pass Xunit.TestContext.Current.CancellationToken to a poll matcher. The session stops on the test’s token. Pass that token to a poll matcher.
Parallelism The tests of a fixture share one instance, so a fixture that runs its tests in parallel fails at setup unless it has [FixtureLifeCycle(LifeCycle.InstancePerTestCase)]. [Parallelizable(ParallelScope.Fixtures)] is fine. No rule beyond xUnit’s own. Each test has its own instance and session. TUnit runs tests in parallel. Put [NotInParallel] on a class that must not.
Skip from a body Assert.Ignore(reason) or Assume.That(...) Assert.Skip(reason) or Assert.SkipWhen(condition, reason) Skip.Test(reason)
Real-model tests [Category("RealModel")] [Trait("TestCategory", "RealModel")] [Category("RealModel")]
Skip them --filter "TestCategory!=RealModel" --filter "TestCategory!=RealModel" --treenode-filter "/*/*/*/*[Category!=RealModel]"

Sign in once, then start other tests signed in. Mark the sign-in test with [E2ESetup("title", Saves = ["admin"])] and the tests that need it with [E2ESession("admin")]. The attribute and the rules are the same in all three. Only where the setup attribute goes differs: it replaces [Test] in NUnit, replaces [Fact] in xUnit v3, and goes beside [Test] in TUnit, which does not let a library define a test attribute.

A setup test runs before the other tests of its class. NUnit gives it an early [Order], xUnit v3 orders it with a test method orderer that a class’s own [TestMethodOrderer] replaces, and TUnit gives it Priority.Critical. A test that restores a session nobody has saved yet runs the setup first, once per run. See Authentication for how a login becomes a session.

A run fixture stops the app commands your targets declare when the last test ends, calls the reporters of e2e.config.json, and carries the Filters, ChangedSince, and LastFailed selection from Test filters. It also deletes saved sessions when the run ends. Without it, none of that runs, and the app commands stop when the test process exits.

NUnit xUnit v3 TUnit
A [SetUpFixture] outside any namespace, derived from the abstract E2ERunFixture [assembly: AssemblyFixture(typeof(E2E.XUnit.V3.E2ERunFixture))], or your own derived class (it is not sealed) A public class with a public parameterless constructor, derived from E2ERunFixture. A test-session hook finds it, so nothing is registered.

dotnet test runs all three. Each page has the filter syntax for its framework, and TUnit needs a one-time opt-in on .NET 10 and later.

NUnit and xUnit v3 run on VSTest by default. TUnit runs on Microsoft.Testing.Platform (MTP). The options differ:

Need VSTest MTP
TRX file --logger "trx;LogFileName=e2e.trx" --report-trx --report-trx-filename e2e.trx
Detailed console output --logger "console;verbosity=detailed" --output Detailed
Pick a test --filter "FullyQualifiedName~Class" NUnit: the same --filter. xUnit v3: --filter-class "*.Class". TUnit: --treenode-filter

NUnit and xUnit v3 can run on MTP too. Add a global.json next to the solution:

{
"test": { "runner": "Microsoft.Testing.Platform" }
}

It applies to every test project under it, so a VSTest project fails with All projects must use that test runner. Then set up each project:

  • NUnit: set <OutputType>Exe</OutputType> and <EnableNUnitRunner>true</EnableNUnitRunner>, and use NUnit3TestAdapter 5.0 or later (6.3.0 worked on SDK 10 and 11; 5.0.0 worked on SDK 11 only).
  • xUnit v3: replace the xunit.v3.mtp-off package with xunit.v3.
  • TUnit: nothing more.

For --report-trx, NUnit and xUnit v3 also need dotnet add package Microsoft.Testing.Extensions.TrxReport, at or above the Microsoft.Testing.Platform version the runner brings. TUnit includes it. The .NET Conf 2026 talk “Bringing dotnet run, test, and watch to .NET MAUI” recommends MTP for the .NET 11 device test templates (dotnet new androidtest, iostest), so a MAUI project that uses them may already have it on.

Use the framework your team already uses. The test API and the replay cache do not change with it. Choose by what you need:

  • NUnit, for [Retry], [Repeat], and TestCase rows.
  • xUnit v3, when the rest of your solution uses xUnit.
  • TUnit, for parallel tests by default and Microsoft.Testing.Platform.

e2e init <directory> scaffolds a project in any of them: --framework nunit (the default), --framework xunit, or --framework tunit.