Testing an API

An API test starts your application, sends a real HTTP request to it, and asserts on the response. Status code, headers, body.

That is worth doing because a lot of an API is not your code. Routing decides which method runs. Model binding turns JSON into objects. Validation rejects bad input. Authorisation decides whether the request is allowed. Serialisation turns the result back into JSON. A unit test on the controller method skips every one of those, so it can pass while the endpoint returns 404, or 401, or a body with the wrong property names.

In ASP.NET Core the tooling for this is unusually direct: the application is hosted in the same process as the test, and you get an HttpClient wired to it. No port, no deployment, no separate build step.

using System.Net;
using System.Net.Http.Json;
using Microsoft.AspNetCore.Mvc.Testing;
using Xunit;

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

    public EmployeesEndpointTests(WebApplicationFactory<Program> factory) =>
        _client = factory.CreateClient();

    [Fact]
    public async Task GetEmployee_WhenTheEmployeeExists_ReturnsTheEmployee()
    {
        HttpResponseMessage response = await _client.GetAsync("/api/employees/1042");

        Assert.Equal(HttpStatusCode.OK, response.StatusCode);

        EmployeeResponse? employee = await response.Content.ReadFromJsonAsync<EmployeeResponse>();
        Assert.NotNull(employee);
        Assert.Equal(1042, employee!.EmployeeId);
        Assert.Equal("Sales Representative", employee.JobTitle);
    }
}

• WebApplicationFactory<Program> starts the application using its real startup code — the same registrations, middleware and endpoint mapping that run in production.
• Program is the top-level statements file. Because that generated class is internal, the test project cannot name it until you add public partial class Program { } at the end of Program.cs. That one line is the most common thing to miss on a first attempt.
• CreateClient returns an HttpClient that talks to the in-process application. There is no network and no port, so nothing to configure and nothing to clash with another test run.
• ReadFromJsonAsync deserialises using the same options the application configured. If a property name or casing does not round-trip, this is where you find out — a unit test on the controller returns a typed object and never serialises anything.
• Assert on the status code first and separately. If the endpoint returned 500, an assertion about the body fails with a deserialisation error that tells you nothing about the cause.

Failure paths break unnoticed, which is the reason to test them first. The happy path has a safety net: somebody uses the feature, sees the wrong thing, and reports it.

Failure paths have no such net. If an endpoint that should return 404 for an unknown employee starts returning 200 with an empty body, or an endpoint that should require a token starts allowing anonymous requests, nobody notices by using the application normally. The request that should have been refused just succeeds quietly.

These are also the paths most easily broken by a change somewhere else — a reordered middleware registration, a removed attribute, a filter that no longer runs. That combination, high risk and low visibility, is why an API suite should cover them at least as carefully as the success case.

[Fact]
public async Task GetEmployee_WhenNoTokenIsSupplied_ReturnsUnauthorised()
{
    // A client with no Authorization header at all
    HttpResponseMessage response = await _client.GetAsync("/api/employees/1042");

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

[Fact]
public async Task GetEmployee_WhenTheEmployeeDoesNotExist_ReturnsNotFound()
{
    HttpResponseMessage response = await _authorisedClient.GetAsync("/api/employees/999999");

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

[Fact]
public async Task CreateEmployee_WithABlankLastName_ReturnsBadRequestNamingTheField()
{
    var request = new { firstName = "Priya", lastName = "", jobTitle = "Sales Representative" };

    HttpResponseMessage response = await _authorisedClient.PostAsJsonAsync("/api/employees", request);

    Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);

    var problem = await response.Content.ReadFromJsonAsync<ValidationProblemDetails>();
    Assert.True(problem!.Errors.ContainsKey("lastName"));
}

• The first test is the cheapest security check in the suite. It asserts that the endpoint is not reachable without credentials, which is the kind of protection that disappears when somebody moves an [Authorize] attribute or reorders middleware.
• 404 rather than 200 matters to callers. A client that receives 200 with an empty body has to invent a rule for interpreting it, and the usual rule is a null reference somewhere further on.
• Asserting that the validation response names lastName is the difference between testing that it failed and testing that the caller can act on the failure. ValidationProblemDetails is the standard shape ASP.NET Core returns for model validation, so the assertion is about a contract rather than about wording.
• An anonymous object as the request body is deliberate. It lets the test send a blank last name that a strongly typed request record might not allow you to construct, and it keeps the test honest about sending raw JSON.
• The authorised client is a separate HttpClient with a token attached. Producing one usually means registering a test authentication handler on the factory so the test does not depend on a real identity provider being reachable.