TestPage Class

A page of a browser engine written in .NET (Meziantou.Framework.WebPlatform), driven by a test: the user input, the queries of the elements, the waits, and the snapshots of the DOM, of the accessibility tree and of the pixels. A BrowserPage is a page of an application (see WebAppBrowser).

public abstract class TestPage : LocatorScope, IAsyncDisposable, IDisposable
Inheritance
LocatorScope TestPage
Implements

Constructors

NameDescription
TestPage(TestPageSettings)Initializes a new instance of the TestPage class.

TestPage(TestPageSettings)

TestPage.cs

Initializes a new instance of the TestPage class.

protected TestPage(TestPageSettings settings)

Parameters

settings TestPageSettings
The settings of the browsing context of the page.

Properties

NameDescription
BrowsingContextGets the browsing context of the page (viewport, user input, event loop, history...).
ConsoleMessagesGets the messages written by the scripts of the page to the console.
ContentSecurityPolicyViolationsGets the violations of the content security policies of the page (the Content-Security-Policy and Content-Security-Policy-Report-Only headers and the meta elements), as reported by the securitypolicyviolation events, including the ones raised while the document loads.
DefaultTimeoutGets the maximum time the waits of the page wait for.
DocumentGets the active document of the page.
InputGets the user input: the mouse, the keyboard and the touch screen.
IsDisposedGets whether the page is disposed.
ScriptErrorsGets the errors of the scripts of the page that were not handled.
TestIdAttributeGets the name of the attribute that LocatorScope.GetByTestId matches.
UrlGets the URL of the active document.

BrowsingContext

TestPage.cs

Gets the browsing context of the page (viewport, user input, event loop, history...).

public BrowsingContext BrowsingContext { get; }

Property value

BrowsingContext

ConsoleMessages

TestPage.cs

Gets the messages written by the scripts of the page to the console.

public IReadOnlyList<string> ConsoleMessages { get; }

Property value

IReadOnlyList<string>

ContentSecurityPolicyViolations

TestPage.cs

Gets the violations of the content security policies of the page (the Content-Security-Policy and Content-Security-Policy-Report-Only headers and the meta elements), as reported by the securitypolicyviolation events, including the ones raised while the document loads.

public IReadOnlyList<ContentSecurityPolicyViolationReport> ContentSecurityPolicyViolations { get; }

DefaultTimeout

TestPage.cs

Gets the maximum time the waits of the page wait for.

public TimeSpan DefaultTimeout { get; }

Property value

TimeSpan

Document

TestPage.cs

Gets the active document of the page.

public Document Document { get; }

Property value

Document

Gets the user input: the mouse, the keyboard and the touch screen.

public PageInput Input { get; }

Property value

PageInput

IsDisposed

TestPage.cs

Gets whether the page is disposed.

protected bool IsDisposed { get; }

Property value

bool

ScriptErrors

TestPage.cs

Gets the errors of the scripts of the page that were not handled.

public IReadOnlyList<ScriptError> ScriptErrors { get; }

TestIdAttribute

TestPage.cs

Gets the name of the attribute that LocatorScope.GetByTestId matches.

public string TestIdAttribute { get; }

Property value

string

Gets the URL of the active document.

public string Url { get; }

Property value

string

Methods

NameDescription
Dispose()Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
Dispose(bool)Releases the resources of the page.
DisposeAsync()Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.
DisposeAsyncCore()Releases the resources of the page asynchronously. Calls TestPage.Dispose by default.
EnterEventLoop()Runs the code that follows on the event loop of the page until the result is disposed: a derived page runs the continuations of its own asynchronous code on the event loop (for instance the components of Blazor). Returns null by default.
Find(string)Gets the first element of the page that matches a CSS selector, now (see LocatorScope.Locator for a locator that waits).
Find<TElement>(string)Gets the first element of the page of a type that matches a CSS selector, now.
FindAll(string)Gets the elements of the page that match a CSS selector now, in document order.
FindOrDefault(string)Gets the first element of the page that matches a CSS selector now, or null.
GetAccessibilitySnapshot()Gets the accessibility tree of the page, as a YAML snapshot (the format of the ARIA snapshots of Playwright).
GetMarkup(MarkupOptions?)Gets the HTML of the body of the page, formatted for snapshots.
GetPage(Node)Gets the page of a node of one of its documents.
GetPendingTasks()Returns the tasks whose completion can make the page idle (a wait wakes up when one completes).
GetRoots()Gets the nodes that the queries of the page search: the document element by default.
IsIdle()Returns whether the page is idle: the event loop has no task and no pending network request. A derived page adds its own pending work.
RunEventLoop()Runs the tasks of the event loop of the page until there is none.
TakeScreenshotAsPng(ScreenshotOptions?)Takes a screenshot of the viewport, encoded as PNG.
ThrowIfFailed()Throws the errors that the page collected while the event loop ran (for instance the unhandled exceptions of the components).
WaitForAssertionAsync(Action, TimeSpan?, CancellationToken)Runs the event loop of the page until an assertion passes.
WaitForAsync(Func<bool>, TimeSpan?, CancellationToken)Runs the event loop of the page until a condition is true.
WaitForIdleAsync(TimeSpan?, CancellationToken)Runs the event loop of the page until it is idle: no task, no pending network request (see TestPage.IsIdle).

Dispose overloads

Dispose()

TestPage.cs

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Dispose(bool)

TestPage.cs

Releases the resources of the page.

protected virtual void Dispose(bool disposing)
Parameters
disposing bool
True when called from TestPage.Dispose.

