xUnit.UserContext

xUnit.UserContext is an attribute based extension for xUnit that allows tests to run under the context of a given Windows user. Impersonation can be useful for running integration tests that use resources that require windows authentication, such as connecting to a database.

The aim of this library is to allow easy usage in xUnit tests with minimal code. This library utilises the wrapper library SimpleImpersonation to use the Win32 LogonUser API for Impersonation. Additionally, because storing credentials in code is not ideal, this library also supports retrieval of credentials stored using ASP.NET UserSecrets.

Notes

• 09/10/2023 - BREAKING CHANGE - Targeting .NET 6 SDK. Refactored UserContextTestInvoker class to invoke the test method with WindowsIdentity.RunImpersonatedAsync.

Installation

Using the dotnet cli:

dotnet add package xunit.usercontext

Usage

To use this library use a UserFact or UserTheory in place of Fact or Theory

UserFactAttribute

using Xunit.UserContext;
...
[UserFact("UserName", "Password")]
public void TestedMethodName_StateUnderTest_ExpectedBehavior()
{
    // Test case that uses resource restricted to a windows user
    // e.g. database connection using windows auth
}
...

UserTheoryAttribute

using Xunit.UserContext;
...
[UserTheory("TestUserSecretsId")]
[InlineData("TestValue")]
public void TestedMethodName_StateUnderTest_ExpectedBehavior(string value)
{
    // Test case that uses resource restricted to a windows user
    // e.g. database connection using windows auth
}
...

Attribute Constructors

Both UserFact and UserTheory follow the same constructor patterns, so the all the following overloads are applicable to both. Additionally, all constructors have the following optional parameters with default values.

• logonType - default value of Network. The type of logon operation to perform (as per the underlying API), this should be set according to your usage, more information on the different logon types is available here.
• displayNameOnTest - default value of true. If true, this appends the username to the test name in the following format (user: username)

Static Username and Password

[UserFact("UserName", "Password")]   
[UserTheory("UserName","Password")]

• username - windows username
• password - windows password

Static Username, Password and Domain

[UserFact("UserName", "Password","Domain")] 
[UserTheory("UserName","Password","Domain")]

• username - windows username
• password - windows password
• domain - windows domain

User Secrets Id

[UserFact("TestUserSecretsId")]
[UserTheory("TestUserSecretsId")]

• userSecretsId - user secrets id, used when setting secrets

To set the credentials for this option, use the dotnet cli to set the values. The library will read values for the following keys: Username,Password, and optionally Domain. Below is an example of setting these values:

dotnet user-secrets set "Username" MyUsername --id TestUserSecretsId
dotnet user-secrets set "Password" MyPassword --id TestUserSecretsId
dotnet user-secrets set "Domain" Domain --id TestUserSecretsId

Issues & Contributions

If you find a bug or have a feature request, please report them in this repository's issues section. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT

Acknowledgments

• xUnit
• SimpleImpersonation
• Ionicons