Browser

Namespace: E2E

public sealed class Browser

The browser the attempt drives, showing one active tab. It needs an engine session that implements IBrowserSession, such as WebEngine; on any other engine each member fails with UNSUPPORTED_CAPABILITY.

Inheritance: object

View source

Properties

Keyboard

public BrowserKeyboard Keyboard { get; }

Viewport-level keyboard, for whatever has focus.

Value: BrowserKeyboard

View source

Mouse

public BrowserMouse Mouse { get; }

Direct pointer input from test code, independent of agent observations.

Value: BrowserMouse

View source

Methods

AddInitScriptAsync(WebInitScript, object?, CancellationToken)

public Task AddInitScriptAsync(WebInitScript script, object? arg, CancellationToken cancellationToken = default)

Adds an init script function (FromFunction(string)) the page calls with one JSON-safe argument. Only a function takes an argument.

Parameters

Name	Type	Description
`script`	WebInitScript
`arg`	object
`cancellationToken`	CancellationToken

Returns: Task

View source

AddInitScriptAsync(WebInitScript, CancellationToken)

public Task AddInitScriptAsync(WebInitScript script, CancellationToken cancellationToken = default)

Adds an init script: source, a file of it (FromPath(string)), or a function the page calls with no argument (FromFunction(string)).

Parameters

Name	Type	Description
`script`	WebInitScript
`cancellationToken`	CancellationToken

Returns: Task

View source

AddInitScriptAsync(string, CancellationToken)

public Task AddInitScriptAsync(string script, CancellationToken cancellationToken = default)

Adds JavaScript source every document runs before the page’s own, in every tab and frame, from the next navigation on, for the rest of the attempt.

Parameters

Name	Type	Description
`script`	string
`cancellationToken`	CancellationToken

Returns: Task

View source

BackAsync(CancellationToken)

public Task BackAsync(CancellationToken cancellationToken = default)

Navigates the history back once.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task

View source

CookiesAsync(CancellationToken)

public Task<IReadOnlyList<BrowserCookie>> CookiesAsync(CancellationToken cancellationToken = default)

Returns the cookies visible to the browser context.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task<IReadOnlyList<BrowserCookie>>

View source

EmulateMediaAsync(WebMedia, CancellationToken)

public Task EmulateMediaAsync(WebMedia media, CancellationToken cancellationToken = default)

Emulates CSS media features on every open tab and every tab opened after them, the app’s own included, for the rest of the attempt, through App.RestartAsync and App.ClearStateAsync: the page’s @media rules and matchMedia both read them. A feature left out keeps its value. It works before the first navigation, so the page loads with them.

Parameters

Name	Type	Description
`media`	WebMedia
`cancellationToken`	CancellationToken

Returns: Task

View source

`EvaluateAsync<T>(string, object?, CancellationToken)`

public Task<T?> EvaluateAsync<T>(string expression, object? arg, CancellationToken cancellationToken = default)

Evaluates a function source in the page with one JSON-safe argument.

Type parameters

Name	Description
`T`

Parameters

Name	Type	Description
`expression`	string
`arg`	object
`cancellationToken`	CancellationToken

Returns: Task<T>

View source

`EvaluateAsync<T>(string, CancellationToken)`

public Task<T?> EvaluateAsync<T>(string expression, CancellationToken cancellationToken = default)

Evaluates trusted test code in the page: an expression, or a function source that is called. The result must be JSON-safe and is deserialized to <code class=“typeparamref”>T</code>. A throwing script fails with EVALUATE_FAILED, and a script that does not finish within the action timeout with OPERATION_TIMEOUT.

Type parameters

Name	Description
`T`

Parameters

Name	Type	Description
`expression`	string
`cancellationToken`	CancellationToken

Returns: Task<T>

View source

ForwardAsync(CancellationToken)

public Task ForwardAsync(CancellationToken cancellationToken = default)

Navigates the history forward once.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task

View source

FrameLocator(string)

public FrameScreen FrameLocator(string selector)

Creates a screen query scope inside one iframe: every Screen query answers from inside the frame. The frame is the one element <code class=“paramref”>selector</code> names; none yet is polled for by an action, and answers no match to a read. Upstream’s browser.frameLocator.

