Union.Playwright.NUnit 0.4.1

Union.Playwright.NUnit

A .NET 9.0 testing framework built on top of Microsoft Playwright and NUnit. It adds Page Object Model infrastructure with URL-based routing, automatic page resolution, reusable components, and dependency injection — so you can stop hand-wiring navigation and page state and focus on writing tests.

Why migrate from raw Playwright?

Installation

dotnet add package Union.Playwright.NUnit

Then install Playwright browsers:

pwsh bin/Debug/net9.0/playwright.ps1 install

Core concepts

1. Pages

A page is a class that maps to a URL pattern.

public abstract class MyAppPage : UnionPage { }

public class LoginPage : MyAppPage
{
    public override string AbsolutePath => "/login";
}

public class UserProfilePage : MyAppPage
{
    public override string AbsolutePath => "/users/{userId}";

    // Path parameters are extracted automatically
    public string UserId => Data["userId"];
}

public class SearchResultsPage : MyAppPage
{
    public override string AbsolutePath => "/search";

    // Query parameters (?q=playwright) extracted automatically
    public string Query => Params["q"];
}

Key points:

• AbsolutePath supports {paramName} placeholders — matched segments populate the Data dictionary.
• Query string values populate the Params dictionary.
• Override WaitLoadedAsync() to add custom wait logic (spinners, skeleton screens) that runs after every navigation.

2. Services

A service represents one application under test (one base URL).

public class MyAppService : UnionService<MyAppPage>
{
    public MyAppService(IServiceContextsPool pool) : base(pool) { }

    public override string BaseUrl => "https://myapp.example.com";
}

On construction the service automatically discovers and registers every non-abstract page class that derives from the base page type (MyAppPage) via reflection. No manual registration needed.

3. Navigation (Go)

// Navigate by type — URL is assembled from the page's AbsolutePath + BaseUrl
var loginPage = await myApp.Go.ToPage<LoginPage>();

// Navigate to a page with path parameters pre-filled
var profile = new UserProfilePage { Data = { ["userId"] = "42" } };
await myApp.Go.ToPage(profile);
// Browser navigates to https://myapp.example.com/users/42

// Raw URL navigation (still actualizes state afterward)
await myApp.Go.ToUrl("https://myapp.example.com/settings");

// Browser controls
await myApp.Go.Refresh();
await myApp.Go.Back();

After every navigation the framework:

1. Matches the resulting URL against all registered pages.
2. Creates a page instance with extracted Data and Params.
3. Calls page.Activate() — which triggers component initialization.
4. Calls page.WaitLoadedAsync().

4. State

// Check what page the browser is on
bool isLogin = myApp.State.PageIs<LoginPage>();

// Get the current page as a specific type (null if it doesn't match)
var profile = myApp.State.PageAs<UserProfilePage>();
Console.WriteLine(profile?.UserId); // "42"

5. Components

Components are reusable UI building blocks that attach to pages (or to other components) via the [UnionInit] attribute.

// A simple element wrapper
public class Element : ComponentBase
{
    public Element(IUnionPage parentPage, string rootScss)
        : base(parentPage, rootScss) { }
}

// A page with auto-initialized components
public class QuestionsPage : MyAppPage
{
    public override string AbsolutePath => "/questions";

    [UnionInit("div#questions")]
    public QuestionList Questions { get; set; }
}

When the page is activated, every field and property marked with [UnionInit] is instantiated automatically. The selector argument is scoped relative to the page's (or parent component's) RootScss, so components compose cleanly.

Lists and items

ListBase<T> and ItemBase handle the common "collection of repeated elements" pattern:

public class QuestionList : ListBase<QuestionItem>
{
    public override string ItemIdScss => "div.s-post-summary";
    public override string IdAttribute => "data-post-id";

    public QuestionList(IUnionPage parentPage, string rootScss)
        : base(parentPage, rootScss) { }
}

public class QuestionItem : ItemBase
{
    public override string ItemScss =>
        $"div.s-post-summary[data-post-id='{this.Id}']";

    [UnionInit("h3 a")]
    public Element Title { get; set; }

    public QuestionItem(IContainer container, string id)
        : base(container, id) { }
}

Usage in tests:

