Fluent.Client.AwesomeAssertions 1.1.0

<div align="center"> <h1>🧪 Fluent.Client.AwesomeAssertions</h1> <h3><em>Write expressive HTTP assertions for .NET integration tests.</em></h3> </div>

<p align="center"> <strong>A fluent assertion library for <code>Task<HttpResponseMessage></code> that makes your HTTP tests readable, maintainable, and delightful to write.</strong> </p>

<p align="center"> <a href="https://www.nuget.org/packages/Fluent.Client.AwesomeAssertions"><img src="https://img.shields.io/nuget/v/Fluent.Client.AwesomeAssertions.svg" alt="NuGet"/></a> <a href="https://www.nuget.org/packages/Fluent.Client.AwesomeAssertions"><img src="https://img.shields.io/nuget/dt/Fluent.Client.AwesomeAssertions.svg" alt="NuGet Downloads"/></a> <a href="https://github.com/lepoco/fluent/stargazers"><img src="https://img.shields.io/github/stars/lepoco/fluent?style=social" alt="GitHub stars"/></a> <a href="https://github.com/lepoco/fluent/blob/main/LICENSE"><img src="https://img.shields.io/github/license/lepoco/fluent" alt="License"/></a> </p>

<p align="center"> <a href="https://lepo.co/">Created in Poland by Leszek Pomianowski</a> and <a href="https://github.com/lepoco/fluent/graphs/contributors">open-source community</a>. </p>

Table of Contents

• Table of Contents
• 🤔 Why This Library?
• ⚡ Get Started
  • 1. Install the Package
  • 2. (Optional) Add Fluent.Client
  • 3. Start Writing Tests
• 📖 How to Use
  • 1. Assert Success
  • 2. Assert Specific Status Code
    • Quick Reference
  • 3. Assert Failure
  • 4. Assert Body Content
  • 5. Authorization with Query Parameters
    • Bearer Token Authorization
    • Basic Authentication
    • Authorization Methods
• 🧪 Integration Testing
  • Key Patterns
• 📚 API Reference
  • Assertion Methods
  • JSON Serialization
• 👥 Maintainers
• 💬 Support
• 🙏 Acknowledgements
• 📄 License

🤔 Why This Library?

Traditional HTTP testing in .NET is verbose and hard to read:

// ❌ Traditional approach - verbose and unclear intent
var response = await client.PostAsync("/api/users", content);
Assert.True(response.IsSuccessStatusCode);
var body = await response.Content.ReadAsStringAsync();
var user = JsonSerializer.Deserialize<User>(body);
Assert.Equal("John", user.Name);

With Fluent.Client.AwesomeAssertions, your tests become expressive and self-documenting:

// ✅ Fluent approach - clear intent, readable assertions
await client
    .Post("/api/users", new { Name = "John" })
    .Should()
    .Satisfy<User>(u => u.Name.Should().Be("John"));

⚡ Get Started

1. Install the Package

dotnet add package Fluent.Client.AwesomeAssertions

📦 NuGet: https://www.nuget.org/packages/Fluent.Client.AwesomeAssertions

2. (Optional) Add Fluent.Client

For an even more fluent API experience:

dotnet add package Fluent.Client

📦 NuGet: https://www.nuget.org/packages/Fluent.Client

3. Start Writing Tests

using Fluent.Client;
using Fluent.Client.AwesomeAssertions;

[Fact]
public async Task CreateUser_ReturnsSuccess()
{
    await client
        .Post("/api/users", new { Name = "John" })
        .Should()
        .Succeed("because valid user data was provided");
}

📖 How to Use

1. Assert Success

Assert that a request was successful (2xx status code).

<details> <summary><strong>Standard HttpClient</strong></summary>

await client
    .PostAsync("/api/users", content)
    .Should()
    .Succeed();

</details>

<details open> <summary><strong>With Fluent.Client</strong></summary>

await client
    .Post("/api/users", new { Name = "John" })
    .Should()
    .Succeed("because the server returned 200 OK");

</details>

2. Assert Specific Status Code

