.NET xUnit Introduction

What is xUnit?

xUnit is a free, open-source, community-focused unit testing tool for .NET. It was created by the original inventor of NUnit v2, and has become one of the most popular testing frameworks in the .NET ecosystem. xUnit follows modern testing principles and is designed to be extensible, making it an excellent choice for developers at all skill levels.

In this guide, we'll explore how to get started with xUnit in your .NET projects and learn the fundamental concepts needed to write effective tests.

Why Use xUnit?

xUnit offers several advantages over other testing frameworks:

• Modern Design: Built from the ground up to support the latest .NET features
• Parallel Test Execution: Tests run in parallel by default, making test suites run faster
• Extensibility: Easy to extend with custom assertions and test patterns
• Active Community: Well-maintained with regular updates and extensive documentation
• Industry Adoption: Used by the .NET Core team for testing the .NET Core codebase itself

Getting Started with xUnit

Installation

To start using xUnit in your project, you'll need to install the required NuGet packages:

1. Open your test project in Visual Studio
2. Right-click on your project in Solution Explorer
3. Select "Manage NuGet Packages"
4. Search for and install:
   • xunit - The core xUnit framework
   • xunit.runner.visualstudio - For running tests in Visual Studio
   • Microsoft.NET.Test.Sdk - Required for test discovery

Alternatively, you can use the .NET CLI with these commands:

bash

dotnet add package xunit
dotnet add package xunit.runner.visualstudio
dotnet add package Microsoft.NET.Test.Sdk

Creating Your First Test

Let's create a simple test class to demonstrate xUnit basics:

csharp

using Xunit;

namespace MyProject.Tests
{
    public class CalculatorTests
    {
        [Fact]
        public void Add_TwoNumbers_ReturnsSum()
        {
            // Arrange
            var calculator = new Calculator();
            
            // Act
            int result = calculator.Add(5, 3);
            
            // Assert
            Assert.Equal(8, result);
        }
    }
}

Here's the simple Calculator class we're testing:

csharp

namespace MyProject
{
    public class Calculator
    {
        public int Add(int a, int b)
        {
            return a + b;
        }
    }
}

Understanding xUnit Basics

Test Attributes

xUnit uses attributes to identify test methods:

1. [Fact]: Marks a test method that always executes under the same conditions.

csharp

[Fact]
public void StringsCanBeCompared()
{
    Assert.Equal("Expected", "Expected");
}

2. [Theory]: Marks a test method that can execute with different sets of data.

csharp

[Theory]
[InlineData(1, 2, 3)]
[InlineData(5, 5, 10)]
[InlineData(-5, 5, 0)]
public void Add_MultipleInputs_ReturnsExpectedSum(int a, int b, int expected)
{
    var calculator = new Calculator();
    var result = calculator.Add(a, b);
    Assert.Equal(expected, result);
}

Common Assertions

xUnit provides various assertion methods for verifying test results:

Assertion	Purpose	Example
Assert.Equal	Verify equality	Assert.Equal(expected, actual)
Assert.NotEqual	Verify inequality	Assert.NotEqual(notExpected, actual)
Assert.True	Verify condition is true	Assert.True(value)
Assert.False	Verify condition is false	Assert.False(value)
Assert.Null	Verify object is null	Assert.Null(object)
Assert.NotNull	Verify object is not null	Assert.NotNull(object)
Assert.Contains	Verify collection contains item	Assert.Contains(item, collection)
Assert.Throws<T>	Verify code throws an exception	Assert.Throws<ArgumentException>(() => method())

Test Fixtures with Constructor and IDisposable

xUnit creates a new instance of the test class for each test, providing isolation between tests. You can use the constructor for setup code and implement IDisposable for cleanup:

csharp

public class DatabaseTests : IDisposable
{
    private readonly DatabaseConnection _connection;
    
    public DatabaseTests()
    {
        // Setup - runs before each test
        _connection = new DatabaseConnection("connection_string");
        _connection.Open();
    }
    
    public void Dispose()
    {
        // Cleanup - runs after each test
        _connection.Close();
    }
    
    [Fact]
    public void Database_InsertRecord_RecordExists()
    {
        // Test code using _connection
        // ...
    }
}

Practical Example: Testing a User Service

Let's create a more realistic example testing a user service class:

First, let's define our User model and IUserService interface:

csharp

public class User
{
    public int Id { get; set; }
    public string Username { get; set; }
    public string Email { get; set; }
}

public interface IUserService
{
    User GetById(int id);
    bool IsEmailValid(string email);
    void AddUser(User user);
}

Now we'll implement the service:

csharp

public class UserService : IUserService
{
    private readonly List<User> _users = new List<User>();

    public User GetById(int id)
    {
        return _users.FirstOrDefault(u => u.Id == id);
    }

    public bool IsEmailValid(string email)
    {
        if (string.IsNullOrWhiteSpace(email))
            return false;
            
        // Simple validation: contains @ and .
        return email.Contains('@') && email.Contains('.');
    }

    public void AddUser(User user)
    {
        if (user == null)
            throw new ArgumentNullException(nameof(user));
            
        if (string.IsNullOrWhiteSpace(user.Username))
            throw new ArgumentException("Username cannot be empty", nameof(user));
            
        if (!IsEmailValid(user.Email))
            throw new ArgumentException("Email is not valid", nameof(user));
            
        _users.Add(user);
    }
}

Now let's write tests for this service:

csharp

public class UserServiceTests
{
    private readonly UserService _userService;

    public UserServiceTests()
    {
        _userService = new UserService();
    }

