Integration Testing. Частина 1: Теорія та WebApplicationFactory

Межа між unit і integration тестами

Протягом попередніх статей ми досліджували unit тести — ізольовані перевірки окремого класу чи методу, де всі зовнішні залежності замінені моками. Unit тести — швидкі, стабільні та дешеві. Але вони мають принципове обмеження: вони перевіряють компоненти ізольовано від одне одного.

Уявіть, що кожен музикант у оркестрі відмінно грає свою партію на репетиції соло. Але чи означає це, що оркестр звучатиме чудово разом? Не обов'язково — виникнуть питання темпу, взаємодії між інструментами, загальної динаміки, що неможливо перевірити окремо.

Саме тут з'являються інтеграційні тести: вони перевіряють як компоненти працюють разом. Вони відповідають на питання, на які unit тести відповісти не можуть:

• Чи правильно налаштований Dependency Injection Container? Чи мій сервіс взагалі резолвиться?
• Чи правильно маршрутизує ASP.NET мої ендпоінти? Чи /api/orders/{id} дійсно викликає правильний handler?
• Чи правильно серіалізується JSON відповідь? Чи поле createdAt відправляється у форматі ISO 8601?
• Чи коректно відпрацьовує middleware — авторизація, логування, обробка помилок?
• Чи правильно обробляються HTTP заголовки — Content-Type, Accept, Authorization?

Жоден з цих аспектів неможливо перевірити, тестуючи сервіси та репозиторії в ізоляції.

Чому конфігурація DI — це ризик

Одна з найпоширеніших помилок у .NET проєктах — реєстрація залежностей у Program.cs без тестування того, що ці реєстрації коректні. Розглянемо конкретний приклад провалу.

Розробник додає новий сервіс:

// OrderService тепер потребує нового IShippingCalculator
public class OrderService(IOrderRepository repo, IShippingCalculator shipping) { }

У Program.cs забуває зареєструвати IShippingCalculator. Unit тести для OrderService проходять — тому що там IShippingCalculator замокований. Але в runtime при першому запиті до /api/orders додаток падає з InvalidOperationException: Unable to resolve service for type 'IShippingCalculator'.

Це класична ситуація, яка трапляється щоразу, коли розробники покладаються виключно на unit тести. Інтеграційний тест, що просто надсилає GET запит до /api/orders, одразу виявив би цю проблему ще до деплою.

Практика показує, що "DI misconfiguration" — одна з найчастіших причин production помилок у .NET проєктах. І вона невидима для unit тестів.

Що тестують integration тести в ASP.NET

Коли ми кажемо "інтеграційний тест для ASP.NET Minimal API", ми маємо на увазі тест, що:

1. Піднімає весь ASP.NET додаток — зі всіма middleware, ендпоінтами, фільтрами, health checks.

2. Надсилає реальний HTTP запит — через HttpClient, який взаємодіє зі справжнім HTTP pipeline, а не напряму викликає метод.

3. Отримує HTTP відповідь і перевіряє:

• Status code (200 OK, 201 Created, 404 Not Found, 422 Unprocessable Entity)
• Заголовки (Content-Type, Location при redirect)
• Тіло відповіді (JSON десеріалізація і перевірка полів)

4. Але при цьому може замінити зовнішні залежності (база даних, email сервіс, платіжний шлюз) на тестові дублі або in-memory реалізації.

Ось що відрізняє integration тест від end-to-end тест: e2e тест піднімає реальний сервер з реальною базою і реальним email — integration тест замінює те, що не потрібно перевіряти.

WebApplicationFactory: архітектурне рішення Microsoft

До появи WebApplicationFactory у ASP.NET Core 2.1 розробники мали кілька незручних варіантів для integration тестів:

• Піднімати реальний HTTP сервер (Kestrel) на конкретному порту — проблеми з паралелізмом, конфліктами портів
• Тестувати через TestServer безпосередньо — громіздкий код
• Взагалі відмовитись від integration тестів

