Playwright E2E Testing for Blazor

Overview

Playwright for .NET provides cross-browser automation for testing Blazor applications. It handles Blazor's asynchronous rendering, WebAssembly loading, and SignalR connections with robust auto-waiting and retry mechanisms.

Key Capabilities

• Cross-browser testing (Chromium, Firefox, WebKit)
• Auto-waiting for elements and network requests
• Trace viewer for debugging failed tests
• Parallel test execution
• Full support for Blazor WebAssembly and Server

CRITICAL: Blazor-Specific Considerations

Quick Start

1. Create Test Project

# MSTest (recommended for .NET projects)
dotnet new mstest -n MyApp.E2E
cd MyApp.E2E

# Add Playwright
dotnet add package Microsoft.Playwright.MSTest

# Build to generate playwright.ps1
dotnet build

# Install browsers
pwsh bin/Debug/net8.0/playwright.ps1 install

2. Basic Blazor Test

using Microsoft.Playwright;
using Microsoft.Playwright.MSTest;

namespace MyApp.E2E;

[TestClass]
public class HomePageTests : PageTest
{
    [TestMethod]
    public async Task HomePage_DisplaysWelcomeMessage()
    {
        // Navigate and wait for Blazor to load
        await Page.GotoAsync("https://localhost:5001/");
        await WaitForBlazorAsync();

        // Use role-based locator (accessibility-first)
        var heading = Page.GetByRole(AriaRole.Heading, new() { Name = "Welcome" });
        await Expect(heading).ToBeVisibleAsync();
    }

    private async Task WaitForBlazorAsync()
    {
        // Wait for Blazor WebAssembly to finish loading
        await Page.WaitForFunctionAsync("window.Blazor !== undefined");

        // Wait for any initial loading indicators to disappear
        var loader = Page.GetByTestId("app-loading");
        await Expect(loader).ToBeHiddenAsync(new() { Timeout = 30000 });
    }
}

3. Configure Base URL

Override ContextOptions to set a base URL:

[TestClass]
public class BlazorTestBase : PageTest
{
    public override BrowserNewContextOptions ContextOptions => new()
    {
        BaseURL = "https://localhost:5001",
        IgnoreHTTPSErrors = true // For dev certificates
    };
}

Locator Strategy (Priority Order)

Always prefer user-facing locators for resilient tests:

MudBlazor Component Locators

// MudButton - use role and accessible name
var saveButton = Page.GetByRole(AriaRole.Button, new() { Name = "Save" });

// MudTextField - use label
var emailField = Page.GetByLabel("Email");

// MudSelect - use label then interact
var categorySelect = Page.GetByLabel("Category");
await categorySelect.ClickAsync();
await Page.GetByRole(AriaRole.Option, new() { Name = "Electronics" }).ClickAsync();

// MudDataGrid row - use text content
var row = Page.GetByRole(AriaRole.Row).Filter(new() { HasText = "Product ABC" });

// MudDialog - use role
var dialog = Page.GetByRole(AriaRole.Dialog);
await Expect(dialog).ToBeVisibleAsync();

Anti-Patterns to Avoid

Additional Resources

For detailed guidance, see:

• Test Patterns - Form submission, dialogs, grids, auth flows
• Configuration - Project structure, .runsettings, CI/CD
• Project Setup - Full project configuration
• Blazor Patterns - Blazor-specific testing patterns, assertions, and actionability
• MudBlazor Selectors - Finding MudBlazor components
• Debugging - Trace viewer, headed mode, Inspector, and debugging techniques

External Documentation

• Playwright .NET Docs
• Playwright Locators
• Playwright Assertions
• Playwright Trace Viewer