Swap.Testing 1.3.0

Swap.Testing

Swap.Testing provides small helpers for writing integration tests against HTMX-powered ASP.NET Core MVC applications.

It is designed to work alongside Swap.Htmx but does not require it.

Install

• NuGet: https://www.nuget.org/packages/Swap.Testing

dotnet add package Swap.Testing

Key types

• HtmxTestFixture<TProgram> – wraps WebApplicationFactory<TProgram> and gives you an HtmxTestClient<TProgram>.
• HtmxTestClient<TProgram> – fluent client with HTMX-aware helpers (HtmxGetAsync, HtmxPostAsync, SubmitFormAsync, …).
• HtmxTestResponse – wraps HttpResponseMessage and exposes HTML and HTMX assertions (elements, attributes, HX headers, snapshots, validation, etc.).
• SnapshotManager – optional snapshot testing helper for HTML responses.

Basic usage

1. Create a test project and reference your ASP.NET Core app project.
2. Add Swap.Testing to the test project.
3. Use HtmxTestFixture<TProgram> as an xUnit fixture:

public class TodosTests : IClassFixture<HtmxTestFixture<Program>>
{
    private readonly HtmxTestClient<Program> _client;

    public TodosTests(HtmxTestFixture<Program> fixture)
    {
        _client = fixture.Client;
    }

    [Fact]
    public async Task GetTodos_ReturnsPartialWithItems()
    {
        var response = await _client.HtmxGetAsync("/todos");

        await response
            .AssertSuccess()
            .AssertPartialViewAsync()
            .AssertElementCountAsync(".todo-item", expectedCount: 5);
    }

    [Fact]
    public async Task UpdateCounter_RazorPage_ReturnsUpdatedCount()
    {
        // Use the Razor Pages helper to target a specific handler
        var response = await _client.HtmxGetPageHandlerAsync("/Counter", "Increment", new { count = 5 });

        await response
            .AssertSuccess()
            .AssertContainsAsync("Count: 6");
    }
}

Form and redirect helpers

• SubmitFormAsync – finds a <form> in a previous HTML response, reads hx-* or action/method, collects inputs, and submits as an HTMX request.
• FollowHxRedirectAsync – follows an HX-Redirect header and returns the resulting HTMX response.

Snapshot testing

Use AssertMatchesSnapshotAsync to compare HTML output against a stored snapshot.

await response
    .AssertSuccess()
    .AssertMatchesSnapshotAsync("todo-list-partial");

The first run creates __snapshots__/todo-list-partial.html. Future runs compare normalized HTML. Set UPDATE_SNAPSHOTS=true to update snapshots.

More examples

See EXAMPLE_TESTS.cs in this folder for a longer example suite using most of the helpers.

Cookie Persistence

Cookies automatically persist across requests within the same HtmxTestClient instance, enabling session-based and authentication testing:

// Login sets a session cookie — persists automatically
await _client.HtmxPostAsync("/auth/login", loginData);

// Subsequent requests include the session cookie
var dashboard = await _client.GetAsync("/dashboard");
await dashboard.AssertSuccess().AssertContainsAsync("Welcome");

// Inspect cookies
var cookies = _client.Cookies.GetAllCookies();

// Clear for test isolation
_client.ClearCookies();

OOB Swap Introspection

Inspect and assert out-of-band swap elements in responses:

var response = await _client.HtmxPostAsync("/shop/purchase", data);

// Get all OOB swaps as structured data
var swaps = await response.GetOobSwapsAsync();
// Each OobSwap has: TargetId, SwapMode, HtmlContent

// Fluent assertions
await response
    .AssertOobSwapExistsAsync("cart-count")
    .AssertOobSwapContentAsync("cart-count", "5")
    .AssertOobSwapCountAsync(3);

Trigger Payload Assertions

Deep-inspect HX-Trigger JSON payloads:

response
    .AssertTriggerPayload("showToast", "message", "Created")
    .AssertTriggerPayload("itemCreated", "data.id", "123")
    .AssertTriggerCount(2);

// Typed deserialization
var toast = response.GetTriggerPayload<ToastData>("showToast");

Form Field Assertions

Assert form field existence and values:

await response
    .AssertFormFieldExistsAsync("Email")
    .AssertFormValueAsync("Name", "John")
    .AssertFormValueAsync("Active", "true");   // checkbox

Snapshot Scrubbers

The SnapshotManager supports custom scrubbers for dynamic content:

SnapshotManager.ScrubUrls();                            // Replace URLs → [URL]
SnapshotManager.ScrubRegex(@"tenant-\w+", "[TENANT]"); // Custom pattern
SnapshotManager.ClearScrubbers();                       // Reset

Built-in default scrubbers automatically handle GUIDs → [GUID], ISO dates → [DATETIME], and anti-forgery tokens → [TOKEN].