WebApplicationFactory<TEntryPoint> вирішила всі ці проблеми. Ключові рішення:

1. In-process тестовий сервер. Замість запуску реального HTTP сервера (Kestrel), WebApplicationFactory піднімає додаток у тому ж процесі, що і тест. Запити HTTP проходять через весь реальний pipeline, але без мережевих викликів — це значно швидше і без проблем з портами.

2. Повна ізоляція між тестами. Кожна фабрика — окрема ізольована інстанція додатку. Ніякого shared state між тест-класами.

3. Гнучка кастомізація. Через WithWebHostBuilder або ConfigureWebHost можна замінити будь-які сервіси, конфігурацію, middleware — не змінюючи production код.

4. TEntryPoint — клас-точка входу. Зазвичай це Program (з partial class trick) або будь-який клас у вашій сборці, що дозволяє знайти конфігурацію WebApplication.

Простіше кажучи, WebApplicationFactory - це спосіб запустити ваш ASP.NET-додаток у тесті так, ніби він уже працює, але без справжнього веб-сервера і без відкритого порту. Ви не викликаєте методи напряму і не підробляєте весь HTTP вручну. Ви просто надсилаєте реальний запит і дивитесь, як додаток на нього відповів.

Документація: WebApplicationFactory<TEntryPoint>

Підготовка Program.cs для тестів

Найпоширеніша помилка при першому знайомстві з WebApplicationFactory — помилка компіляції: Program не доступний з тестового проєкту.

Це відбувається тому, що у .NET 6+ Program.cs використовує top-level statements, і клас Program генерується як internal за замовчуванням. Тестовий проєкт зовні не бачить internal типи.

Рішення: public partial class Program

Документація: Program у Minimal API

// Весь код Minimal API налаштування...
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IOrderRepository, OrderRepository>();
// ... інше

var app = builder.Build();
app.MapGet("/api/orders", GetOrders);
// ... інші ендпоінти

app.Run();

// Ця одна строка робить Program доступним для тестів
public partial class Program { }

<ItemGroup>
  <InternalsVisibleTo Include="MyProject.Tests" />
  <!-- Також потрібно для Moq dynamic proxy -->
  <InternalsVisibleTo Include="DynamicProxyGenAssembly2" />
</ItemGroup>

// Program.cs
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IProductService, ProductService>();
builder.Services.AddScoped<IProductRepository, ProductRepository>();
builder.Services.AddDbContext<AppDbContext>(opts =>
    opts.UseNpgsql(builder.Configuration.GetConnectionString("Default")));

var app = builder.Build();

app.MapGet("/api/products", async (IProductService service) =>
{
    var products = await service.GetAllAsync();
    return Results.Ok(products);
});

app.MapGet("/api/products/{id:guid}", async (Guid id, IProductService service) =>
{
    var product = await service.GetByIdAsync(id);
    return product is null ? Results.NotFound() : Results.Ok(product);
});

app.MapPost("/api/products", async (CreateProductDto dto, IProductService service) =>
{
    var product = await service.CreateAsync(dto);
    return Results.Created($"/api/products/{product.Id}", product);
});

app.Run();
public partial class Program { }