var page = await myApp.Go.ToPage<QuestionsPage>();

List<string> ids = await page.Questions.GetIdsAsync();
List<QuestionItem> items = await page.Questions.GetItemsAsync();
QuestionItem single = await page.Questions.FindSingleAsync();
QuestionItem random = await page.Questions.FindRandomAsync();

bool visible = await single.Title.IsVisibleAsync();

6. SCSS selectors

The framework includes a custom selector language that compiles to both CSS and XPath. It extends standard CSS syntax with XPath-only features:

CSS-compatible selectors are emitted as CSS; others fall back to XPath automatically. Use InnerScss() in components to scope relative selectors to the component root.

Test setup

1. Define a test session

A test session groups the services available to a test:

public class MyTestSession : ITestSession
{
    public MyAppService MyApp { get; }

    public MyTestSession(MyAppService myApp)
    {
        this.MyApp = myApp;
    }

    public List<IUnionService> GetServices() => new() { this.MyApp };
}

2. Define a session provider

The provider configures dependency injection:

public class MySessionProvider : TestSessionProvider<MyTestSession>
{
    public static readonly MySessionProvider Instance = new();

    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddScoped<MyAppService>();
    }
}

3. Write tests

[TestFixture]
public class LoginTests : UnionTest<MyTestSession>
{
    protected override TestSessionProvider<MyTestSession> GetSessionProvider()
        => MySessionProvider.Instance;

    [Test]
    public async Task NavigateToLogin()
    {
        var app = this.Session.MyApp;

        var loginPage = await app.Go.ToPage<LoginPage>();

        app.State.PageIs<LoginPage>().Should().BeTrue();
        loginPage.Should().NotBeNull();
    }
}

UnionTest<T>:

• Inherits from Playwright's PageTest — you still have this.Page, this.Context, this.Browser.
• [SetUp] creates a scoped session; [TearDown] disposes it.
• Access the session via this.Session.
• Retrieve a service via this.GetService<TService>().

Migration guide: before and after

Navigating to a page

Before:

await page.GotoAsync("https://myapp.com/login");
// hope the URL is correct, no compile-time safety

After:

var loginPage = await myApp.Go.ToPage<LoginPage>();
// URL assembled from BaseUrl + AbsolutePath, returns typed page object

Extracting path parameters

Before:

await page.GotoAsync($"https://myapp.com/users/{userId}/orders/{orderId}");
// later, to verify:
var url = page.Url;
var segments = new Uri(url).Segments; // manual parsing

After:

public class OrderPage : MyAppPage
{
    public override string AbsolutePath => "/users/{userId}/orders/{orderId}";
    public string UserId => Data["userId"];
    public string OrderId => Data["orderId"];
}

var orderPage = myApp.State.PageAs<OrderPage>();
var userId = orderPage.UserId; // extracted automatically from URL

Page components

Before:

var submitBtn = page.Locator("#form .submit-button");
var nameInput = page.Locator("#form input[name='username']");
// locators duplicated across every test that touches this page

After:

public class LoginPage : MyAppPage
{
    public override string AbsolutePath => "/login";

    [UnionInit("#form .submit-button")]
    public Element SubmitButton { get; set; }

    [UnionInit("#form input[name='username']")]
    public Element NameInput { get; set; }
}

// In test — components ready after navigation
var loginPage = await myApp.Go.ToPage<LoginPage>();
await loginPage.SubmitButton.IsVisibleAsync();

Repeated element lists

Before:

var items = page.Locator(".item");
var count = await items.CountAsync();
for (int i = 0; i < count; i++)
{
    var title = await items.Nth(i).Locator("h3").TextContentAsync();
    // ...
}

After:

var items = await page.ItemList.GetItemsAsync();
foreach (var item in items)
{
    var visible = await item.Title.IsVisibleAsync();
    // each item is a strongly-typed object with its own components
}

Knowing which page you're on

Before:

Assert.That(page.Url, Does.Contain("/dashboard"));
// fragile string matching

After:

myApp.State.PageIs<DashboardPage>().Should().BeTrue();
// URL pattern matching with parameter extraction

API reference

UnionPage

UnionService<T>

IBrowserGo

IBrowserState

ComponentBase

ListBase<T>

Attributes