klod68/integration-testing-webapplicationfactory

---

name: integration-testing-webapplicationfactory description: "Use when writing integration tests for Razor Pages, MVC, or Minimal API applications to validate routing, middleware, page rendering, and HTTP behavior without a browser or live server, or when adding fast smoke tests to a CI pipeline. Covers WebApplicationFactory<Program> setup with public partial class Program, in-memory test server, AngleSharp HTML parsing, CSS selector assertions, redirect and status code testing, and a shared static fixture pattern for minimal per-test startup overhead. Domain: Testing, ASP.NET Core. Level: Intermediate. Tags: integration-testing, webapplicationfactory, razor-pages, anglesharp, http-testing."

Integration Testing with WebApplicationFactory

Problem

You need to test that your ASP.NET Core web application (Razor Pages, MVC, or Minimal API) works correctly end-to-end — HTTP pipeline, middleware, routing, page rendering — but without launching a browser or a real server.

Solution: In-Memory Server + HTML Parsing

Use WebApplicationFactory<Program> to spin up an in-memory test server, send HTTP requests via HttpClient, and parse HTML responses with AngleSharp. No browser, no ports, no flakiness.

Why This Over Browser E2E

| Aspect | WebApplicationFactory | Browser E2E (Playwright/Selenium) | |--------|----------------------|----------------------------------| | Speed | ~ms per test | ~seconds per test | | Stability | Deterministic | Flaky (timeouts, rendering) | | Setup | NuGet packages only | Browser install + drivers | | Scope | HTTP pipeline + HTML | Full rendering + JavaScript | | CI cost | Minimal | Heavy (headless browser) |

Use both: WebApplicationFactory for 80% of tests; browser E2E for JavaScript-dependent flows.

Implementation

1. Expose Program for the test host

In the web app's Program.cs, add at the bottom:

// Expose Program class for WebApplicationFactory in tests
public partial class Program { }

2. Create a shared fixture

using Microsoft.AspNetCore.Mvc.Testing;

/// <summary>
/// Shared WebApplicationFactory fixture. Created once, reused across all test classes.
/// </summary>
public static class WebAppFixture
{
    private static readonly WebApplicationFactory<Program> _factory = new();
    
    public static HttpClient Client { get; } = _factory.CreateClient(new WebApplicationFactoryClientOptions
    {
        AllowAutoRedirect = false  // Test redirects explicitly
    });
}

3. Create the base test class

using AngleSharp.Html.Dom;
using AngleSharp.Html.Parser;
using System.Net;

/// <summary>
/// Base class for integration tests. Provides HTTP + HTML parsing helpers.
/// </summary>
public abstract class IntegrationTestBase
{
    protected HttpClient Client => WebAppFixture.Client;
    protected IHtmlParser HtmlParser { get; } = new HtmlParser();

    /// <summary>
    /// GET a page and parse the HTML response.
    /// </summary>
    protected async Task<IHtmlDocument> GetPageAsync(string relativePath)
    {
        var response = await Client.GetAsync(relativePath);
        response.EnsureSuccessStatusCode();
        var content = await response.Content.ReadAsStringAsync();
        return (IHtmlDocument)await HtmlParser.ParseDocumentAsync(content);
    }

    /// <summary>
    /// Assert that a page returns HTTP 200.
    /// </summary>
    protected async Task AssertPageLoadsAsync(string relativePath)
    {
        var response = await Client.GetAsync(relativePath);
        Assert.AreEqual(HttpStatusCode.OK, response.StatusCode,
            $"Page {relativePath} returned {response.StatusCode}");
    }

    /// <summary>
    /// Assert that a page body contains specific text.
    /// </summary>
    protected async Task AssertPageContainsTextAsync(string relativePath, string expectedText)
    {
        var document = await GetPageAsync(relativePath);
        var bodyText = document.Body?.TextContent ?? string.Empty;
        Assert.IsTrue(bodyText.Contains(expectedText),
            $"Page {relativePath} does not contain '{expectedText}'");
    }

    /// <summary>
    /// Assert that a CSS selector matches at least one element.
    /// </summary>
    protected async Task AssertElementExistsAsync(string relativePath, string cssSelector)
    {
        var document = await GetPageAsync(relativePath);
        var element = document.QuerySelector(cssSelector);
        Assert.IsNotNull(element,
            $"Page {relativePath} has no element matching '{cssSelector}'");
    }

    /// <summary>
    /// Assert a page returns the expected status code (for error pages, redirects).
    /// </summary>
    protected async Task AssertStatusCodeAsync(string relativePath, HttpStatusCode expected)
    {
        var response = await Client.GetAsync(relativePath);
        Assert.AreEqual(expected, response.StatusCode);
    }
}

4. Write tests

[TestClass]
public class HomePageTests : IntegrationTestBase
{
    [TestMethod]
    public async Task HomePage_Returns200()
    {
        await AssertPageLoadsAsync("/");
    }

    [TestMethod]
    public async Task HomePage_ContainsSiteTitle()
    {
        await AssertPageContainsTextAsync("/", "My Application");
    }

    [TestMethod]
    public async Task HomePage_HasNavigationMenu()
    {
        await AssertElementExistsAsync("/", "nav");
    }

    [TestMethod]
    public async Task NotFoundPage_Returns404()
    {
        await AssertStatusCodeAsync("/nonexistent-page", HttpStatusCode.NotFound);
    }
}

5. Required packages (test project .csproj)

<ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.0" />
    <PackageReference Include="AngleSharp" Version="1.3.0" />
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.x.x" />
    <!-- Plus your test framework: MSTest, xUnit, or NUnit -->
</ItemGroup>

Common Assertion Patterns

| What to Test | Helper | Example | |-------------|--------|---------| | Page loads | AssertPageLoadsAsync | All pages return 200 | | Text content | AssertPageContainsTextAsync | Page has expected heading | | HTML structure | AssertElementExistsAsync | Page has <nav>, <footer> | | Status codes | AssertStatusCodeAsync | 404 for missing pages | | Redirect | Check Location header | Login redirects to dashboard | | API response | GetAsync + deserialize | JSON endpoint returns expected shape |

When to Use

• Testing Razor Pages, MVC, or Minimal API applications
• Validating routing, middleware, page rendering, and HTTP behavior
• Smoke tests in CI pipelines (fast, no infrastructure)
• Testing HTML structure without JavaScript

When NOT to Use

• JavaScript-heavy interactions (use Playwright/Selenium)
• Load testing or performance benchmarks
• Testing third-party service integrations (use contract tests)

Gotchas

1. public partial class Program { } is required — without it, WebApplicationFactory<Program> can't find the entry point.
2. AllowAutoRedirect = false is recommended — otherwise redirects are silently followed and you can't test redirect behavior.
3. AngleSharp doesn't execute JavaScript — it's an HTML parser, not a browser. CSS selectors and DOM traversal work; JavaScript-rendered content won't.
4. Shared fixture lifetime — create the factory once (static) to avoid spinning up a new server per test class. The overhead of repeated startup adds up quickly.
5. Environment: The test server defaults to Development. Override with _factory.WithWebHostBuilder(b => b.UseEnvironment("Production")) if needed.

Related Skills

• Test Category Taxonomy (categorize these as Integration)
• Health Check Endpoint (test the /health endpoint)