From afa29e1f99b7131b2463404d802b36a049af6d35 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 21:10:55 +0000 Subject: [PATCH] Add WebFixtures (Browser, WebApp.BaseUrl) for IEngine on WebEngine (upstream #1734) Closes #1699 Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Ls2e1zrGq2gUwMKsCiCozN --- docs-site/public/api/E2E.Engine.WebApp.html | 13 ++++ .../public/api/E2E.Engine.WebFixtures.html | 13 ++++ .../content/docs/api/E2E.Engine/IEngine-1.md | 11 ++-- .../src/content/docs/api/E2E.Engine/WebApp.md | 43 ++++++++++++++ .../content/docs/api/E2E.Engine/WebEngine.md | 26 +++++++- .../docs/api/E2E.Engine/WebFixtures.md | 59 +++++++++++++++++++ .../src/content/docs/api/E2E.Engine/index.md | 2 + docs-site/src/content/docs/api/E2E/App.md | 4 +- docs-site/src/content/docs/docs/core.mdx | 2 +- skills/e2e-dotnet/references/host.md | 2 +- src/E2E.Mobile/MobileEngine.cs | 2 +- src/E2E/Core/Launch.cs | 4 +- src/E2E/Engine/IEngine.cs | 4 +- src/E2E/Engine/WebEngine.cs | 11 +++- src/E2E/Engine/WebFixtures.cs | 34 +++++++++++ src/E2E/Run/Fixtures.cs | 21 ++++++- tests/E2E.Tests/Core/CoreFakeEngine.cs | 2 +- 17 files changed, 236 insertions(+), 17 deletions(-) create mode 100644 docs-site/public/api/E2E.Engine.WebApp.html create mode 100644 docs-site/public/api/E2E.Engine.WebFixtures.html create mode 100644 docs-site/src/content/docs/api/E2E.Engine/WebApp.md create mode 100644 docs-site/src/content/docs/api/E2E.Engine/WebFixtures.md create mode 100644 src/E2E/Engine/WebFixtures.cs diff --git a/docs-site/public/api/E2E.Engine.WebApp.html b/docs-site/public/api/E2E.Engine.WebApp.html new file mode 100644 index 000000000..6e296ede9 --- /dev/null +++ b/docs-site/public/api/E2E.Engine.WebApp.html @@ -0,0 +1,13 @@ + + + + + + +Redirecting… + + + +

Continue

+ + diff --git a/docs-site/public/api/E2E.Engine.WebFixtures.html b/docs-site/public/api/E2E.Engine.WebFixtures.html new file mode 100644 index 000000000..82a02157b --- /dev/null +++ b/docs-site/public/api/E2E.Engine.WebFixtures.html @@ -0,0 +1,13 @@ + + + + + + +Redirecting… + + + +

Continue

+ + diff --git a/docs-site/src/content/docs/api/E2E.Engine/IEngine-1.md b/docs-site/src/content/docs/api/E2E.Engine/IEngine-1.md index b8268ee4e..541edca34 100644 --- a/docs-site/src/content/docs/api/E2E.Engine/IEngine-1.md +++ b/docs-site/src/content/docs/api/E2E.Engine/IEngine-1.md @@ -28,27 +28,30 @@ Upstream's `EngineHandle` (`defineEngine`). | --- | --- | | `TFixtures` | What a session on this engine holds beside `Screen` and `App`, such as `Device` on a mobile engine. | +**Derived:** [WebEngine](/api/E2E.Engine/WebEngine/) + [View source](https://github.com/hardkoded/e2e-dotnet/blob/main/src/E2E/Engine/IEngine.cs) ## Methods - + -### CreateFixtures(IEngineSession) +### CreateFixtures(IEngineSession, Session) ```csharp -TFixtures CreateFixtures(IEngineSession session) +TFixtures CreateFixtures(IEngineSession session, Session controls) ``` -The fixtures of one session, over the engine's own <code class="paramref">session</code>. +The fixtures of one session, over the engine's own <code class="paramref">session</code> and the <code class="paramref">controls</code> the harness built (its `Browser` and `App`). **Parameters** | Name | Type | Description | | --- | --- | --- | | `session` | [IEngineSession](/api/E2E.Engine/IEngineSession/) | | +| `controls` | [Session](/api/E2E/Session/) | | **Returns:** `TFixtures` diff --git a/docs-site/src/content/docs/api/E2E.Engine/WebApp.md b/docs-site/src/content/docs/api/E2E.Engine/WebApp.md new file mode 100644 index 000000000..241bb78b9 --- /dev/null +++ b/docs-site/src/content/docs/api/E2E.Engine/WebApp.md @@ -0,0 +1,43 @@ +--- +title: "WebApp" +description: "App on a web target. A WebEngine target always declares app.url, so BaseUrl is always set. Upstream's WebApp (web/fixtures.ts)." +editUrl: false +prev: false +next: false +sidebar: + label: "WebApp" + hidden: true +--- + + + +Namespace: [E2E.Engine](/api/E2E.Engine/) + + +```csharp +public sealed class WebApp : App +``` + + +`App` on a web target. A [WebEngine](/api/E2E.Engine/WebEngine/) target always declares `app.url`, so [BaseUrl](#E2E_Engine_WebApp_BaseUrl) is always set. Upstream's `WebApp` (`web/fixtures.ts`). + +**Inheritance:** [object](https://learn.microsoft.com/dotnet/api/system.object) → [App](/api/E2E/App/) + +[View source](https://github.com/hardkoded/e2e-dotnet/blob/main/src/E2E/Engine/WebFixtures.cs) + +## Properties + + + + +### BaseUrl + + +```csharp +public string BaseUrl { get; } +``` + + +The target's `app.url` with the run's port and no trailing slash: `$"{app.BaseUrl}/api/users"`. + +**Value:** [string](https://learn.microsoft.com/dotnet/api/system.string) diff --git a/docs-site/src/content/docs/api/E2E.Engine/WebEngine.md b/docs-site/src/content/docs/api/E2E.Engine/WebEngine.md index 109d176c0..fcc9d6a1f 100644 --- a/docs-site/src/content/docs/api/E2E.Engine/WebEngine.md +++ b/docs-site/src/content/docs/api/E2E.Engine/WebEngine.md @@ -15,7 +15,7 @@ Namespace: [E2E.Engine](/api/E2E.Engine/) ```csharp -public sealed class WebEngine : IDoctorEngine, IEngine, IAsyncDisposable +public sealed class WebEngine : IEngine, IDoctorEngine, IEngine, IAsyncDisposable ``` @@ -26,7 +26,7 @@ same node actions the document engine does. Install browsers once with **Inheritance:** [object](https://learn.microsoft.com/dotnet/api/system.object) -**Implements:** [IDoctorEngine](/api/E2E.Engine/IDoctorEngine/), [IEngine](/api/E2E.Engine/IEngine/), [IAsyncDisposable](https://learn.microsoft.com/dotnet/api/system.iasyncdisposable) +**Implements:** `IEngine<WebFixtures>`, [IDoctorEngine](/api/E2E.Engine/IDoctorEngine/), [IEngine](/api/E2E.Engine/IEngine/), [IAsyncDisposable](https://learn.microsoft.com/dotnet/api/system.iasyncdisposable) [View source](https://github.com/hardkoded/e2e-dotnet/blob/main/src/E2E/obj/Release/net10.0/System.Text.RegularExpressions.Generator/System.Text.RegularExpressions.Generator.RegexGenerator/RegexGenerator.g.cs) @@ -137,6 +137,28 @@ public string Version { get; } ## Methods + + + +### CreateFixtures(IEngineSession, Session) + + +```csharp +public WebFixtures CreateFixtures(IEngineSession session, Session controls) +``` + + +The fixtures of a session on this engine: its `Browser` and its `App` with the base URL set. A web target always declares `app.url`, so a session with none is a `WORKER_PROTOCOL` failure. + +**Parameters** + +| Name | Type | Description | +| --- | --- | --- | +| `session` | [IEngineSession](/api/E2E.Engine/IEngineSession/) | | +| `controls` | [Session](/api/E2E/Session/) | | + +**Returns:** [WebFixtures](/api/E2E.Engine/WebFixtures/) + diff --git a/docs-site/src/content/docs/api/E2E.Engine/WebFixtures.md b/docs-site/src/content/docs/api/E2E.Engine/WebFixtures.md new file mode 100644 index 000000000..85b66c090 --- /dev/null +++ b/docs-site/src/content/docs/api/E2E.Engine/WebFixtures.md @@ -0,0 +1,59 @@ +--- +title: "WebFixtures" +description: "What a session on a WebEngine holds beside Screen: the Browser fixture, and App with its BaseUrl always set. Read it from Fixtures. Upstream's WebFixtures (w..." +editUrl: false +prev: false +next: false +sidebar: + label: "WebFixtures" + hidden: true +--- + + + +Namespace: [E2E.Engine](/api/E2E.Engine/) + + +```csharp +public sealed class WebFixtures +``` + + +What a session on a [WebEngine](/api/E2E.Engine/WebEngine/) holds beside `Screen`: the [Browser](#E2E_Engine_WebFixtures_Browser) fixture, and [App](#E2E_Engine_WebFixtures_App) with its +[BaseUrl](/api/E2E.Engine/WebApp/#E2E_Engine_WebApp_BaseUrl) always set. Read it from `Fixtures`. Upstream's `WebFixtures` (`web/fixtures.ts`). + +**Inheritance:** [object](https://learn.microsoft.com/dotnet/api/system.object) + +[View source](https://github.com/hardkoded/e2e-dotnet/blob/main/src/E2E/Engine/WebFixtures.cs) + +## Properties + + + + +### App + + +```csharp +public WebApp App { get; } +``` + + +The app, with its base URL always set. + +**Value:** [WebApp](/api/E2E.Engine/WebApp/) + + + + +### Browser + + +```csharp +public Browser Browser { get; } +``` + + +The browser fixture. + +**Value:** [Browser](/api/E2E/Browser/) diff --git a/docs-site/src/content/docs/api/E2E.Engine/index.md b/docs-site/src/content/docs/api/E2E.Engine/index.md index f6000322f..989dff8b5 100644 --- a/docs-site/src/content/docs/api/E2E.Engine/index.md +++ b/docs-site/src/content/docs/api/E2E.Engine/index.md @@ -121,10 +121,12 @@ Public types in the `E2E.Engine` namespace. | [VideoFile](/api/E2E.Engine/VideoFile/) | A video file in the attempt artifact directory. | | [VideoLink](/api/E2E.Engine/VideoLink/) | A recording a hosted service keeps, by URL: the report links to it and the runner never downloads it. | | [VideoSegment](/api/E2E.Engine/VideoSegment/) | One recorded video of an attempt: a file the engine wrote into the attempt artifact directory (VideoFile), or a recording a hosted service keeps and links to (VideoLink). | +| [WebApp](/api/E2E.Engine/WebApp/) | App on a web target. A WebEngine target always declares app.url, so BaseUrl is always set. Upstream's WebApp (web/fixtures.ts). | | [WebBasicAuth](/api/E2E.Engine/WebBasicAuth/) | HTTP basic authentication the browser answers a 401 challenge with. | | [WebConnectOptions](/api/E2E.Engine/WebConnectOptions/) | Attach to a remote Chromium over CDP instead of launching one. Supplying ReconnectEndpoint opts into a persistent context instead. | | [WebEngine](/api/E2E.Engine/WebEngine/) | Browser engine for the web target. It drives Chromium, Firefox, or WebKit through Playwright, reads a semantic tree (role, name, text, test id, state), and performs the same node actions the document engine does. Install browsers once with playwright.ps1 install chromium (or firefox, webkit) from this project's build output. | | [WebEngineOptions](/api/E2E.Engine/WebEngineOptions/) | Options of the browser engine: how it drives the app. | +| [WebFixtures](/api/E2E.Engine/WebFixtures/) | What a session on a WebEngine holds beside Screen: the Browser fixture, and App with its BaseUrl always set. Read it from Fixtures. Upstream's WebFixtures (web/fixtures.ts). | | [WebInitScript](/api/E2E.Engine/WebInitScript/) | A script every document runs before the page's own, in every tab and frame: JavaScript source, a file of it, or a function source the page calls. A string converts to source. | | [WebMedia](/api/E2E.Engine/WebMedia/) | User preferences a page reads through @media rules and matchMedia, as Playwright's emulateMedia sets them. A feature left null keeps the browser's own value, or the one an earlier call set. | | [WebRouteRequest](/api/E2E.Engine/WebRouteRequest/) | The request a route intercepted. | diff --git a/docs-site/src/content/docs/api/E2E/App.md b/docs-site/src/content/docs/api/E2E/App.md index da0dbffeb..c1ac87455 100644 --- a/docs-site/src/content/docs/api/E2E/App.md +++ b/docs-site/src/content/docs/api/E2E/App.md @@ -15,7 +15,7 @@ Namespace: [E2E](/api/E2E/) ```csharp -public sealed class App +public class App ``` @@ -24,6 +24,8 @@ Opens and resets the app under test. A relative URL is resolved against **Inheritance:** [object](https://learn.microsoft.com/dotnet/api/system.object) +**Derived:** [WebApp](/api/E2E.Engine/WebApp/) + [View source](https://github.com/hardkoded/e2e-dotnet/blob/main/src/E2E/Run/Fixtures.cs) ## Properties diff --git a/docs-site/src/content/docs/docs/core.mdx b/docs-site/src/content/docs/docs/core.mdx index 64f15df9d..27f0fe8be 100644 --- a/docs-site/src/content/docs/docs/core.mdx +++ b/docs-site/src/content/docs/docs/core.mdx @@ -9,7 +9,7 @@ import { Aside } from '@astrojs/starlight/components'; ## Drive a browser -`Launch.LaunchAsync` prepares an engine and returns a `Host`. A `Session` is one isolated browser context on that host, and it holds `Screen`, `App`, `Platform`, and `Browser`. An engine that contributes fixtures (`IEngine`, such as `MobileEngine` with `MobileFixtures`) makes `LaunchAsync` return a `Host` whose sessions are `Session`: `session.Fixtures.Device` is the device fixture. +`Launch.LaunchAsync` prepares an engine and returns a `Host`. A `Session` is one isolated browser context on that host, and it holds `Screen`, `App`, `Platform`, and `Browser`. An engine that contributes fixtures (`IEngine`, such as `MobileEngine` with `MobileFixtures`) makes `LaunchAsync` return a `Host` whose sessions are `Session`: `session.Fixtures.Device` is the device fixture. `WebEngine` is one too (`WebFixtures`): `session.Fixtures.Browser` is the browser fixture, and `session.Fixtures.App` is a `WebApp`, the `App` with `BaseUrl` always set, since a web target always declares `app.url`. ```csharp using E2E; diff --git a/skills/e2e-dotnet/references/host.md b/skills/e2e-dotnet/references/host.md index 6994e9ab9..27d34d786 100644 --- a/skills/e2e-dotnet/references/host.md +++ b/skills/e2e-dotnet/references/host.md @@ -82,7 +82,7 @@ trace mode. The page stands alone: it has no `report.json` to point at. ## Launch without a config or a runner For a script, a scraper, or a bot there is no config file and no report: `Launch.LaunchAsync` (upstream's `launch` from `@e2e-dev/core`) takes an engine and -the app, and returns a `Host` that opens one `Session` at a time. A session holds `Screen`, `App`, `Platform`, and `Browser`. An engine that contributes fixtures (`IEngine`, such as `MobileEngine` with `MobileFixtures`) makes `LaunchAsync` return a `Host` whose sessions are `Session`: `session.Fixtures.Device` is the device fixture. +the app, and returns a `Host` that opens one `Session` at a time. A session holds `Screen`, `App`, `Platform`, and `Browser`. An engine that contributes fixtures (`IEngine`, such as `MobileEngine` with `MobileFixtures`) makes `LaunchAsync` return a `Host` whose sessions are `Session`: `session.Fixtures.Device` is the device fixture. `WebEngine` is one too (`WebFixtures`): `session.Fixtures.Browser` is the browser fixture, and `session.Fixtures.App` is a `WebApp`, the `App` with `BaseUrl` always set, since a web target always declares `app.url`. ```csharp await using var shop = await Launch.LaunchAsync(new WebEngine(), new LaunchOptions diff --git a/src/E2E.Mobile/MobileEngine.cs b/src/E2E.Mobile/MobileEngine.cs index 1692a435c..203b7a4f7 100644 --- a/src/E2E.Mobile/MobileEngine.cs +++ b/src/E2E.Mobile/MobileEngine.cs @@ -85,7 +85,7 @@ public sealed partial class MobileEngine : IPreparableEngine, IDisposableEngine, public const string EngineVersion = "0.11.0"; /// The fixtures of a session on this engine: its Device. A session no device engine started is a WORKER_PROTOCOL failure. - public MobileFixtures CreateFixtures(IEngineSession session) => + public MobileFixtures CreateFixtures(IEngineSession session, Session controls) => session is DeviceSession device ? new MobileFixtures(device.Device) : throw new EngineException("WORKER_PROTOCOL", "a mobile engine builds its fixtures from the device session it started"); diff --git a/src/E2E/Core/Launch.cs b/src/E2E/Core/Launch.cs index 74cb06e59..c0235f3cc 100644 --- a/src/E2E/Core/Launch.cs +++ b/src/E2E/Core/Launch.cs @@ -170,9 +170,9 @@ private async Task CloseOnceAsync() public sealed class Session : Session where TFixtures : class { - internal Session(StandaloneAttempt attempt, StateIdentity identity, Action onClosed, Func fixtures) + internal Session(StandaloneAttempt attempt, StateIdentity identity, Action onClosed, Func fixtures) : base(attempt, identity, onClosed) => - Fixtures = fixtures(EngineSession); + Fixtures = fixtures(EngineSession, this); /// What the engine contributes beside , , and . public TFixtures Fixtures { get; } diff --git a/src/E2E/Engine/IEngine.cs b/src/E2E/Engine/IEngine.cs index d3dc4cedd..0d4c1a6ee 100644 --- a/src/E2E/Engine/IEngine.cs +++ b/src/E2E/Engine/IEngine.cs @@ -129,8 +129,8 @@ public interface IEngineFixtureHost public interface IEngine : IEngine where TFixtures : class { - /// The fixtures of one session, over the engine's own . - TFixtures CreateFixtures(IEngineSession session); + /// The fixtures of one session, over the engine's own and the the harness built (its Browser and App). + TFixtures CreateFixtures(IEngineSession session, Session controls); } /// Passed to once per test attempt. diff --git a/src/E2E/Engine/WebEngine.cs b/src/E2E/Engine/WebEngine.cs index 6e555415a..22f0066f8 100644 --- a/src/E2E/Engine/WebEngine.cs +++ b/src/E2E/Engine/WebEngine.cs @@ -278,8 +278,17 @@ public sealed class WebEngineOptions /// same node actions the document engine does. Install browsers once with /// playwright.ps1 install chromium (or firefox, webkit) from this project's build output. /// -public sealed partial class WebEngine : IEngine +public sealed partial class WebEngine : IEngine, IEngine { + /// The fixtures of a session on this engine: its Browser and its App with the base URL set. A web target always declares app.url, so a session with none is a WORKER_PROTOCOL failure. + public WebFixtures CreateFixtures(IEngineSession session, Session controls) + { + ArgumentNullException.ThrowIfNull(controls); + return new WebFixtures( + controls.Browser, + new WebApp(controls.App, controls.App.BaseUrl ?? throw new EngineException("WORKER_PROTOCOL", "a web target always declares app.url"))); + } + public const string EngineVersion = "1.1.0"; private const string SkipInstallVariable = "E2E_SKIP_BROWSER_INSTALL"; diff --git a/src/E2E/Engine/WebFixtures.cs b/src/E2E/Engine/WebFixtures.cs new file mode 100644 index 000000000..3f88322e1 --- /dev/null +++ b/src/E2E/Engine/WebFixtures.cs @@ -0,0 +1,34 @@ +// Copyright 2026 TesterArmy. +// Modified by Dario Kondratiuk. +// SPDX-License-Identifier: Apache-2.0 + +namespace E2E.Engine; + +/// App on a web target. A target always declares app.url, so is always set. Upstream's WebApp (web/fixtures.ts). +public sealed class WebApp : App +{ + internal WebApp(App app, string baseUrl) + : base(app) => BaseUrl = baseUrl; + + /// The target's app.url with the run's port and no trailing slash: $"{app.BaseUrl}/api/users". + public new string BaseUrl { get; } +} + +/// +/// What a session on a holds beside Screen: the fixture, and with its +/// always set. Read it from . Upstream's WebFixtures (web/fixtures.ts). +/// +public sealed class WebFixtures +{ + internal WebFixtures(Browser browser, WebApp app) + { + Browser = browser; + App = app; + } + + /// The browser fixture. + public Browser Browser { get; } + + /// The app, with its base URL always set. + public WebApp App { get; } +} diff --git a/src/E2E/Run/Fixtures.cs b/src/E2E/Run/Fixtures.cs index 2d4f72312..e775e7e86 100644 --- a/src/E2E/Run/Fixtures.cs +++ b/src/E2E/Run/Fixtures.cs @@ -39,7 +39,7 @@ internal interface IArtifactSink /// Opens and resets the app under test. A relative URL is resolved against /// ; no URL opens the base URL. /// -public sealed class App +public class App { private readonly IEngineSession _session; private readonly string? _baseUrl; @@ -67,6 +67,25 @@ internal App(IEngineSession session, string? baseUrl, Func to _steps = steps; } + /// Copies an app, which extends (upstream's WebApp extends App). + private protected App(App other) + { + _session = other._session; + _baseUrl = other._baseUrl; + _token = other._token; + _steps = other._steps; + _pinnedApp = other._pinnedApp; + _target = other._target; + _linkBase = other._linkBase; + OperationBudget = other.OperationBudget; + LifecycleBudget = other.LifecycleBudget; + Recordings = other.Recordings; + SinkOf = other.SinkOf; + ArtifactsDir = other.ArtifactsDir; + Redact = other.Redact; + Attach = other.Attach; + } + /// /// The resolved base URL of the target's app, with the port the run allocated when app.url declared port 0 and no trailing /// slash, so $"{BaseUrl}/api/users" joins with one slash; null when the test declares none. still diff --git a/tests/E2E.Tests/Core/CoreFakeEngine.cs b/tests/E2E.Tests/Core/CoreFakeEngine.cs index d3145a9f1..d2de16dc2 100644 --- a/tests/E2E.Tests/Core/CoreFakeEngine.cs +++ b/tests/E2E.Tests/Core/CoreFakeEngine.cs @@ -82,7 +82,7 @@ public IReadOnlyList OpenedLinks public EngineCapabilities Capabilities { get; } /// Contributes the gadget fixture. Upstream's fixtures: true. - public CoreFakeFixtures CreateFixtures(IEngineSession session) => new("gadget on " + Platform); + public CoreFakeFixtures CreateFixtures(IEngineSession session, E2E.Session controls) => new("gadget on " + Platform); public Task StartAsync(EngineStartOptions options, CancellationToken cancellationToken) {