Xunit.StaFact

Run your xunit-based tests on an STA thread with the WPF Dispatcher, a WinForms or WinUI SynchronizationContext, or even a cross-platform generic UI thread emulation with a SynchronizationContext that keeps code running on a "main thread" for that test.

Simply use [WpfFact], [WinFormsFact], [WinUIFact], [StaFact] or the cross-platform [UIFact] on your test method to run your test under conditions that most closely match the main thread in your application.

Theory variants of these attributes allow for parameterized testing. Check out the xunit.combinatorial nuget package for pairwise or combinatorial testing with theories.

xUnit v2 vs. v3

With xUnit v3 now available with breaking changes from v2, see the following table for how we support both versions:

xUnit	Xunit.STAFact
For xUnit v2 support	Use Xunit.STAFact 1.x
For xUnit.v3 1.x support	Use Xunit.STAFact 2.0
For xUnit.v3 2.x support	Use Xunit.STAFact 2.1+
For xUnit.v3 3.x support	Use Xunit.STAFact 3.x
For xUnit.v3 4.x support	Use Xunit.STAFact 4.x

Features

The following test attributes are supported:

Xunit test attributes	Supported OS's	SynchronizationContext	STA thread?
[UIFact, UITheory]	All	Yes1	yes2
[WpfFact, WpfTheory]	Windows only3	DispatcherSynchronizationContext	yes
[WinFormsFact, WinFormsTheory]	Windows only3	WindowsFormsSynchronizationContext	yes
[WinUIFact, WinUITheory]	Windows 10 1809+4	DispatcherQueueSynchronizationContext	yes
[StaFact, StaTheory]	Windows only3	No	yes
[CocoaFact, CocoaTheory]	Mac OSX only3	Yes1	no

¹ This is a private SynchronizationContext that works cross-platform and effectively keeps code running on the test's starting thread the way a GUI application's main thread would do.

² STA thread only applies on Windows. On other operating systems, an MTA thread is used.

³ Windows-only attributes result in the test to result in "Skipped" on other operating systems.

⁴ WinUI attributes require a Windows-versioned target framework such as net8.0-windows10.0.17763.0.

We also offer a [UISettingsAttribute] that can be applied to individual test methods or test classes to control the behavior of the various UI test attributes. This attribute offers a means to add automated retries to a test's execution for unstable tests. Set MaxAttempts to the total number of attempts. Set Cultures to run each test independently under one or more cultures; each culture receives its own result, retry policy, display-name suffix, and Culture trait.

[WpfFact]
[UISettings(MaxAttempts = 3, Cultures = new[] { "en-US", "fr-FR" })]
public async Task LocalizedUiTest()
{
    Assert.Equal(CultureInfo.CurrentCulture, CultureInfo.CurrentUICulture);
}

Cultures applies both CultureInfo.CurrentCulture and CultureInfo.CurrentUICulture with user overrides disabled, and restores both after execution. A method-level setting overrides the corresponding class-level setting. Use xUnit's [CulturedFact] or [CulturedTheory] for ordinary tests; use UISettings.Cultures when combining cultures with Xunit.StaFact's custom thread or synchronization-context execution.

Samples

[UIFact] // or [WinFormsFact], [WpfFact], or [WinUIFact]
public async Task WpfFact_OnSTAThread()
{
    Assert.Equal(ApartmentState.STA, Thread.CurrentThread.GetApartmentState());
    int originalThread = Environment.CurrentManagedThreadId;
    await Task.Yield();
    Assert.Equal(originalThread, Environment.CurrentManagedThreadId); // still there
}

See more in our getting started doc.

Sponsorships

GitHub Sponsors

Zcash

Address: u1vv2ws6xhs72faugmlrasyeq298l05rrj6wfw8hr3r29y3czev5qt4ugp7kylz6suu04363ze92dfg8ftxf3237js0x9p5r82fgy47xkjnw75tqaevhfh0rnua72hurt22v3w3f7h8yt6mxaa0wpeeh9jcm359ww3rl6fj5ylqqv54uuwrs8q4gys9r3cxdm3yslsh3rt6p7wznzhky7