// ProductEndpointsTests.cs
public class ProductEndpointsTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _factory;
    private readonly HttpClient _client;

    public ProductEndpointsTests(WebApplicationFactory<Program> factory)
    {
        _factory = factory;
        _client = factory.CreateClient();
    }

    [Fact]
    public async Task GetProducts_ReturnsOkWithEmptyList()
    {
        // Відправляємо реальний HTTP GET запит через весь ASP.NET pipeline
        var response = await _client.GetAsync("/api/products");

        // Перевіряємо HTTP статус
        response.StatusCode.Should().Be(HttpStatusCode.OK);

        // Перевіряємо Content-Type
        response.Content.Headers.ContentType?.MediaType
            .Should().Be("application/json");

        //Десеріалізуємо JSON тіло відповіді
        var products = await response.Content.ReadFromJsonAsync<List<ProductDto>>();
        products.Should().NotBeNull();
        products.Should().BeEmpty();
    }

    [Fact]
    public async Task GetProduct_ByNonExistentId_Returns404()
    {
        var nonExistentId = Guid.NewGuid();
        var response = await _client.GetAsync($"/api/products/{nonExistentId}");

        // Перевіряємо що Minimal API повертає 404 для відсутнього ресурсу
        response.StatusCode.Should().Be(HttpStatusCode.NotFound);
    }

    [Fact]
    public async Task CreateProduct_WithValidData_Returns201WithLocationHeader()
    {
        var dto = new CreateProductDto
        {
            Name = "MacBook Pro 16",
            Price = 85000m,
            Category = "Electronics"
        };

        var response = await _client.PostAsJsonAsync("/api/products", dto);

        // 201 Created — критично для REST API
        response.StatusCode.Should().Be(HttpStatusCode.Created);

        // Location header повинен вказувати на новий ресурс
        response.Headers.Location.Should().NotBeNull();
        response.Headers.Location!.ToString().Should().StartWith("/api/products/");

        // Десеріалізуємо та перевіряємо тіло відповіді
        var created = await response.Content.ReadFromJsonAsync<ProductDto>();
        created.Should().NotBeNull();
        created!.Name.Should().Be("MacBook Pro 16");
        created.Price.Should().Be(85000m);
        created.Id.Should().NotBeEmpty();
    }
}

Що відбувається при запуску цього тесту:

1. xUnit ініціалізує WebApplicationFactory<Program> один раз (завдяки IClassFixture)
2. Фабрика читає Program.cs і піднімає весь додаток — DI, middleware, ендпоінти
3. factory.CreateClient() повертає HttpClient підключений до TestServer
4. _client.GetAsync("/api/products") проходить через весь реальний ASP.NET pipeline:
   • Routing ( розпізнає маршрут /api/products)
   • DI (розраховує IProductService і його залежності)
   • Endpoint handler (викликається)
   • JSON serialization (відповідь серіалізується)
5. Ми отримуємо реальну HttpResponseMessage і перевіряємо її

Тут важливо помітити логіку: тест не знає нічого про внутрішню реалізацію сервісу, але він бачить результат роботи всього ланцюжка. Саме тому один такий тест може одразу зловити проблему, яка в unit-тестах виглядала б нормально, бо там були замокані всі залежності.

Підміна залежностей: ConfigureTestServices

Найважливіша можливість WebApplicationFactory — замінити production реєстрації на тестові. Це дозволяє уникнути реальної бази даних або зовнішніх сервісів у integration тестах.

Є кілька способів це зробити. Найчистіший — через WithWebHostBuilder:

WithWebHostBuilder зручний тоді, коли вам потрібно змінити тільки один або кілька сервісів для конкретного сценарію. Ідея проста: базовий хост лишається тим самим, але перед створенням клієнта ви вносите тестову правку в контейнер залежностей. Це краще, ніж намагатися змінювати production-код лише заради одного тесту.

Документація: ConfigureTestServices

public class ProductEndpointsTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HttpClient _client;

    public ProductEndpointsTests(WebApplicationFactory<Program> factory)
    {
        _client = factory.WithWebHostBuilder(builder =>
        {
            builder.ConfigureTestServices(services =>
            {
                // Видаляємо реальний DbContext
                var descriptor = services.SingleOrDefault(
                    d => d.ServiceType == typeof(DbContextOptions<AppDbContext>));
                if (descriptor != null)
                    services.Remove(descriptor);

                // Додаємо SQLite in-memory замість реального PostgreSQL
                services.AddDbContext<AppDbContext>(opts =>
                    opts.UseSqlite("Data Source=:memory:"));

                // Замінюємо реальний email сервіс на fake
                services.AddScoped<IEmailService, FakeEmailService>();

                // Замінюємо payment gateway на mock
                services.AddScoped<IPaymentGateway, FakePaymentGateway>();
            });
        })
        .CreateClient();
    }
}

