Unit Testing in C# with xUnit — The Complete Practical Guide

# Run these commands in your terminal to scaffold the solution

# 1. Create a solution folder
mkdir OrderProcessingApp && cd OrderProcessingApp

# 2. Create the production class library
dotnet new classlib -n OrderProcessing.Core

# 3. Create the xUnit test project
dotnet new xunit -n OrderProcessing.Tests

# 4. Create a solution file to hold both
dotnet new sln -n OrderProcessingApp

# 5. Add both projects to the solution
dotnet sln add OrderProcessing.Core/OrderProcessing.Core.csproj
dotnet sln add OrderProcessing.Tests/OrderProcessing.Tests.csproj

# 6. Reference the production project FROM the test project
dotnet add OrderProcessing.Tests/OrderProcessing.Tests.csproj \
  reference OrderProcessing.Core/OrderProcessing.Core.csproj

# Your folder structure should look like this:
# OrderProcessingApp/
# ├── OrderProcessingApp.sln
# ├── OrderProcessing.Core/          <-- production code
# │   ├── OrderProcessing.Core.csproj
# │   └── OrderCalculator.cs
# └── OrderProcessing.Tests/         <-- test code (separate project)
#     ├── OrderProcessing.Tests.csproj
#     └── OrderCalculatorTests.cs

# Run all tests from the solution root
dotnet test

// OrderProcessing.Core/OrderCalculator.cs — the class we are testing
namespace OrderProcessing.Core
{
    public class OrderCalculator
    {
        // Applies a percentage discount to the subtotal and returns the final price
        public decimal CalculateTotal(decimal subtotal, decimal discountPercent)
        {
            if (subtotal < 0)
                throw new ArgumentOutOfRangeException(nameof(subtotal), "Subtotal cannot be negative.");

            if (discountPercent < 0 || discountPercent > 100)
                throw new ArgumentOutOfRangeException(nameof(discountPercent), "Discount must be between 0 and 100.");

            var discountAmount = subtotal * (discountPercent / 100m);
            return subtotal - discountAmount;
        }

        // Returns true only if the order qualifies for free shipping
        public bool QualifiesForFreeShipping(decimal orderTotal, string customerTier)
        {
            return customerTier == "Gold" && orderTotal >= 50m
                || customerTier == "Standard" && orderTotal >= 100m;
        }
    }
}

// ─────────────────────────────────────────────────────────
// OrderProcessing.Tests/OrderCalculatorTests.cs
using Xunit;
using OrderProcessing.Core;

namespace OrderProcessing.Tests
{
    public class OrderCalculatorTests
    {
        // Create one instance of the calculator — it has no state, so it's safe to share
        private readonly OrderCalculator _calculator = new OrderCalculator();

        // ── [Fact] tests: single, unconditional scenarios ──

        [Fact]
        public void CalculateTotal_WhenSubtotalIsNegative_ThrowsArgumentOutOfRangeException()
        {
            // Arrange: a clearly invalid subtotal
            decimal negativeSubtotal = -10.00m;
            decimal validDiscount = 10m;

            // Act + Assert: xUnit's Assert.Throws captures the exception cleanly
            var exception = Assert.Throws<ArgumentOutOfRangeException>(
                () => _calculator.CalculateTotal(negativeSubtotal, validDiscount)
            );

            // Also verify the exception message mentions the right parameter name
            Assert.Equal("subtotal", exception.ParamName);
        }

        [Fact]
        public void CalculateTotal_WhenDiscountIsZero_ReturnFullSubtotal()
        {
            // Arrange
            decimal subtotal = 200.00m;
            decimal noDiscount = 0m;

            // Act
            decimal result = _calculator.CalculateTotal(subtotal, noDiscount);

            // Assert: no discount means we pay full price
            Assert.Equal(200.00m, result);
        }

        // ── [Theory] tests: same logic, many data sets ──

        [Theory]
        // Format: subtotal, discountPercent, expectedTotal
        [InlineData(100.00, 10,  90.00)]   // standard 10% off
        [InlineData(200.00, 25, 150.00)]   // 25% off a larger order
        [InlineData(50.00,  100,  0.00)]   // 100% off — free item promotion
        [InlineData(99.99,  0,   99.99)]   // zero discount — pay full price
        [InlineData(0.00,   50,   0.00)]   // zero subtotal — result must also be zero
        public void CalculateTotal_WithVariousDiscounts_ReturnsCorrectTotal(
            decimal subtotal,
            decimal discountPercent,
            decimal expectedTotal)
        {
            // Act: run the same logic for every [InlineData] row above
            decimal actualTotal = _calculator.CalculateTotal(subtotal, discountPercent);

            // Assert.Equal on decimals — xUnit compares value, not reference
            Assert.Equal(expectedTotal, actualTotal);
        }

