Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion COMPATIBILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ Names are C# versions of the JavaScript API: `agent.act` is `ActAsync`, `screen.

## Error codes that differ

A locator reports an engine failure as upstream's `translateLocatorError` (`LocatorEngine.TranslateLocatorError`, over `ErrorSerializer.TranslateEngineError`, upstream's `translateEngineError`, `internal/errors.ts`) does, with the engine error as `InnerException` and the locator's description added to the message (#846): `NOT_ACTIONABLE` and `ACTION_MAY_HAVE_COMMITTED` are `ACTION_FAILED`, `OPERATION_TIMEOUT` is `ACTION_FAILED` (`operation timed out: <locator>`), `NODE_STALE` and `FRAME_NOT_FOUND` are `LOCATOR_NOT_FOUND`, `FRAME_AMBIGUOUS` is `LOCATOR_AMBIGUOUS`, and `INVALID_STATE` is `APP_NOT_OPEN`. `CANCELLED` is an `EngineException` of that code (`operation cancelled`), `UNSUPPORTED_CAPABILITY` is a `ConfigurationException` (category `configuration`), and `ENGINE_FAILURE`, any other engine code, and an error that is no e2e error are an `EngineException` `ENGINE_FAILURE` (category `infrastructure`), each with the original error as `InnerException`, as upstream's `translateEngineError` wraps them (#885). A recorded browser step maps the engine error it throws the same way (a `Browser` outside a session runs the call bare, like the surface upstream's engine tests call; `Browser.Translated`, upstream's `translated` in `run/fixture-recording.ts`), with ` in <api> <label>` as the suffix, so a timeout reads `operation timed out in browser.goto <url>` or `... in browser.waitForResponse "foo.css"` (#1068). Differences: an `OperationCanceledException` is returned as it is, so a caller's cancel stays a cancel. The port applies the translation to the locator's resolve (including the resolve over an observation) and to its actions; it has no read by reference to translate. `LocatorEngine` (`Locator/LocatorEngine.cs`, upstream's `locator/engine.ts`, #994) owns the resolve, the retries, the deadlines, the engine events, and the operation context a call carries (`OperationContext.Test`); `Screen` and `Locator` pass it their query. Differences: its session is the set of calls in `LocatorEngineOptions` (.NET-only: the attempt reads the screen through its scope), a locate answers the nodes themselves so `read`, `readNow`, `readAllNow`, and `tryRead` read a resolve and have no `session.read` to go stale, `fillSecret` and `pressSequentially` are not engine methods (a secret fill and a typed text are engine actions), and `DeadlineFor` is upstream's `deadline` (`Deadline` is the type's name). `LocatorEngine/` ports the `read retry`, `resolve retry`, `perform`, `readAllNow`, `reads that do not wait`, `translateLocatorError`, `visible queries`, `isNodeVisible`, and `locator failure candidate counts` (`LocatorFailureCandidateCountsTests`) describes; not ported: the its that need `session.read` to go stale (read retry 1 to 3, read contract, readAllNow stale and failure, readNow stale between resolve and read), `secret fill` (no engine `fillSecret`), `AttemptBudget.capped` (no `AttemptBudget`), and the cross-realm describe (no second module registry in .NET). A filtered locator that matches nothing or too many lists the candidates each filter step left (tester-army/e2e#1416, `79e2e13d3365`): `LocatorExpression.FilterSpine()` is `filterSpine` (`locator/expression.ts`), and `LocatorEngine.CandidateCountsAsync` is `candidateCounts`, read by `NotFoundAsync` (`notFound` in `resolveCounted`) and `AmbiguousAsync` (`singleOf`, which replaces `assertSingle`), one immediate resolve per prefix of the chain under one 500 ms budget (`StepCountBudget`, `STEP_COUNT_BUDGET_MS`; `Deadline.Min` is `Deadline.min`). A walk that cannot finish says `walk stopped after N of M steps`, a read that fails drops the list, and a cancel surfaces as cancellation. Differences: the port's failure messages are its own (`<locator> matched 0 nodes.`), so the list follows on a new line (`candidates left after each filter step, counted after the failure:`) where upstream continues after `; `. The five `filterSpine` its are in `Expression/LocatorExpressionsTests`. An action whose engine call finds a retryable stale node resolves the locator again and repeats the action while its deadline remains, as upstream's `performUntil` does; an action that may have committed is never repeated. An action whose deadline passed before it was sent is not sent: it fails with `ACTION_FAILED` (`operation timed out before the tap was sent: <locator>`), as upstream's `lateAction` (#869). Tests: `LocatorEngine/TranslateLocatorErrorMappingTableTests` (the `translateLocatorError mapping table` describe; the seven rows with the port's codes are `Partial_`) and the perform `it`s of `LocatorEngine/LocatorEnginePerformContractTests`. All six perform `it`s are ported; `marks every action it performs with the test origin` runs on the `LocatorEngine` itself (`ScriptedLocatorEngine`, upstream's `makeEngine`), and a .NET-only test checks that `E2ESession` wires that origin to the engine a test's step reaches (`OriginRecordingEngine`).
A locator reports an engine failure as upstream's `translateLocatorError` (`LocatorEngine.TranslateLocatorError`, over `ErrorSerializer.TranslateEngineError`, upstream's `translateEngineError`, `internal/errors.ts`) does, with the engine error as `InnerException` and the locator's description added to the message (#846): `NOT_ACTIONABLE` and `ACTION_MAY_HAVE_COMMITTED` are `ACTION_FAILED`, `OPERATION_TIMEOUT` is `ACTION_FAILED` (`operation timed out: <locator>`), `NODE_STALE` and `FRAME_NOT_FOUND` are `LOCATOR_NOT_FOUND`, `FRAME_AMBIGUOUS` is `LOCATOR_AMBIGUOUS`, and `INVALID_STATE` is `APP_NOT_OPEN`. `CANCELLED` is an `EngineException` of that code (`operation cancelled`), `UNSUPPORTED_CAPABILITY` is a `ConfigurationException` (category `configuration`), and `ENGINE_FAILURE`, any other engine code, and an error that is no e2e error are an `EngineException` `ENGINE_FAILURE` (category `infrastructure`), each with the original error as `InnerException`, as upstream's `translateEngineError` wraps them (#885). A recorded fixture step maps the engine error it throws the same way (`FixtureRecording.Translated`, upstream's `translated` in `run/fixture-recording.ts`), with ` in <api> <label>` as the suffix, so a timeout reads `operation timed out in browser.goto <url>`, `... in browser.waitForResponse "foo.css"`, or `... in app.open /orders` (#1068, #1120). It covers every `Browser` step, every `App` step, and the device fixture's steps (`EngineFixtureContext.RunOperationAsync`, upstream's `FixtureRecorder.run`); a `Browser`, `App`, or fixture outside a session runs the call bare, like the surface upstream's engine tests call. `Browser.OnDialogAsync` and the download waits ask for the browser session inside their step, so an engine with no browser is a `ConfigurationException` there as in `GotoAsync`. A caller's cancel on a web session is an `EngineException` `CANCELLED` (`operation cancelled`), as upstream; screen and locator steps keep their own mapping (`translateLocatorError`). Differences: an `OperationCanceledException` is returned as it is, so a caller's cancel stays a cancel. The port applies the translation to the locator's resolve (including the resolve over an observation) and to its actions; it has no read by reference to translate. `LocatorEngine` (`Locator/LocatorEngine.cs`, upstream's `locator/engine.ts`, #994) owns the resolve, the retries, the deadlines, the engine events, and the operation context a call carries (`OperationContext.Test`); `Screen` and `Locator` pass it their query. Differences: its session is the set of calls in `LocatorEngineOptions` (.NET-only: the attempt reads the screen through its scope), a locate answers the nodes themselves so `read`, `readNow`, `readAllNow`, and `tryRead` read a resolve and have no `session.read` to go stale, `fillSecret` and `pressSequentially` are not engine methods (a secret fill and a typed text are engine actions), and `DeadlineFor` is upstream's `deadline` (`Deadline` is the type's name). `LocatorEngine/` ports the `read retry`, `resolve retry`, `perform`, `readAllNow`, `reads that do not wait`, `translateLocatorError`, `visible queries`, `isNodeVisible`, and `locator failure candidate counts` (`LocatorFailureCandidateCountsTests`) describes; not ported: the its that need `session.read` to go stale (read retry 1 to 3, read contract, readAllNow stale and failure, readNow stale between resolve and read), `secret fill` (no engine `fillSecret`), `AttemptBudget.capped` (no `AttemptBudget`), and the cross-realm describe (no second module registry in .NET). A filtered locator that matches nothing or too many lists the candidates each filter step left (tester-army/e2e#1416, `79e2e13d3365`): `LocatorExpression.FilterSpine()` is `filterSpine` (`locator/expression.ts`), and `LocatorEngine.CandidateCountsAsync` is `candidateCounts`, read by `NotFoundAsync` (`notFound` in `resolveCounted`) and `AmbiguousAsync` (`singleOf`, which replaces `assertSingle`), one immediate resolve per prefix of the chain under one 500 ms budget (`StepCountBudget`, `STEP_COUNT_BUDGET_MS`; `Deadline.Min` is `Deadline.min`). A walk that cannot finish says `walk stopped after N of M steps`, a read that fails drops the list, and a cancel surfaces as cancellation. Differences: the port's failure messages are its own (`<locator> matched 0 nodes.`), so the list follows on a new line (`candidates left after each filter step, counted after the failure:`) where upstream continues after `; `. The five `filterSpine` its are in `Expression/LocatorExpressionsTests`. An action whose engine call finds a retryable stale node resolves the locator again and repeats the action while its deadline remains, as upstream's `performUntil` does; an action that may have committed is never repeated. An action whose deadline passed before it was sent is not sent: it fails with `ACTION_FAILED` (`operation timed out before the tap was sent: <locator>`), as upstream's `lateAction` (#869). Tests: `LocatorEngine/TranslateLocatorErrorMappingTableTests` (the `translateLocatorError mapping table` describe; the seven rows with the port's codes are `Partial_`) and the perform `it`s of `LocatorEngine/LocatorEnginePerformContractTests`. All six perform `it`s are ported; `marks every action it performs with the test origin` runs on the `LocatorEngine` itself (`ScriptedLocatorEngine`, upstream's `makeEngine`), and a .NET-only test checks that `E2ESession` wires that origin to the engine a test's step reaches (`OriginRecordingEngine`).

## Locator actions

Expand Down
2 changes: 1 addition & 1 deletion docs-site/src/content/docs/migrate/playwright.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -353,7 +353,7 @@ A page object that reads `Browser` makes every test that uses it web only. `ILoc
- Text reads are rendered text. On the web, `TextContentAsync()` and `ToHaveTextAsync` read what `innerText` returns, like Playwright's `UseInnerText = true`. Playwright reads the DOM's `textContent` by default. Queries still match the source text: `GetByText("Draft")` finds `<span style="text-transform: uppercase">Draft</span>`, and `ToHaveTextAsync("DRAFT")` passes on it. `Browser.EvaluateAsync` reads the raw DOM text.
- `.Not.ToBeCheckedAsync()` passes on a button or a heading, where Playwright throws, as `IsCheckedAsync()` does. Query a checkable control by role, so the query fails when the control changes kind.
- A negated locator matcher passes only after its condition has been false for 1 s in a row, or for its whole timeout when that is shorter. The positive inverse, such as `ToBeHiddenAsync()`, passes on the first read that holds.
- A `Browser` call that times out fails with `ACTION_FAILED`, and the message names the call: `operation timed out in browser.goto <url>` or `operation timed out in browser.waitForResponse "foo.css"`. Playwright's message, `Timeout 30000ms exceeded.`, is in the `InnerException`.
- A `Browser` call that times out fails with `ACTION_FAILED`, and the message names the call: `operation timed out in browser.goto <url>` or `operation timed out in browser.waitForResponse "foo.css"`. An `App` call does the same (`operation timed out in app.open /orders`). Playwright's message, `Timeout 30000ms exceeded.`, is in the `InnerException`.
- `CheckAsync()` and `UncheckAsync()` read the state back until the action timeout, so a controlled checkbox that updates late passes. A click that removes the control passes too, where Playwright fails. Assert on what replaced it.
- One match or `LOCATOR_AMBIGUOUS`, `IsVisibleAsync()` included, where Playwright reads the first match silently. Narrow with `Filter`, `First()`, or `Visible = true`.
- Navigation opens `http`, `https`, and `about:blank` only. `data:`, `file:`, and every other scheme are `POLICY_DENIED`, whether from `App.OpenAsync`, `Browser.GotoAsync`, or a route's `ContinueAsync` `Url`.
Expand Down
5 changes: 3 additions & 2 deletions skills/e2e-dotnet/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -346,8 +346,9 @@ lines you changed:
- On the web, a swipe is a wheel gesture, as a person scrolls: the viewport swipe wheels by a share of the
viewport, and a node swipe moves the pointer over the node and wheels by a share of its box. A node that
nothing scrollable holds scrolls nothing. `Expect.Soft(screen)` keeps a screenshot failure like `Expect.Soft(locator)`.
- A `Browser` call reports an engine failure the same way, and a timeout names the call:
`operation timed out in browser.goto <url>` or `... in browser.waitForResponse "foo.css"`.
- A `Browser` call, an `App` call, and a device fixture call report an engine failure the same way, and a timeout names the call:
`operation timed out in browser.goto <url>`, `... in browser.waitForResponse "foo.css"`, or `... in app.open /orders`. A browser call on
an engine that has no browser, including `OnDialogAsync` and the download waits, is a `ConfigurationException`.
- A locator reports an engine failure in the test's own codes, with the engine's
error as `InnerException`: `NOT_ACTIONABLE`, `ACTION_MAY_HAVE_COMMITTED`, and
`OPERATION_TIMEOUT` are `ACTION_FAILED` (the timeout reads `operation timed
Expand Down
4 changes: 2 additions & 2 deletions src/E2E/Engine/IEngine.cs
Original file line number Diff line number Diff line change
Expand Up @@ -71,10 +71,10 @@ public sealed class EngineFixtureContext

/// <summary>
/// Runs one fixture call as a recorded step of the attempt (upstream's <c>FixtureRecorder.run</c>, which wraps each operation a fixture
/// declares through <c>fixture</c>). .NET-only: the port's fixtures call it themselves instead of declaring their operations.
/// declares through <c>fixture</c>), mapping the engine error the call throws onto the runner taxonomy. .NET-only: the port's fixtures call it themselves instead of declaring their operations.
/// </summary>
internal Task<T> RunOperationAsync<T>(StepKind kind, string api, string label, Func<Task<T>> body) =>
_screen.RunStepAsync(kind, api, label, body);
_screen.RunStepAsync(kind, api, label, () => FixtureRecording.Translated(api, label, body));

/// <summary>Mints a public locator from a raw expression (a platform selector, say). Upstream's <c>locator</c>.</summary>
public Locator Locator(LocatorExpression expression)
Expand Down
41 changes: 5 additions & 36 deletions src/E2E/Run/Browser.cs
Original file line number Diff line number Diff line change
Expand Up @@ -80,41 +80,11 @@ internal Browser(IEngineSession session, string platform, string? baseUrl, strin
/// fixture runtime); a browser outside a session runs the call as it is, like the bare surface upstream's engine tests call.
/// </summary>
internal Task RunStepAsync(StepKind kind, string api, string label, Func<Task> body, bool verifies = false) =>
Steps is null ? body() : Steps.RunAsync(kind, api, label, () => Translated(api, label, body), new StepRunOptions { Verifies = verifies });
Steps is null ? body() : Steps.RunAsync(kind, api, label, () => FixtureRecording.Translated(api, label, body), new StepRunOptions { Verifies = verifies });

/// <summary>Runs one call that touches the app and returns a value as a recorded step of the attempt, or as it is without a timeline.</summary>
internal Task<T> RunStepAsync<T>(StepKind kind, string api, string label, Func<Task<T>> body, bool verifies = false) =>
Steps is null ? body() : Steps.RunAsync(kind, api, label, () => Translated(api, label, body), new StepRunOptions { Verifies = verifies });

/// <summary>
/// Runs one operation and maps an <see cref="EngineException"/> it rejects with onto the runner taxonomy, as every other engine
/// surface is mapped (upstream's <c>translated</c>). The suffix names the operation and its label, so a timeout says what it
/// waited for. Anything else is rethrown as the call threw it.
/// </summary>
private static async Task Translated(string api, string label, Func<Task> body)
{
try
{
await body().ConfigureAwait(false);
}
catch (EngineException cause)
{
throw ErrorSerializer.TranslateEngineError(cause, " in " + (label == "" ? api : api + " " + label));
}
}

/// <inheritdoc cref="Translated(string, string, Func{Task})"/>
private static async Task<T> Translated<T>(string api, string label, Func<Task<T>> body)
{
try
{
return await body().ConfigureAwait(false);
}
catch (EngineException cause)
{
throw ErrorSerializer.TranslateEngineError(cause, " in " + (label == "" ? api : api + " " + label));
}
}
Steps is null ? body() : Steps.RunAsync(kind, api, label, () => FixtureRecording.Translated(api, label, body), new StepRunOptions { Verifies = verifies });

/// <summary>Tells the attempt that an assertion failed on the app. Nothing outside a session listens.</summary>
internal Action Failed { get; set; } = static () => { };
Expand Down Expand Up @@ -408,9 +378,8 @@ public Task EmulateMediaAsync(WebMedia media, CancellationToken cancellationToke
public async Task<Func<Task>> OnDialogAsync(DialogHandler handler, CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(handler);
var session = Require("onDialog");
Action unsubscribe = static () => { };
await RunStepAsync(StepKind.Resource, "browser.onDialog", "", async () => unsubscribe = await session.OnDialogAsync(handler, Token(cancellationToken)).ConfigureAwait(false)).ConfigureAwait(false);
await RunStepAsync(StepKind.Resource, "browser.onDialog", "", async () => unsubscribe = await Require("onDialog").OnDialogAsync(handler, Token(cancellationToken)).ConfigureAwait(false)).ConfigureAwait(false);
return () =>
{
unsubscribe();
Expand All @@ -436,10 +405,10 @@ public Task<Func<Task>> OnDialogAsync(Func<Dialog, Task> handler, CancellationTo
public async Task<BrowserDownload> WaitForDownloadAsync(Func<Task> trigger, TimeSpan? timeout = null, CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(trigger);
var session = Require("waitForDownload");
BrowserDownload? download = null;
await RunStepAsync(StepKind.Resource, "browser.waitForDownload", "", async () =>
{
var session = Require("waitForDownload");
var budget = StepBudget(timeout, "browser.waitForDownload");
download = await AppNotOpen.GuardAsync(() => session.WaitForDownloadAsync(trigger, budget, Token(cancellationToken))).ConfigureAwait(false);
Attach("download", download.Path);
Expand All @@ -459,10 +428,10 @@ await RunStepAsync(StepKind.Resource, "browser.waitForDownload", "", async () =>
public async Task<IReadOnlyList<BrowserDownload>> WaitForDownloadsAsync(Func<Task> trigger, int count, TimeSpan? timeout = null, CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(trigger);
var session = Require("waitForDownloads");
IReadOnlyList<BrowserDownload> downloads = [];
await RunStepAsync(StepKind.Resource, "browser.waitForDownloads", "", async () =>
{
var session = Require("waitForDownloads");
if (count < 1)
{
throw new TestException("INVALID_ARGUMENT", "waitForDownloads: count must be a positive safe integer");
Expand Down
Loading
Loading