::field{name="UseEnvironment("Testing")" type="method"} Перемикає додаток у тестове середовище, щоб production-branching міг поводитися інакше. ::

// TestWebApplicationFactory.cs
public class TestWebApplicationFactory : WebApplicationFactory<Program>
{
    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        // Встановлюємо тестове середовище — впливає на конфігурацію та middleware
        builder.UseEnvironment("Testing");

        builder.ConfigureTestServices(services =>
        {
            // Замінюємо DbContext
            ReplaceDbContext(services);

            // Реєструємо fake сервіси
            services.AddScoped<IEmailService, FakeEmailService>();
            services.AddScoped<IPaymentGateway, FakePaymentGateway>();
            services.AddScoped<IExternalShippingApi, FakeShippingApi>();

            // Додаємо тестову аутентифікацію (про це нижче)
            services.AddAuthentication("Test")
                .AddScheme<AuthenticationSchemeOptions, TestAuthHandler>(
                    "Test", options => { });
        });
    }

    private static void ReplaceDbContext(IServiceCollection services)
    {
        // Видаляємо всі реєстрації, пов'язані з реальним DbContext
        var descriptorsToRemove = services
            .Where(d => d.ServiceType == typeof(DbContextOptions<AppDbContext>)
                     || d.ServiceType == typeof(AppDbContext))
            .ToList();

        foreach (var descriptor in descriptorsToRemove)
            services.Remove(descriptor);

        // Додаємо SQLite in-memory
        services.AddDbContext<AppDbContext>(opts =>
            opts.UseSqlite("Data Source=testdb;Mode=Memory;Cache=Shared"));
    }

    // Ініціалізація схеми та seed даних
    protected override void Dispose(bool disposing)
    {
        base.Dispose(disposing);
        // Очистка ресурсів після всіх тестів
    }
}

// Тест-клас використовує кастомну фабрику
public class ProductEndpointsTests : IClassFixture<TestWebApplicationFactory>
{
    private readonly TestWebApplicationFactory _factory;
    private readonly HttpClient _client;

    public ProductEndpointsTests(TestWebApplicationFactory factory)
    {
        _factory = factory;
        _client = factory.CreateClient();
    }
    // ...
}

Ініціалізація тестових даних

Проблема: перш ніж тестувати GET /api/products/{id}, потрібно мати продукт у базі. Є кілька підходів.

Підхід 1: Через HTTP API (реалістичний)

[Fact]
public async Task GetProduct_AfterCreation_ReturnsCorrectData()
{
    // Arrange: спочатку створюємо через API
    var createDto = new CreateProductDto { Name = "Test Product", Price = 100m };
    var createResponse = await _client.PostAsJsonAsync("/api/products", createDto);
    createResponse.EnsureSuccessStatusCode();

    var created = await createResponse.Content.ReadFromJsonAsync<ProductDto>();
    var productId = created!.Id;

    // Act: тепер читаємо
    var getResponse = await _client.GetAsync($"/api/products/{productId}");

    // Assert
    getResponse.StatusCode.Should().Be(HttpStatusCode.OK);
    var product = await getResponse.Content.ReadFromJsonAsync<ProductDto>();
    product!.Name.Should().Be("Test Product");
}

Підхід 2: Через DbContext напряму (швидший)

[Fact]
public async Task GetProduct_WithSeededData_ReturnsCorrectData()
{
    // Arrange: seed через DbContext з DI container
    using var scope = _factory.Services.CreateScope();
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();

    var product = new Product
    {
        Id = Guid.NewGuid(),
        Name = "Seeded Product",
        Price = 500m
    };
    db.Products.Add(product);
    await db.SaveChangesAsync();

    // Act
    var response = await _client.GetAsync($"/api/products/{product.Id}");

    // Assert
    response.StatusCode.Should().Be(HttpStatusCode.OK);
    var dto = await response.Content.ReadFromJsonAsync<ProductDto>();
    dto!.Name.Should().Be("Seeded Product");
}