        [Theory]
        [InlineData(50.00,  "Gold",     true)]   // Gold hits threshold of 50
        [InlineData(49.99,  "Gold",     false)]  // Gold just under threshold
        [InlineData(100.00, "Standard", true)]   // Standard hits threshold of 100
        [InlineData(99.99,  "Standard", false)]  // Standard just under threshold
        [InlineData(500.00, "Bronze",   false)]  // Unknown tier never qualifies
        public void QualifiesForFreeShipping_WithVariousTiersAndTotals_ReturnsExpected(
            decimal orderTotal,
            string customerTier,
            bool expectedResult)
        {
            bool actualResult = _calculator.QualifiesForFreeShipping(orderTotal, customerTier);
            Assert.Equal(expectedResult, actualResult);
        }
    }
}

// First, add Moq to the test project:
// dotnet add OrderProcessing.Tests package Moq

// ─── OrderProcessing.Core/IEmailService.cs ───
namespace OrderProcessing.Core
{
    public interface IEmailService
    {
        // Sends a confirmation to the given address and returns true on success
        bool SendOrderConfirmation(string recipientEmail, int orderId);
    }
}

// ─── OrderProcessing.Core/OrderService.cs ───
namespace OrderProcessing.Core
{
    public class OrderService
    {
        private readonly IEmailService _emailService;
        private readonly OrderCalculator _calculator;

        // Dependencies injected through constructor — this is what makes mocking possible
        public OrderService(IEmailService emailService, OrderCalculator calculator)
        {
            _emailService = emailService;
            _calculator = calculator;
        }

        // Places an order, calculates final price, and sends a confirmation email
        // Returns the final order total, or throws if email fails
        public decimal PlaceOrder(string customerEmail, decimal subtotal, decimal discountPercent)
        {
            if (string.IsNullOrWhiteSpace(customerEmail))
                throw new ArgumentException("Customer email is required.", nameof(customerEmail));

            decimal finalTotal = _calculator.CalculateTotal(subtotal, discountPercent);

            // Generate a deterministic order ID (simplified for the example)
            int orderId = Math.Abs(customerEmail.GetHashCode() % 100000);

            bool emailSent = _emailService.SendOrderConfirmation(customerEmail, orderId);

            if (!emailSent)
                throw new InvalidOperationException("Order confirmation email could not be sent.");

            return finalTotal;
        }
    }
}

// ─── OrderProcessing.Tests/OrderServiceTests.cs ───
using Xunit;
using Moq;
using OrderProcessing.Core;

namespace OrderProcessing.Tests
{
    public class OrderServiceTests
    {
        // Moq creates a fake IEmailService — no real emails, no SMTP server needed
        private readonly Mock<IEmailService> _mockEmailService;
        private readonly OrderService _orderService;

        public OrderServiceTests()
        {
            _mockEmailService = new Mock<IEmailService>();
            var calculator = new OrderCalculator(); // real calculator — no need to mock pure math

            // Inject the MOCK email service into OrderService
            _orderService = new OrderService(_mockEmailService.Object, calculator);
        }

        [Fact]
        public void PlaceOrder_WhenEmailSucceeds_ReturnsFinalTotal()
        {
            // Arrange: script the fake email service to succeed for ANY string and int
            _mockEmailService
                .Setup(emailSvc => emailSvc.SendOrderConfirmation(
                    It.IsAny<string>(),   // match any email address
                    It.IsAny<int>()))     // match any order ID
                .Returns(true);           // always say 'yes, email was sent'

            // Act: place a real order through the real OrderService
            decimal finalTotal = _orderService.PlaceOrder(
                customerEmail: "alice@example.com",
                subtotal: 150.00m,
                discountPercent: 10m
            );

            // Assert 1: the math came out right (10% off 150 = 135)
            Assert.Equal(135.00m, finalTotal);

            // Assert 2: verify the email service was called exactly once
            // This proves we didn't forget to send the confirmation
            _mockEmailService.Verify(
                emailSvc => emailSvc.SendOrderConfirmation(
                    "alice@example.com",   // must be this exact address
                    It.IsAny<int>()),      // any order ID is fine
                Times.Once()              // called exactly once — not zero, not twice
            );
        }