Parameters

Name	Type	Description
`selector`	string

Returns: FrameScreen

Exceptions

Type	Condition
TestException	`INVALID_LOCATOR`: <code class=“paramref”>selector</code> is empty.

View source

GotoAsync(string, GotoOptions?, CancellationToken)

public Task GotoAsync(string url, GotoOptions? options = null, CancellationToken cancellationToken = default)

Navigates to <code class=“paramref”>url</code>, resolved against the base URL like App.OpenAsync, and waits for WaitUntil within Timeout.

Parameters

Name	Type	Description
`url`	string
`options`	GotoOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

Locator(string)

public Locator Locator(string selector)

Creates a web-only locator from a CSS or XPath selector, for a control with no accessible name. Same polling and strictness as any locator. A selector that captures with * before its last part (*css=article >> text=Hello) is refused with INVALID_LOCATOR when the locator resolves: narrow with Filter(Locator) instead. Upstream’s browser.locator.

Parameters

Name	Type	Description
`selector`	string

Returns: Locator

Exceptions

Type	Condition
TestException	`INVALID_LOCATOR`: <code class=“paramref”>selector</code> is empty.

View source

OnDialogAsync(DialogHandler, CancellationToken)

public Task<Func<Task>> OnDialogAsync(DialogHandler handler, CancellationToken cancellationToken = default)

Registers a handler for native dialogs, of every tab, for the rest of the attempt, and returns its unsubscribe. The newest registration answers. A dialog with no handler fails the next step and is dismissed; a handler that returns without calling AcceptAsync(string) or DismissAsync(), or throws, fails the next step with that error, and its dialog is dismissed. Pass Accept or Dismiss to answer them all alike.

Parameters

Name	Type	Description
`handler`	DialogHandler
`cancellationToken`	CancellationToken

Returns: Task<Func<Task>>

View source

`OnDialogAsync(Func<Dialog, Task>, CancellationToken)`

public Task<Func<Task>> OnDialogAsync(Func<Dialog, Task> handler, CancellationToken cancellationToken = default)

Registers a handler that runs <code class=“paramref”>handler</code> for each dialog. See CancellationToken).

Parameters

Name	Type	Description
`handler`	Func<Dialog, Task>
`cancellationToken`	CancellationToken

Returns: Task<Func<Task>>

View source

ReloadAsync(CancellationToken)

public Task ReloadAsync(CancellationToken cancellationToken = default)

Reloads the current document.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task

View source

`RouteAsync(string, Func<WebRoute, Task>, CancellationToken)`

public Task RouteAsync(string pattern, Func<WebRoute, Task> handler, CancellationToken cancellationToken = default)

Adds a network route for the rest of the attempt, matching a complete URL with the glob <code class=“paramref”>pattern</code> that CancellationToken) takes. The route registered last runs first. <code class=“paramref”>handler</code> must take exactly one decision on the WebRoute. A handler that takes none, takes two, or throws fails the next step with that error, and an undecided request is aborted.

Parameters

Name	Type	Description
`pattern`	string
`handler`	Func<WebRoute, Task>
`cancellationToken`	CancellationToken

Returns: Task

View source

`RouteAsync(Regex, Func<WebRoute, Task>, CancellationToken)`

public Task RouteAsync(Regex pattern, Func<WebRoute, Task> handler, CancellationToken cancellationToken = default)

Adds a network route for the URLs <code class=“paramref”>pattern</code> matches. See CancellationToken).

Parameters

Name	Type	Description
`pattern`	Regex
`handler`	Func<WebRoute, Task>
`cancellationToken`	CancellationToken

Returns: Task

View source

`SetCookiesAsync(IReadOnlyList<BrowserCookie>, CancellationToken)`

public Task SetCookiesAsync(IReadOnlyList<BrowserCookie> cookies, CancellationToken cancellationToken = default)

Sets cookies. Each target URL, or the origin a domain cookie is sent to, must pass the URL rule. A relative url resolves against the base URL. A cookie URL that does not parse, or uses a scheme other than http: or https: (about:blank included), is POLICY_DENIED.

Parameters

