Testing with NUnit¶

dotnet test examples/Documentation/TestingFrameworks/NUnit/NUnitTests.csproj

namespace Refit.Documentation.TestingFrameworks;

/// <summary>A person, as returned by the little pretend API these tests call.</summary>
/// <param name="Id">The person's id.</param>
/// <param name="Name">The person's name.</param>
public sealed record Person(int Id, string Name);

namespace Refit.Documentation.TestingFrameworks;

/// <summary>
/// The API these tests pretend to call. Refit turns this interface into real HTTP calls; in these tests,
/// a stub handler intercepts every call instead of sending it over the network.
/// </summary>
public interface IPeopleApi
{
    /// <summary>Gets one person by id.</summary>
    /// <param name="id">The person's id.</param>
    /// <returns>The person the server sent back.</returns>
    [Get("/people/{id}")]
    Task<Person> GetPersonAsync(int id);

    /// <summary>Creates a person.</summary>
    /// <param name="person">The person to create.</param>
    /// <returns>The person the server saved.</returns>
    [Post("/people")]
    Task<Person> CreatePersonAsync([Body] Person person);

    /// <summary>Watches a live feed of people, one at a time, as they arrive.</summary>
    /// <param name="cancellationToken">Stops watching when cancelled.</param>
    /// <returns>Each person, as soon as the server sends them.</returns>
    [Get("/people/live")]
    IAsyncEnumerable<Person> WatchPeopleAsync(CancellationToken cancellationToken);

    /// <summary>Uploads a list of people, one per line, as JSON Lines.</summary>
    /// <param name="people">The people to upload.</param>
    /// <returns>A task that completes once the server has answered.</returns>
    [Post("/people/import")]
    Task ImportPeopleAsync([Body(BodySerializationMethod.JsonLines)] IEnumerable<Person> people);
}

using System.Text.Json;
using System.Text.Json.Serialization;

namespace Refit.Documentation.TestingFrameworks;

/// <summary>The JSON metadata for <see cref="Person"/>, generated at compile time instead of by reflection.</summary>
[JsonSourceGenerationOptions(JsonSerializerDefaults.Web)]
[JsonSerializable(typeof(Person))]
public sealed partial class PersonJsonContext : JsonSerializerContext;

using System.Text.Json;

namespace Refit.Documentation.TestingFrameworks;

/// <summary>Builds the <see cref="RefitSettings"/> every test uses, so JSON matches the generated <see cref="Person"/> metadata.</summary>
public static class TestSettings
{
    /// <summary>The JSON options every test shares, built once from the source-generated <see cref="Person"/> metadata.</summary>
    private static readonly JsonSerializerOptions Options = new(PersonJsonContext.Default.Options) { TypeInfoResolver = PersonJsonContext.Default };

    /// <summary>Creates settings that read and write <see cref="Person"/> using the source-generated metadata.</summary>
    /// <returns>Settings ready to pass to a generated client.</returns>
    public static RefitSettings Create() => new(new SystemTextJsonContentSerializer(Options));
}

// Problem: does my code correctly read back the person my API returns?
[Test]
public async Task GetPerson_ReturnsTheStubbedPerson()
{
    using StubHttp http = new()
    {
        { Route.Get("/people/{id}"), Reply.With(new Person(1, "Ada")) },
    };
    IPeopleApi api = http.CreateGeneratedClient<IPeopleApi>("https://api.example.com", TestSettings.Create());

    Person person = await api.GetPersonAsync(1);

    Assert.That(person.Name, Is.EqualTo("Ada"));
}

// Problem: did my app actually send the data I expected to the server?
[Test]
public async Task CreatePerson_SendsTheRightJsonBody()
{
    using StubHttp http = new()
    {
        { Route.Post("/people"), Reply.With(new Person(2, "Grace"), HttpStatusCode.Created) },
    };
    IPeopleApi api = http.CreateGeneratedClient<IPeopleApi>("https://api.example.com", TestSettings.Create());

    await api.CreatePersonAsync(new Person(2, "Grace"));

    Person? sentPerson = await http.LastRequestBodyAsync<Person>();
    Assert.That(sentPerson?.Name, Is.EqualTo("Grace"));
}

// Problem: my API can return 404 for a person who doesn't exist. Does my code notice?
[Test]
public void GetMissingPerson_ReturnsNotFound()
{
    using StubHttp http = new()
    {
        { Route.Get("/people/{id}"), Reply.Status(HttpStatusCode.NotFound) },
    };
    IPeopleApi api = http.CreateGeneratedClient<IPeopleApi>("https://api.example.com", TestSettings.Create());

    ApiException? error = Assert.ThrowsAsync<ApiException>(() => api.GetPersonAsync(99));

    Assert.That(error?.StatusCode, Is.EqualTo(HttpStatusCode.NotFound));
}