    [Fact]
    public void GetById_NonExistingId_ReturnsNull()
    {
        // Arrange
        int nonExistingId = 999;
        
        // Act
        var result = _userService.GetById(nonExistingId);
        
        // Assert
        Assert.Null(result);
    }

    [Fact]
    public void AddUser_ValidUser_AddsToCollection()
    {
        // Arrange
        var user = new User 
        { 
            Id = 1, 
            Username = "testuser", 
            Email = "[email protected]" 
        };
        
        // Act
        _userService.AddUser(user);
        var retrievedUser = _userService.GetById(1);
        
        // Assert
        Assert.NotNull(retrievedUser);
        Assert.Equal("testuser", retrievedUser.Username);
    }

    [Fact]
    public void AddUser_NullUser_ThrowsArgumentNullException()
    {
        // Act & Assert
        Assert.Throws<ArgumentNullException>(() => _userService.AddUser(null));
    }

    [Theory]
    [InlineData("")]
    [InlineData(null)]
    [InlineData("invalid")]
    [InlineData("invalid@")]
    [InlineData("@invalid")]
    public void IsEmailValid_InvalidEmail_ReturnsFalse(string email)
    {
        // Act
        bool isValid = _userService.IsEmailValid(email);
        
        // Assert
        Assert.False(isValid);
    }

    [Theory]
    [InlineData("[email protected]")]
    [InlineData("[email protected]")]
    public void IsEmailValid_ValidEmail_ReturnsTrue(string email)
    {
        // Act
        bool isValid = _userService.IsEmailValid(email);
        
        // Assert
        Assert.True(isValid);
    }
}

Advanced xUnit Features

Shared Context with Class Fixtures

When multiple test methods need to share setup but creating that setup is expensive, use class fixtures:

csharp

// Define the fixture
public class DatabaseFixture : IDisposable
{
    public DatabaseConnection Connection { get; private set; }
    
    public DatabaseFixture()
    {
        Connection = new DatabaseConnection("connection_string");
        Connection.Open();
        // Initialize the database with test data
    }
    
    public void Dispose()
    {
        Connection.Close();
    }
}

// Use the fixture in test class
public class DatabaseTests : IClassFixture<DatabaseFixture>
{
    private readonly DatabaseFixture _fixture;
    
    public DatabaseTests(DatabaseFixture fixture)
    {
        _fixture = fixture;
    }
    
    [Fact]
    public void Test1()
    {
        // Use _fixture.Connection
    }
    
    [Fact]
    public void Test2()
    {
        // Use _fixture.Connection
    }
}

Collection Fixtures

Collection fixtures allow sharing context across multiple test classes:

csharp

// Define the collection
[CollectionDefinition("Database collection")]
public class DatabaseCollection : ICollectionFixture<DatabaseFixture>
{
    // This class is just a placeholder for the collection attribute
}

// Use the collection in multiple test classes
[Collection("Database collection")]
public class UserRepositoryTests
{
    private readonly DatabaseFixture _fixture;
    
    public UserRepositoryTests(DatabaseFixture fixture)
    {
        _fixture = fixture;
    }
    
    // Test methods...
}

[Collection("Database collection")]
public class ProductRepositoryTests
{
    private readonly DatabaseFixture _fixture;
    
    public ProductRepositoryTests(DatabaseFixture fixture)
    {
        _fixture = fixture;
    }
    
    // Test methods...
}

Output Helper

You can capture test output for logging and debugging using ITestOutputHelper:

csharp

public class LoggingTests
{
    private readonly ITestOutputHelper _output;
    
    public LoggingTests(ITestOutputHelper output)
    {
        _output = output;
    }
    
    [Fact]
    public void Test_WithLogging()
    {
        _output.WriteLine("Starting test");
        
        // Test code
        var result = 2 + 2;
        
        _output.WriteLine($"Result: {result}");
        Assert.Equal(4, result);
    }
}

Best Practices for xUnit Testing

1. Keep tests simple and focused: Each test should verify a single behavior
2. Use descriptive test names: Name tests according to what they're testing using a convention like Method_Scenario_ExpectedResult
3. Follow the AAA pattern: Arrange, Act, Assert
4. Use theories for data-driven tests: When testing the same behavior with different inputs
5. Isolate tests: Don't create tests that depend on each other
6. Avoid logic in tests: Tests should be straightforward without complex logic
7. Test exceptions properly: Use Assert.Throws<T> to verify exceptions
8. Keep test setup minimal: Only set up what's needed for the test
9. Use meaningful assertions: Make sure your assertions clearly communicate what's being tested

Summary

In this introduction to xUnit for .NET, we've covered:

• Setting up xUnit in a .NET project
• Creating basic tests with [Fact] and [Theory] attributes
• Using assertions to verify test outcomes
• Handling test setup and cleanup
• Implementing practical tests for a real-world service
• Working with advanced features like fixtures and output helpers
• Best practices for effective testing

xUnit provides a powerful framework for testing .NET applications, helping you ensure your code functions correctly and is resilient to changes. By incorporating unit tests into your development process, you can catch bugs early and build more reliable software.

Additional Resources

• xUnit Official Documentation
• Microsoft Docs: Unit Testing in .NET
• GitHub: xUnit Project

Exercises

1. Create a simple string utility class with methods for common string operations (reverse, capitalize, count words) and write xUnit tests for each method.

2. Implement a temperature conversion class that converts between Celsius, Fahrenheit, and Kelvin and test it using xUnit theories with multiple data points.

3. Write tests for an existing class in your project that currently lacks test coverage, focusing on edge cases and potential exceptions.

4. Create a mock object to test a class that depends on external services and write xUnit tests that verify the class interacts with the dependency correctly.