Testing an API

What callers depend on is not your handler method. It is the status code, the body shape, the headers and the behaviour of the whole pipeline — model binding, validation, authentication, authorisation, serialisation and error handling, in that order.

A unit test on a handler skips all of it. It can pass while the endpoint returns 415 because the content type was wrong, or 200 with a body in the wrong case, or 500 because the error handler was not registered. So the tests that protect an API send real HTTP requests through the real pipeline and assert on what comes back.

ASP.NET Core makes that inexpensive. WebApplicationFactory starts your application in memory, with your real routing, middleware and dependency injection, and hands you an HttpClient wired to it. No port, no deployment, and fast enough to run on every build.

public class EmployeeEndpointTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _app;

    public EmployeeEndpointTests(WebApplicationFactory<Program> app) => _app = app;

    [Fact]
    public async Task Create_returns_201_with_a_location_header()
    {
        var client = _app.CreateClient();
        client.DefaultRequestHeaders.Authorization = TestTokens.ForHrUser();

        var response = await client.PostAsJsonAsync("/api/employees", new
        {
            fullName = "Asha Menon",
            email = "asha.menon@example.com",
            departmentId = 3,
            startDate = "2024-04-17"
        });

        Assert.Equal(HttpStatusCode.Created, response.StatusCode);
        Assert.NotNull(response.Headers.Location);
    }

    [Fact]
    public async Task Create_without_a_token_returns_401()
    {
        var response = await _app.CreateClient()
            .PostAsJsonAsync("/api/employees", new { fullName = "Asha Menon" });

        Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
    }

    [Fact]
    public async Task Reading_another_employee_returns_403()
    {
        var client = _app.CreateClient();
        client.DefaultRequestHeaders.Authorization = TestTokens.ForEmployee(19);

        var response = await client.GetAsync("/api/employees/42");

        Assert.Equal(HttpStatusCode.Forbidden, response.StatusCode);
    }
}

• WebApplicationFactory<Program> needs Program to be reachable from the test project. In a top-level-statements application, adding InternalsVisibleTo for the test assembly, or a public partial class Program declaration, is the usual way.
• CreateClient gives an HttpClient that calls the application in memory. Every request goes through the real middleware, so anything the pipeline does to a request or response is exercised.
• The first test asserts the status and the Location header. Asserting only the status would miss a 201 that forgot to say where the new employee is.
• The second test sends no Authorization header. It is one of the most valuable tests in the file, because it is the one that fails if authentication is ever removed from that endpoint.
• The third is the ownership refusal from the previous lesson, expressed as a test. Employee 19 asking for employee 42 must be refused, and this assertion is what keeps that check from being dropped in a later refactor.
• TestTokens is a small helper producing tokens your test configuration accepts. Do not disable authentication in tests to make them easier — that removes the only automated check that it works.

The failure paths deserve the emphasis, because they are the ones that break silently. Your front end exercises the happy path continuously — every developer, every manual check, every demo. If a 200 response loses a field, someone notices within a day.

Nobody exercises the 403. It fires for a request a legitimate user does not make, so if it becomes a 500, or a 200, nothing visible changes. The API keeps working for everyone who is allowed, which is exactly the condition under which a gap can persist for months.

Validation behaves the same way. A form that no longer sends an empty field stops producing 400s, so a regression in the validation response goes unnoticed until a different consumer relies on it. The tests that assert refusals are the tests that hold these paths in place, and they cost very little to write once the factory is set up.