// Problem: how do I make sure a test actually called the API it set up?
[Test]
public void ForgottenApiCall_FailsVerification()
{
    using StubHttp http = new()
    {
        { Route.Get("/people/1"), Reply.Status(HttpStatusCode.OK) },
    };

    InvalidOperationException? error = Assert.Throws<InvalidOperationException>(http.VerifyAllCalled);

    Assert.That(error?.Message, Does.Contain("GET /people/1"));
}

// Problem: what happens when the server is slow? We can test that without really waiting.
[Test]
public async Task SlowServer_DelaysTheReplyWithoutWaiting()
{
    FakeTimeProvider clock = new();
    NetworkBehavior behavior = new()
    {
        Delay = TimeSpan.FromSeconds(2),
        Variance = 0,
        FailurePercent = 0, // turn off the default random jitter and random failures so the test is repeatable
    };
    using StubHttp http = new(behavior)
    {
        { Route.Get("/people/1"), Reply.Json("""{"id":1,"name":"Ada"}""") },
    };
    http.TimeProvider = clock;
    IPeopleApi api = http.CreateGeneratedClient<IPeopleApi>("https://api.example.com", TestSettings.Create());

    Task<Person> pendingPerson = api.GetPersonAsync(1);
    clock.Advance(TimeSpan.FromSeconds(1));
    Assert.That(pendingPerson.IsCompleted, Is.False); // Only one of the two simulated seconds has passed.

    clock.Advance(TimeSpan.FromSeconds(1));
    Person person = await pendingPerson;
    Assert.That(person.Name, Is.EqualTo("Ada"));
}

// Problem: what happens when the network just fails, not just returns an error status?
[Test]
public void BrokenNetwork_ThrowsAConnectionError()
{
    NetworkBehavior behavior = new()
    {
        Delay = TimeSpan.Zero,
        FailurePercent = 1, // 1.0 = every request fails (the value is a probability from 0 to 1)
        FailureFactory = static () => new HttpRequestException("Connection reset."),
    };
    using StubHttp http = new(behavior)
    {
        { Route.Get("/people/1"), Reply.Json("""{"id":1,"name":"Ada"}""") },
    };
    IPeopleApi api = http.CreateGeneratedClient<IPeopleApi>("https://api.example.com", TestSettings.Create());

    // Refit never lets a transport failure escape as the raw HttpRequestException: it wraps it in an
    // ApiRequestException, copying the original exception's message across.
    ApiRequestException? error = Assert.ThrowsAsync<ApiRequestException>(() => api.GetPersonAsync(1));

    Assert.That(error?.Message, Is.EqualTo("Connection reset."));
}

// Problem: can my code react to each item the moment it streams in, instead of waiting for everything?
[Test]
public async Task WatchPeople_SeesEachOneAsTheyArrive()
{
    StreamSource source = new(StreamingContentFormat.JsonLines);
    using StubHttp http = new() { { Route.Get("/people/live"), Reply.Stream(source) } };
    IPeopleApi api = http.CreateGeneratedClient<IPeopleApi>("https://api.example.com", TestSettings.Create());
    await using IAsyncEnumerator<Person> people = api.WatchPeopleAsync(CancellationToken.None).GetAsyncEnumerator();

    source.Release(new Person(1, "Ada"));
    Assert.That(await people.MoveNextAsync(), Is.True);
    Assert.That(people.Current.Name, Is.EqualTo("Ada"));

    ValueTask<bool> nextPerson = people.MoveNextAsync();
    Assert.That(nextPerson.IsCompleted, Is.False); // Grace has not arrived yet.

    source.Release(new Person(2, "Grace"));
    Assert.That(await nextPerson, Is.True);
    Assert.That(people.Current.Name, Is.EqualTo("Grace"));

    source.Complete();
}

// Problem: can the server start handling my upload before I've finished sending it?
[Test]
public async Task UploadPeople_ServerDoesNotWaitForTheWholeUpload()
{
    int peopleProducedSoFar = 0;

    IEnumerable<Person> ProducePeople()
    {
        peopleProducedSoFar++;
        yield return new(1, "Ada");
        peopleProducedSoFar++;
        yield return new(2, "Grace");
    }

    int producedWhenServerStartedReading = -1;
    string? uploadedJson = null;
    using StubHttp http = new()
    {
        {
            Route.Post("/people/import"),
            Reply.From(async (request, cancellationToken) =>
            {
                // RequestCapture.None (set below) means StubHttp never buffered the body ahead of
                // time, so this line genuinely runs before ProducePeople() has finished.
                producedWhenServerStartedReading = peopleProducedSoFar;
                uploadedJson = await request.Content!.ReadAsStringAsync(cancellationToken);
                return new HttpResponseMessage(HttpStatusCode.Accepted);
            })
        },
    };
    http.RequestCapture = RequestCapture.None;
    IPeopleApi api = http.CreateGeneratedClient<IPeopleApi>("https://api.example.com", TestSettings.Create());

    await api.ImportPeopleAsync(ProducePeople());

    Assert.That(producedWhenServerStartedReading, Is.EqualTo(0));
    Assert.That(uploadedJson, Does.Contain("Grace"));
}