Document improve automated browser testing with WebApplicationFactory and Kestrel in .NET 10

[danroth27]

Description

Document improve automated browser testing with WebApplicationFactory and Kestrel in .NET 10: https://github.com/dotnet/core/blob/main/release-notes/10.0/preview/preview4/aspnetcore.md#use-webapplicationfactory-with-kestrel-for-integration-testing

Page URL

https://learn.microsoft.com/en-us/aspnet/core/test/integration-tests?view=aspnetcore-10.0&pivots=xunit

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/test/integration-tests.md

Document ID

f499b131-8b14-7e10-1728-543fdd5a5656

Platform Id

a725fe2a-b11f-6664-eb77-2adc94d55792

Article author

@tdykstra

Metadata

• ID: 77889d43-fedb-f8b4-8fea-379ec946555c
• PlatformId: a725fe2a-b11f-6664-eb77-2adc94d55792
• Service: aspnet-core
• Sub-service: testing

Related Issues

[wadepickett]

@tdykstra, .NET 10 topic update needed, filed by Dan.

I took the opportunity to run our latest AI prompts using version .05 for generating an analyis and action plan, here is the output below. Interesting ly I ran it on the GPT 4.1 model first and it left out "StartServer();" from the code example. This one below is Claude Sonnet 3.5 which did not have that problem:

AI analysis test run by wadepickett
Prompt: verify-issue-set-course-of-action_v.05.md
Model: Claude 3.5 Sonnet (2024-10-22)

Issue Analysis: Document WebApplicationFactory with Kestrel for Integration Testing in .NET 10

Issue Summary

This is a valid issue.

The issue requests documentation of a new .NET 10 feature that enables using WebApplicationFactory with Kestrel for integration testing, as announced in the .NET 10 Preview 4 release notes.

Issue Context and Validation

Issue Details:

• Issue Number: Document improve automated browser testing with WebApplicationFactory and Kestrel in .NET 10 #36312
• Target Article: https://learn.microsoft.com/en-us/aspnet/core/test/integration-tests?view=aspnetcore-10.0&pivots=xunit
• Source File: aspnetcore/test/integration-tests.md
• Target .NET Version: 10.0
• Article Author: @tdykstra
• Service/Subservice: aspnet-core / testing

Validation:
The issue references a legitimate feature introduced in .NET 10 Preview 4. The feature is documented in the official release notes at:
https://github.com/dotnet/core/blob/main/release-notes/10.0/preview/preview4/aspnetcore.md#use-webapplicationfactory-with-kestrel-for-integration-testing

Feature Summary:
The new capability allows developers to use WebApplicationFactory with Kestrel for integration testing instead of the in-memory TestServer. This enables running integration tests against a real Kestrel server, including browser-based tests using tools like Playwright or Selenium.

Key Methods:

• UseKestrel() - Configures the factory to use Kestrel
• StartServer() - Starts the Kestrel server
• Optional UseKestrel overloads for port and Kestrel configuration

Affected File(s) and Section(s)

Primary File:

• Path: aspnetcore/test/integration-tests.md
• Current Version: Moniker range >= aspnetcore-10.0
• File exists and is actively maintained

Target Section:
The new content should be added near the end of the document, after the existing integration testing content. Based on the current structure, the ideal location would be:

• After the "Integration tests sample" section (currently starts at line ~447)
• Before the "Additional resources" section (currently at line ~498)

This placement makes logical sense as it represents an advanced/alternative approach to integration testing.

Recommended Documentation Update

Content to Add

Section Heading: "Browser-based integration testing with Kestrel"

Content Type: New section with explanatory text and code example

Key Points to Cover:

1. Explanation that WebApplicationFactory can now use Kestrel instead of TestServer
2. Benefits: enables real browser automation with Playwright/Selenium
3. Basic usage pattern with UseKestrel() and StartServer()
4. Configuration options (port, Kestrel settings)
5. Integration with browser automation frameworks