DisposeAsync()

TestPage.cs

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

net10.0

public ValueTask DisposeAsync()

net11.0

public ValueTask DisposeAsync()

Returns

ValueTask A task that represents the asynchronous dispose operation.

DisposeAsyncCore()

TestPage.cs

Releases the resources of the page asynchronously. Calls TestPage.Dispose by default.

protected virtual ValueTask DisposeAsyncCore()

Returns

ValueTask A task completed once the resources are released.

EnterEventLoop()

TestPage.cs

Runs the code that follows on the event loop of the page until the result is disposed: a derived page runs the continuations of its own asynchronous code on the event loop (for instance the components of Blazor). Returns null by default.

protected internal virtual IDisposable? EnterEventLoop()

Returns

IDisposable? An object that leaves the event loop when disposed, or null.

Find overloads

Find(string)

TestPage.cs

Gets the first element of the page that matches a CSS selector, now (see LocatorScope.Locator for a locator that waits).

public Element Find(string selector)
Parameters
selector string
The CSS selector.
Returns

Element The element.

Exceptions
ElementNotFoundException
No element matches the selector.

Find<TElement>(string)

TestPage.cs

Gets the first element of the page of a type that matches a CSS selector, now.

public TElement Find<TElement>(string selector) where TElement : Element
Type parameters
TElement
The type of the element.
Parameters
selector string
The CSS selector.
Returns

TElement The element.

Exceptions
ElementNotFoundException
No element of type TElement matches the selector.

FindAll(string)

TestPage.cs

Gets the elements of the page that match a CSS selector now, in document order.

public IReadOnlyList<Element> FindAll(string selector)

Parameters

selector string
The CSS selector.

Returns

IReadOnlyList<Element> The elements.

FindOrDefault(string)

TestPage.cs

Gets the first element of the page that matches a CSS selector now, or null.

public Element? FindOrDefault(string selector)

Parameters

selector string
The CSS selector.

Returns

Element? The element, or null.

GetAccessibilitySnapshot()

TestPage.cs

Gets the accessibility tree of the page, as a YAML snapshot (the format of the ARIA snapshots of Playwright).

public string GetAccessibilitySnapshot()

Returns

string The snapshot.

GetMarkup(MarkupOptions?)

TestPage.cs

Gets the HTML of the body of the page, formatted for snapshots.

public string GetMarkup(MarkupOptions? options = null)

Parameters

options MarkupOptions?
The options, or null for the default options.

Returns

string The HTML.

GetPage(Node)

TestPage.cs

Gets the page of a node of one of its documents.

public static TestPage GetPage(Node node)

Parameters

node Node
The node.

Returns

TestPage The page.

Exceptions

InvalidOperationException
The node does not belong to a document of a TestPage.

GetPendingTasks()

TestPage.cs

Returns the tasks whose completion can make the page idle (a wait wakes up when one completes).

protected virtual IReadOnlyCollection<Task> GetPendingTasks()

Returns

IReadOnlyCollection<Task> The pending tasks.

GetRoots()

TestPage.cs

Gets the nodes that the queries of the page search: the document element by default.

protected virtual IReadOnlyList<Node> GetRoots()

Returns

IReadOnlyList<Node> The root nodes.

IsIdle()

TestPage.cs

Returns whether the page is idle: the event loop has no task and no pending network request. A derived page adds its own pending work.

protected virtual bool IsIdle()

Returns

bool True when the page is idle.

RunEventLoop()

TestPage.cs

Runs the tasks of the event loop of the page until there is none.

protected internal void RunEventLoop()

TakeScreenshotAsPng(ScreenshotOptions?)

TestPage.cs

Takes a screenshot of the viewport, encoded as PNG.

public byte[] TakeScreenshotAsPng(ScreenshotOptions? options = null)

Parameters

options ScreenshotOptions?
The options, or null for the default options.

Returns

byte[] The PNG image.

ThrowIfFailed()

TestPage.cs

Throws the errors that the page collected while the event loop ran (for instance the unhandled exceptions of the components).

protected virtual void ThrowIfFailed()

WaitForAssertionAsync(Action, TimeSpan?, CancellationToken)

TestPage.cs

Runs the event loop of the page until an assertion passes.

net10.0

public Task WaitForAssertionAsync(Action assertion, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

net11.0

public Task WaitForAssertionAsync(Action assertion, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

assertion Action
The assertion, which throws when it fails.
timeout TimeSpan?
The maximum time to wait, or null for TestPage.DefaultTimeout.
cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the assertion passes.

Exceptions

TimeoutException
The assertion fails after timeout; the inner exception is the last failure.

WaitForAsync(Func<bool>, TimeSpan?, CancellationToken)

TestPage.cs

Runs the event loop of the page until a condition is true.

public Task WaitForAsync(Func<bool> condition, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

condition Func<bool>
The condition, evaluated after each task of the event loop.
timeout TimeSpan?
The maximum time to wait, or null for TestPage.DefaultTimeout.
cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the condition is true.

Exceptions

TimeoutException
The condition is false after timeout.

WaitForIdleAsync(TimeSpan?, CancellationToken)

TestPage.cs

Runs the event loop of the page until it is idle: no task, no pending network request (see TestPage.IsIdle).

public Task WaitForIdleAsync(TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

timeout TimeSpan?
The maximum time to wait, or null for TestPage.DefaultTimeout.
cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the page is idle.

Exceptions

TimeoutException
The page is not idle after timeout.