Name	Type	Description
`cookies`	IReadOnlyList<BrowserCookie>
`cancellationToken`	CancellationToken

Returns: Task

View source

SetViewportAsync(int, int, CancellationToken)

public Task SetViewportAsync(int width, int height, CancellationToken cancellationToken = default)

Sets the viewport size for the rest of the attempt.

Parameters

Name	Type	Description
`width`	int
`height`	int
`cancellationToken`	CancellationToken

Returns: Task

View source

TitleAsync(CancellationToken)

public Task<string> TitleAsync(CancellationToken cancellationToken = default)

Returns the current title. A page that does not answer within the action timeout fails with OPERATION_TIMEOUT.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task<string>

View source

UnrouteAllAsync(CancellationToken)

public Task UnrouteAllAsync(CancellationToken cancellationToken = default)

Removes every route added through this browser. The configured site headers stay.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task

View source

UnrouteAsync(string, CancellationToken)

public Task UnrouteAsync(string pattern, CancellationToken cancellationToken = default)

Removes every route added with the same glob.

Parameters

Name	Type	Description
`pattern`	string
`cancellationToken`	CancellationToken

Returns: Task

View source

UnrouteAsync(Regex, CancellationToken)

public Task UnrouteAsync(Regex pattern, CancellationToken cancellationToken = default)

Removes every route added with a regex of the same source and options.

Parameters

Name	Type	Description
`pattern`	Regex
`cancellationToken`	CancellationToken

Returns: Task

View source

UrlAsync(CancellationToken)

public Task<string> UrlAsync(CancellationToken cancellationToken = default)

Returns the current URL.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task<string>

View source

`WaitForDownloadAsync(Func<Task>, TimeSpan?, CancellationToken)`

public Task<BrowserDownload> WaitForDownloadAsync(Func<Task> trigger, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Runs <code class=“paramref”>trigger</code> and waits for the download it starts, within <code class=“paramref”>timeout</code> (the action timeout by default). The file is kept under the attempt’s downloads artifact folder, as an artifact of this step. A trigger that throws fails the call with its own error, and one that starts no download fails with ACTION_FAILED, naming the wait and how long the trigger took.

Parameters

Name	Type	Description
`trigger`	Func<Task>
`timeout`	TimeSpan?
`cancellationToken`	CancellationToken

Returns: Task<BrowserDownload>

View source

WaitForResponseAsync(string, TimeSpan?, CancellationToken)

public Task<WebResponse> WaitForResponseAsync(string pattern, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Waits for a response whose complete URL matches the glob <code class=“paramref”>pattern</code>: * matches within one path segment, ** crosses /, ? matches one character, and \ escapes the next one. The timeout bounds the match only, and defaults to the action timeout.

Parameters

Name	Type	Description
`pattern`	string
`timeout`	TimeSpan?
`cancellationToken`	CancellationToken

Returns: Task<WebResponse>

View source

WaitForResponseAsync(Regex, TimeSpan?, CancellationToken)

public Task<WebResponse> WaitForResponseAsync(Regex pattern, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Waits for a response whose URL matches <code class=“paramref”>pattern</code>. The timeout bounds the match only, and defaults to the action timeout.

Parameters

Name	Type	Description
`pattern`	Regex
`timeout`	TimeSpan?
`cancellationToken`	CancellationToken

Returns: Task<WebResponse>

View source

WaitForURLAsync(string, TimeSpan?, CancellationToken)

public Task WaitForURLAsync(string url, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Waits until the current URL equals <code class=“paramref”>url</code>, resolved against the base URL, as CancellationToken). The default timeout is the assertion timeout.

Parameters

Name	Type	Description
`url`	string
`timeout`	TimeSpan?
`cancellationToken`	CancellationToken

Returns: Task

View source

WaitForURLAsync(Regex, TimeSpan?, CancellationToken)

public Task WaitForURLAsync(Regex pattern, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Waits until the current URL matches <code class=“paramref”>pattern</code>. The default timeout is the assertion timeout.

Parameters

Name	Type	Description
`pattern`	Regex
`timeout`	TimeSpan?
`cancellationToken`	CancellationToken

Returns: Task

View source