Union.Playwright.NUnit 0.8.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. Actions (Action)

Click-and-wait methods that interact with the page and actualize browser state in one step. Uses Playwright's native waiting (no polling or Thread.Sleep).

// Click a link and wait for redirect — returns typed page or null
var dashboard = await myApp.Action
    .ClickAndWaitForRedirectAsync<DashboardPage>(page.Locator("a.dashboard-link"));

if (dashboard != null)
{
    // State is actualized — service knows we're on DashboardPage
    myApp.State.PageIs<DashboardPage>().Should().BeTrue();
}

// Click a button and wait for a modal to appear — returns typed modal or null
var confirmDialog = await myApp.Action
    .ClickAndWaitForAlertAsync<ConfirmDialog>(page.Locator("button.delete"));

if (confirmDialog != null)
{
    // Modal is actualized — available via state as well
    confirmDialog.Accept();
}

Both methods return null when the expected result doesn't happen (no redirect, or modal didn't appear within Playwright's timeout). This lets you handle unexpected states gracefully in tests instead of getting timeout exceptions.

6. 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();

7. 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
}

Click and wait for redirect

Before:

await page.Locator("a.dashboard").ClickAsync();
await page.WaitForURLAsync("**/dashboard");
// manual URL check, no page object

After:

var dashboard = await myApp.Action
    .ClickAndWaitForRedirectAsync<DashboardPage>(page.Locator("a.dashboard"));
// returns typed page with extracted params, state actualized automatically

Click and wait for modal

Before:

await page.Locator("button.delete").ClickAsync();
await page.Locator(".confirm-dialog").WaitForAsync();
// manual locator management, no typed modal object

After:

var dialog = await myApp.Action
    .ClickAndWaitForAlertAsync<ConfirmDialog>(page.Locator("button.delete"));
// returns typed modal, state.ModalWindow also set
dialog?.Accept();

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

IBrowserAction

IBrowserState

ComponentBase

ListBase<T>

Attributes