Другий підхід значно швидший, але тестує лише GET endpoint. Перший підхід тестує весь цикл — POST і GET разом. Обидва правомірні залежно від мети тесту.

Тестування аутентифікації та авторизації

Одна з найскладніших частин integration тестів — перевірка захищених ендпоінтів. Реальна JWT-аутентифікація потребує реального токену, що ускладнює тести.

Рішення — TestAuthHandler: власна тестова схема аутентифікації, яку ми свідомо створюємо в тестовому проєкті та реєструємо через DI. Важливо підкреслити, що це не вбудований клас ASP.NET Core і не частина production-коду. Це лише тестова реалізація контракту аутентифікації, яка дозволяє контрольовано підставити користувача без JWT, cookies або зовнішнього identity provider.

У термінах ASP.NET Core AuthenticationHandler є конкретним обробником для певної схеми аутентифікації. Схема має назву, наприклад "Test", а handler відповідає за те, як саме визначити, чи є запит аутентифікованим. У нашому випадку рішення просте: якщо у запиті є спеціальний заголовок, ми вважаємо користувача валідним і повертаємо ClaimsPrincipal. Якщо заголовка немає, повертаємо NoResult(), і далі запит поводиться як anonymous.

Хто викликає цей handler? Не тест напряму, а сам ASP.NET pipeline. Коли запит проходить через UseAuthentication() та UseAuthorization(), фреймворк звертається до зареєстрованої схеми, а та, у свою чергу, делегує роботу нашому TestAuthHandler. Саме тому такий підхід є “нативним” для ASP.NET Core: ми не обходимо систему, а підміняємо лише механізм отримання користувача.

Назва схеми, наприклад "Test", є проектною домовленістю. Фреймворк не вимагає саме такого імені, але воно має бути однаково використане в AddAuthentication("Test"), у реєстрації handler-а та в місцях, де ви створюєте клієнт для тесту. Сам клас також може мати будь-яку назву, наприклад TestAuthHandler або LimitedTestAuthHandler; важливо не ім'я, а відповідність між реєстрацією і фактичною поведінкою.

Ідея тут не в тому, щоб перевіряти реальний провайдер ідентичності. Навпаки, ми хочемо прибрати зовнішній шум: токени, refresh flow, підписування, expiration, зовнішній identity provider. Для integration тесту нам зазвичай важливо лише одне - чи додаток правильно реагує на вже аутентифікованого користувача з певними claims і ролями.

Документація: TestAuthHandler

// TestAuthHandler.cs
public class TestAuthHandler : AuthenticationHandler<AuthenticationSchemeOptions>
{
    public const string TestUserId = "test-user-001";
    public const string AuthHeaderName = "X-Test-Auth";

    public TestAuthHandler(
        IOptionsMonitor<AuthenticationSchemeOptions> options,
        ILoggerFactory logger,
        UrlEncoder encoder)
        : base(options, logger, encoder) { }

    protected override Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        // Аутентифікуємо лише якщо є спеціальний тестовий заголовок
        if (!Request.Headers.ContainsKey(AuthHeaderName))
            return Task.FromResult(AuthenticateResult.NoResult());

        var userId = Request.Headers[AuthHeaderName].ToString();

        // Створюємо ClaimsPrincipal з потрібними ролями та claims
        var claims = new[]
        {
            new Claim(ClaimTypes.NameIdentifier, userId),
            new Claim(ClaimTypes.Name, "Test User"),
            new Claim(ClaimTypes.Role, "Admin"),
            new Claim(ClaimTypes.Role, "User"),
        };

        var identity = new ClaimsIdentity(claims, "Test");
        var principal = new ClaimsPrincipal(identity);
        var ticket = new AuthenticationTicket(principal, "Test");

        return Task.FromResult(AuthenticateResult.Success(ticket));
    }
}