Tone: Informative, consistent with existing integration testing documentation

Example Code or CLI Snippets

The release notes provide a complete working example that should be adapted for the documentation:

public class BlazorWebAppFactory : WebApplicationFactory<Program>
{
    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.ConfigureTestServices(svc =>
        {
            svc.AddTransient<IWeatherService, TestWeatherService>();
        });
    }
}

public class WeatherPageTests : PageTest
{
    [Fact]
    public async Task Page_LoadsSuccessfully()
    {
        using var waf = new BlazorWebAppFactory();

        waf.UseKestrel();
        waf.StartServer();

        await Task.Delay(30000);
        var privacyPagePath = waf.ClientOptions.BaseAddress.ToString() + "weather";
        var response = await Page.GotoAsync(privacyPagePath);
        var content = await response!.TextAsync();

        await Expect(Page).ToHaveTitleAsync("Weather");
        Assert.Contains(TestWeatherService.TestWeatherSummary, content);
    }
}

Note: The example should be adapted to:

• Use a more general scenario (not Blazor-specific) or include multiple examples
• Demonstrate Playwright integration more clearly
• Show best practices for cleanup and disposal
• Match the xUnit/MSTest/NUnit pivot structure used in the existing document at https://github.com/dotnet/core/blob/main/release-notes/10.0/preview/preview4/aspnetcore.md#use-webapplicationfactory-with-kestrel-for-integration-testing

Suggested Action Plan for Consideration

• File to Edit: aspnetcore/test/integration-tests.md
• Section: After "Integration tests sample" section (~line 447-495), before "Additional resources"
• Insertion Type: Add new section with heading, explanatory paragraphs, and code block
• Content Block Type: Standard documentation (no special note blocks needed unless highlighting important caveats)
• Example Code to Include:
  • Basic example showing UseKestrel() and StartServer() pattern
  • Playwright/Selenium integration example
  • Optional: Port configuration example
• Expected Output: Updated doc includes clear explanation of the Kestrel-based testing approach with validated code samples showing browser automation scenarios
• Do Not:
  • Edit unrelated sections or headings
  • Remove or modify existing TestServer documentation (this is an alternative approach, not a replacement)
  • Add content to .NET 9 or earlier moniker ranges (feature is .NET 10+ only)

References and Links

• Release Notes: https://github.com/dotnet/core/blob/main/release-notes/10.0/preview/preview4/aspnetcore.md#use-webapplicationfactory-with-kestrel-for-integration-testing
• Target Documentation: https://learn.microsoft.com/en-us/aspnet/core/test/integration-tests?view=aspnetcore-10.0&pivots=xunit
• Source File: https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/test/integration-tests.md
• Related Concepts:
  • WebApplicationFactory: https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.mvc.testing.webapplicationfactory-1
  • Playwright for .NET: https://playwright.dev/dotnet/
  • Selenium: https://www.selenium.dev/

Additional Considerations

1. Moniker Range: Content must be wrapped in :::moniker range=">= aspnetcore-10.0" to ensure it only appears for .NET 10 and later versions.

2. Testing Framework Pivots: The document uses zone pivots for xUnit, MSTest, and NUnit. Code examples should be provided for all three frameworks if they differ significantly.

3. Cross-references: Consider adding a note in the "Basic tests with the default WebApplicationFactory" section pointing readers to the new Kestrel-based approach for browser testing scenarios.

4. Prerequisites: May need to mention Playwright or Selenium NuGet package requirements in the "Test app prerequisites" section.

5. Sample Code: The main sample application may need updates to include a Kestrel-based test example. The sample is located at: https://github.com/dotnet/AspNetCore.Docs.Samples/tree/main/test/integration-tests/10.x/IntegrationTestsSample

---

Summary: This is a straightforward documentation request for a new .NET 10 feature. The issue is valid, actionable, and has clear guidance from the official release notes. The recommended approach is to add a new section demonstrating browser-based integration testing with Kestrel, positioned logically within the existing document structure.