Assert that a request returned a specific HTTP status code.

await client
    .Delete("/api/users/123")
    .Should()
    .HaveStatusCode(HttpStatusCode.NoContent, "because delete should return 204");

Quick Reference

3. Assert Failure

Assert that a request failed (non-2xx status code).

await client
    .Post("/api/basket", new { CartItem = "esp32-dev-board" })
    .Should()
    .Fail("because the server returned 400 Bad Request");

4. Assert Body Content

Assert on the deserialized response body using Satisfy<T>.

await client
    .Authorize(token: "abc123")
    .Get("/api/users/1", new 
    {
        // Query parameters as anonymous object
        includeDetails = true
    })
    .Should()
    .Satisfy<User>(user =>
    {
        user.Name.Should().Be("John");
        user.Id.Should().Be(1);
    }, "because the server returned the expected JSON body");

<details> <summary><strong>How it works</strong></summary>

1. Awaits the HTTP response
2. Reads the response body as string
3. Deserializes JSON to T using System.Text.Json
4. Executes your assertion lambda against the deserialized object

</details>

5. Authorization with Query Parameters

Combine authorization headers with query parameters for authenticated requests.

Bearer Token Authorization

await client
    .Authorize(token: "abc123")
    .Post("/v1/api/basket")
    .Should()
    .Succeed();

Basic Authentication

await client
    .Authorize(username: "john", password: "potato")
    .Get("/v1/api/basket", new
    {
        page = 1,
        limit = 2,
        sortBy = "dateAsc",
    })
    .Should()
    .HaveStatusCode(HttpStatusCode.Unauthorized, "because the credentials are invalid");

Authorization Methods

🧪 Integration Testing

The library excels in integration testing scenarios with multi-step workflows.

<details open> <summary><strong>Complete Workflow Example</strong></summary>

[Collection("Integration Tests")]
public sealed class OrderWorkflowTests(AspireAppHostFixture app)
{
    [Fact]
    public async Task Order_WhenCreatedAndProcessed_CompletesSuccessfully()
    {
        Guid orderId = Guid.NewGuid();

        // Step 1: Create resource
        await app.Client
            .Authorize(token: "jwt-token")
            .Put($"v1/orders/{orderId}", new { ProductId = "SKU-001", Quantity = 2 })
            .Should()
            .Succeed("because order creation should be accepted");

        // Step 2: Verify resource state
        await app.Client
            .Authorize(token: "jwt-token")
            .Get($"v1/orders/{orderId}")
            .Should()
            .Satisfy<OrderResponse>(order =>
            {
                order.Status.Should().Be("Pending");
                order.Id.Should().Be(orderId);
            });

        // Step 3: Transition state
        await app.Client
            .Authorize(token: "jwt-token")
            .Put($"v1/orders/{orderId}/confirm")
            .Should()
            .Succeed("because order confirmation should succeed");

        // Step 4: Complete workflow
        await app.Client
            .Authorize(token: "jwt-token")
            .Put($"v1/orders/{orderId}/complete", new { Note = "Delivered" })
            .Should()
            .Succeed("because order completion should succeed");
    }
}

</details>

Key Patterns

📚 API Reference

Assertion Methods

JSON Serialization

<details> <summary><code>Satisfy<T></code> uses the following <code>JsonSerializerOptions</code> by default</summary>

new JsonSerializerOptions
{
    PropertyNameCaseInsensitive = true,
    AllowTrailingCommas = true,
    WriteIndented = true,
    IncludeFields = false,
    Converters = { new JsonStringEnumConverter() }
}

</details>

👥 Maintainers

• Leszek Pomianowski (@pomianowski)

💬 Support

For support, please open a GitHub issue. We welcome bug reports, feature requests, and questions.

🙏 Acknowledgements

This project builds on the excellent AwesomeAssertions library and is inspired by the need for better HTTP testing ergonomics in .NET.

📄 License

This project is licensed under the terms of the MIT open source license. Please refer to the LICENSE file for the full terms.

You can use it in private and commercial projects. Keep in mind that you must include a copy of the license in your project.