        [Fact]
        public void PlaceOrder_WhenEmailServiceFails_ThrowsInvalidOperationException()
        {
            // Arrange: script the fake email service to FAIL
            _mockEmailService
                .Setup(emailSvc => emailSvc.SendOrderConfirmation(
                    It.IsAny<string>(),
                    It.IsAny<int>()))
                .Returns(false); // simulate an SMTP outage

            // Act + Assert: placing the order should throw because email failed
            var exception = Assert.Throws<InvalidOperationException>(
                () => _orderService.PlaceOrder("bob@example.com", 200.00m, 0m)
            );

            Assert.Contains("confirmation email", exception.Message);
        }

        [Fact]
        public void PlaceOrder_WhenEmailIsEmpty_ThrowsArgumentException_BeforeCallingEmailService()
        {
            // Act + Assert: an empty email should fail immediately
            Assert.Throws<ArgumentException>(
                () => _orderService.PlaceOrder("", 100.00m, 0m)
            );

            // Verify the email service was NEVER called — we should have thrown before reaching it
            _mockEmailService.Verify(
                emailSvc => emailSvc.SendOrderConfirmation(
                    It.IsAny<string>(),
                    It.IsAny<int>()),
                Times.Never() // this line proves our guard clause fired correctly
            );
        }
    }
}

// dotnet add OrderProcessing.Tests package Microsoft.EntityFrameworkCore.InMemory

// ─── OrderProcessing.Core/Order.cs ───
namespace OrderProcessing.Core
{
    public class Order
    {
        public int Id { get; set; }
        public string CustomerEmail { get; set; } = string.Empty;
        public decimal Total { get; set; }
        public DateTime PlacedAt { get; set; }
    }
}

// ─── OrderProcessing.Core/AppDbContext.cs ───
using Microsoft.EntityFrameworkCore;

namespace OrderProcessing.Core
{
    public class AppDbContext : DbContext
    {
        public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }
        public DbSet<Order> Orders => Set<Order>();
    }
}

// ─── OrderProcessing.Tests/DatabaseFixture.cs ───
// This class is created ONCE and shared across all tests in OrderRepositoryTests
using Microsoft.EntityFrameworkCore;
using OrderProcessing.Core;

namespace OrderProcessing.Tests
{
    public class DatabaseFixture : IDisposable
    {
        public AppDbContext Context { get; }

        public DatabaseFixture()
        {
            // Build an in-memory database — fast, isolated, no file system needed
            var options = new DbContextOptionsBuilder<AppDbContext>()
                .UseInMemoryDatabase(databaseName: "OrderTests_" + Guid.NewGuid()) // unique name prevents bleed-over
                .Options;

            Context = new AppDbContext(options);

            // Seed with known data that tests can rely on
            Context.Orders.AddRange(
                new Order { Id = 1, CustomerEmail = "alice@example.com", Total = 99.99m, PlacedAt = DateTime.UtcNow },
                new Order { Id = 2, CustomerEmail = "bob@example.com",   Total = 249.00m, PlacedAt = DateTime.UtcNow }
            );
            Context.SaveChanges();
        }

        // Called automatically by xUnit after all tests in the class have run
        public void Dispose()
        {
            Context.Database.EnsureDeleted(); // clean up the in-memory database
            Context.Dispose();
        }
    }
}

// ─── OrderProcessing.Tests/OrderRepositoryTests.cs ───
using Xunit;
using OrderProcessing.Core;

namespace OrderProcessing.Tests
{
    // IClassFixture<DatabaseFixture> tells xUnit: create DatabaseFixture once, share it with all tests here
    public class OrderRepositoryTests : IClassFixture<DatabaseFixture>
    {
        private readonly AppDbContext _context;

        // xUnit injects the shared fixture through the constructor
        public OrderRepositoryTests(DatabaseFixture fixture)
        {
            _context = fixture.Context;
        }

        [Fact]
        public void GetOrder_WhenIdExists_ReturnsCorrectOrder()
        {
            // Act: query the seeded in-memory database
            var order = _context.Orders.Find(1);

            // Assert: the seeded data is exactly what we expect
            Assert.NotNull(order);
            Assert.Equal("alice@example.com", order.CustomerEmail);
            Assert.Equal(99.99m, order.Total);
        }

        [Fact]
        public void GetOrder_WhenIdDoesNotExist_ReturnsNull()
        {
            // Act: look for an order that was never seeded
            var order = _context.Orders.Find(999);

            // Assert: EF Core returns null for a missing key — not an exception
            Assert.Null(order);
        }

        [Fact]
        public void GetAllOrders_ReturnsExactlySeedCount()
        {
            // The fixture seeded exactly 2 orders
            int orderCount = _context.Orders.Count();
            Assert.Equal(2, orderCount);
        }
    }
}