У практиці цей клас використовується як тестовий substitute для ролей і політик доступу. Наприклад, один handler може створювати адміністратора, інший - звичайного користувача, третій - анонімний запит. Це дає змогу окремо перевіряти authentication і authorization без залучення реального сервера авторизації.

Тепер у тестах ми просто додаємо заголовок:

У практиці це зручно, бо ви одним заголовком керуєте “особою” користувача у тесті. Якщо заголовка немає - запит anonymous. Якщо заголовок є - handler створює ClaimsPrincipal, і далі вже спрацьовують ваші правила авторизації, policies та roles.

[Fact]
public async Task GetOrder_AuthenticatedUser_ReturnsOwnOrders()
{
    // Authenticate як конкретний юзер
    _client.DefaultRequestHeaders.Add("X-Test-Auth", "user-123");

    var response = await _client.GetAsync("/api/orders");

    response.StatusCode.Should().Be(HttpStatusCode.OK);
}

[Fact]
public async Task GetOrder_UnauthenticatedUser_Returns401()
{
    // БЕЗ заголовку — не аутентифікований
    var response = await _client.GetAsync("/api/orders");

    response.StatusCode.Should().Be(HttpStatusCode.Unauthorized);
}

[Fact]
public async Task DeleteOrder_NonAdminUser_Returns403()
{
    // Аутентифікований, але без Admin ролі
    var limitedClient = _factory.WithWebHostBuilder(builder =>
    {
        builder.ConfigureTestServices(services =>
        {
            // Замінюємо auth handler на один без Admin ролі
            services.AddAuthentication("Test")
                .AddScheme<AuthenticationSchemeOptions, LimitedTestAuthHandler>(
                    "Test", o => { });
        });
    }).CreateClient();

    limitedClient.DefaultRequestHeaders.Add("X-Test-Auth", "regular-user");

    var response = await limitedClient.DeleteAsync($"/api/orders/{Guid.NewGuid()}");
    response.StatusCode.Should().Be(HttpStatusCode.Forbidden);
}

Scope та параллелізм: важливі нюанси

Оскільки xUnit виконує тест-класи паралельно за замовчуванням, а тести в одному класі послідовно — необхідно правильно розуміти ізоляцію даних.

Проблема: якщо два тест-класи поділяють одну WebApplicationFactory через IClassFixture<TestWebApplicationFactory>, але фабрика є IClassFixture (прив'язана до класу), то кожен клас отримує власну інстанцію фабрики — проблем немає.

Але якщо використовується ICollectionFixture — один екземпляр фабрики на кілька класів. Тоді спільна база даних стає проблемою паралелізму.

У цьому місці важлива не тільки xUnit-деталь, а й життєвий цикл даних. Тестова БД має бути передбачуваною: якщо один тест записав дані, інший не повинен раптово на них натрапити, якщо це не було задумано. Інакше тести стають крихкими й починають падати не через код, а через порядок запуску.

Рішення для паралельних integration тестів:

// Варіант 1: Унікальна база для кожного тест-класу
public class ProductTests : IClassFixture<TestWebApplicationFactory>
{
    public ProductTests(TestWebApplicationFactory factory)
    {
        // Кожен запуск фабрики = своя SQLite in-memory база
        // SQLite "Data Source=:memory:" при кожній новій factory дає ізольовану базу
    }
}

// Варіант 2: Reset даних перед кожним тестом у класі
public class OrderTests : IClassFixture<TestWebApplicationFactory>
{
    private readonly TestWebApplicationFactory _factory;

    public OrderTests(TestWebApplicationFactory factory)
    {
        _factory = factory;
        // Очищаємо дані через DI
        ResetDatabase();
    }

    private void ResetDatabase()
    {
        using var scope = _factory.Services.CreateScope();
        var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
        db.Orders.RemoveRange(db.Orders);
        db.SaveChanges();
    }
}

Практичні завдання

Підсумок