API Proposal: Microsoft.AspNetCore.Components.Testing E2E infrastructure

[javiercn]

Background and Motivation

Blazor E2E testing currently requires significant boilerplate for process management, readiness detection, proxy routing, interactivity awareness, and tracing. Each test project reimplements this infrastructure. This package provides a Playwright + xUnit v3 + YARP-based E2E testing library that handles all of these concerns, enabling developers to write concise E2E tests for Blazor applications.

PR #65958. No linked issue. Adds Microsoft.AspNetCore.Components.Testing E2E test infrastructure.

Proposed API

namespace Microsoft.AspNetCore.Components.Testing.Infrastructure;

+ public class ServerFixture<TTestAssembly> : IAsyncLifetime, IAsyncDisposable
+ {
+     public string ProxyUrl { get; }
+     public ValueTask InitializeAsync();
+     public ValueTask DisposeAsync();
+     public Task<ServerInstance> StartServerAsync(string appName, Action<ServerStartOptions>? configure = null);
+     public Task<ServerInstance> StartServerAsync<TApp>(Action<ServerStartOptions>? configure = null);
+ }

+ public class ServerInstance : IAsyncDisposable
+ {
+     public string AppName { get; }
+     public string AppUrl { get; }
+     public string Id { get; }
+     public string? PublicUrl { get; }
+     public string TestUrl { get; }
+     public ValueTask DisposeAsync();
+ }

+ public class ServerStartOptions
+ {
+     public Dictionary<string, string> EnvironmentVariables { get; }
+     public int ReadinessTimeoutMs { get; set; }
+     public void ConfigureServices(Type type, string methodName);
+     public void ConfigureServices<T>(string methodName);
+ }

+ public static class PlaywrightExtensions
+ {
+     public static Task<TracedContext> NewTracedContextAsync(this BrowserTest test, ServerInstance server, BrowserNewContextOptions? options = null);
+     public static string SanitizeFileName(string name);
+     public static Task SetTestSession(this IBrowserContext context, ServerInstance server, string sessionId);
+     public static Task<TracingSession> TraceAsync(this IBrowserContext context, string artifactDir);
+     public static Task WaitForBlazorAsync(this IPage page);
+     public static Task WaitForEnhancedNavigationAsync(this IPage page);
+     public static Task WaitForEnhancedNavigationAsync(this IPage page, Func<Task> navigationAction);
+     public static Task WaitForInteractiveAsync(this IPage page, string selector);
+     public static BrowserNewContextOptions WithArtifacts(this BrowserNewContextOptions options, string? artifactDir = null);
+     public static BrowserNewContextOptions WithServerRouting(this BrowserNewContextOptions options, ServerInstance server);
+ }

+ public class TracedContext : IAsyncDisposable
+ {
+     public IBrowserContext Context { get; }
+     public void Deconstruct(out IBrowserContext context);
+     public ValueTask DisposeAsync();
+     public Task<IPage> NewPageAsync();
+ }

+ public class TracingSession : IAsyncDisposable
+ {
+     public ValueTask DisposeAsync();
+     public static Task<TracingSession> StartAsync(IBrowserContext context, string artifactDir, bool recordVideo);
+ }

+ public class RemoteLock : IAsyncDisposable
+ {
+     public ValueTask DisposeAsync();
+     public Task ReleaseAsync();
+ }

+ public class ResourceLock : IAsyncDisposable
+ {
+     public ValueTask DisposeAsync();
+     public Task ReleaseAsync();
+     public Task WaitForRequestAsync();
+     public static Task<ResourceLock> CreateAsync(IPage page, Regex urlPattern);
+ }

+ public class TestLockClient
+ {
+     public RemoteLock Lock(string name);
+     public static Task<TestLockClient> CreateAsync(ServerInstance server, IBrowserContext context);
+ }

+ public class TestLockProvider
+ {
+     public bool Release(string key);
+     public Task WaitOn(string key);
+ }

+ public class TestSessionContext
+ {
+     public string? Id { get; set; }
+ }

+ public class TestReadinessHostingStartup : IHostingStartup
+ {
+     public void Configure(IWebHostBuilder builder);
+ }

+ public interface IE2EServiceOverrideResolver
+ {
+     Action<IServiceCollection>? TryResolve(string assemblyQualifiedTypeName, string methodName);
+ }

Usage Examples

[Fact]
public async Task Counter_IncrementsOnClick()
{
    await using var ctx = await this.NewTracedContextAsync(_server);
    var page = await ctx.NewPageAsync();

    await page.GotoAsync($"{_server.TestUrl}/counter");
    await page.WaitForInteractiveAsync("button.btn-primary");

    await page.GetByRole(AriaRole.Button, new() { Name = "Click me" }).ClickAsync();

    await Expect(page.Locator("p[role='status']")).ToHaveTextAsync("Current count: 1");
}

Alternative Designs

Each test project building its own infrastructure. The unified library reduces duplication and provides consistent patterns.

Risks

Large public API surface. The library depends on Playwright and xUnit v3, which constrains the testing framework choice. This is primarily intended for testing Blazor applications within the ASP.NET Core repo and by library authors.

[dotnet-policy-service]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[github-actions]

Triage Summary

Area: area-blazor (already labeled — proposal is for Microsoft.AspNetCore.Components.Testing, a new Blazor E2E testing library under src/Components/)
Type: api-proposal (formal API addition proposal with a full diff of new public types and methods, linked to PR #65958)

Potential Duplicates

• None found — searches for "Microsoft.AspNetCore.Components.Testing E2E infrastructure" and "Blazor E2E testing Playwright ServerFixture" returned only this issue.

Notes

• The issue already carries api-ready-for-review, indicating it is already in the API review queue.
• The proposed library (Playwright + xUnit v3 + YARP) is explicitly scoped to internal ASP.NET Core repo usage and library authors, which aligns with the stated risks around its large public API surface and opinionated dependency choices.

Generated by Issue Triage Agent for dotnet/aspnetcore for issue #66394 · ● 172.5K · ◷