From 97c97505ac24e2a7faaa9392cd08929077024928 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 20:32:35 +0000 Subject: [PATCH] Type a host and a session by the fixtures of their engine (upstream #1734) Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Ls2e22Vkrdd6oNeFajzj4G --- .../public/api/E2E.Engine.IEngine-1.html | 13 ++ docs-site/public/api/E2E.Host-1.html | 13 ++ docs-site/public/api/E2E.Session-1.html | 13 ++ .../docs/api/E2E.Engine/EngineStartOptions.md | 3 +- .../docs/api/E2E.Engine/IBrowserProvider.md | 4 +- .../content/docs/api/E2E.Engine/IEngine-1.md | 54 ++++++++ .../src/content/docs/api/E2E.Engine/index.md | 1 + .../content/docs/api/E2E/E2ESessionOptions.md | 2 +- docs-site/src/content/docs/api/E2E/Host-1.md | 126 ++++++++++++++++++ docs-site/src/content/docs/api/E2E/Launch.md | 29 ++++ .../src/content/docs/api/E2E/LaunchOptions.md | 5 +- .../src/content/docs/api/E2E/ScriptedModel.md | 2 +- .../src/content/docs/api/E2E/Session-1.md | 53 ++++++++ docs-site/src/content/docs/api/E2E/Session.md | 24 +++- docs-site/src/content/docs/api/E2E/index.md | 2 + docs-site/src/content/docs/docs/core.mdx | 2 +- skills/e2e-dotnet/references/host.md | 2 +- src/E2E.Mobile/MobileEngine.cs | 8 +- src/E2E.Mobile/MobileFixtures.cs | 18 +++ src/E2E/Core/Launch.cs | 78 ++++++++++- src/E2E/Engine/IEngine.cs | 12 ++ tests/E2E.Tests/Core/CoreFakeEngine.cs | 8 +- tests/E2E.Tests/Core/CoreTests.cs | 29 ++-- 23 files changed, 476 insertions(+), 25 deletions(-) create mode 100644 docs-site/public/api/E2E.Engine.IEngine-1.html create mode 100644 docs-site/public/api/E2E.Host-1.html create mode 100644 docs-site/public/api/E2E.Session-1.html create mode 100644 docs-site/src/content/docs/api/E2E.Engine/IEngine-1.md create mode 100644 docs-site/src/content/docs/api/E2E/Host-1.md create mode 100644 docs-site/src/content/docs/api/E2E/Session-1.md create mode 100644 src/E2E.Mobile/MobileFixtures.cs diff --git a/docs-site/public/api/E2E.Engine.IEngine-1.html b/docs-site/public/api/E2E.Engine.IEngine-1.html new file mode 100644 index 00000000..6be67e99 --- /dev/null +++ b/docs-site/public/api/E2E.Engine.IEngine-1.html @@ -0,0 +1,13 @@ + + + + + + +Redirecting… + + + +

Continue

+ + diff --git a/docs-site/public/api/E2E.Host-1.html b/docs-site/public/api/E2E.Host-1.html new file mode 100644 index 00000000..71c0569f --- /dev/null +++ b/docs-site/public/api/E2E.Host-1.html @@ -0,0 +1,13 @@ + + + + + + +Redirecting… + + + +

Continue

+ + diff --git a/docs-site/public/api/E2E.Session-1.html b/docs-site/public/api/E2E.Session-1.html new file mode 100644 index 00000000..da376c59 --- /dev/null +++ b/docs-site/public/api/E2E.Session-1.html @@ -0,0 +1,13 @@ + + + + + + +Redirecting… + + + +

Continue

+ + diff --git a/docs-site/src/content/docs/api/E2E.Engine/EngineStartOptions.md b/docs-site/src/content/docs/api/E2E.Engine/EngineStartOptions.md index 5d992285..1d46e947 100644 --- a/docs-site/src/content/docs/api/E2E.Engine/EngineStartOptions.md +++ b/docs-site/src/content/docs/api/E2E.Engine/EngineStartOptions.md @@ -178,7 +178,8 @@ public bool Headed { get; init; } ``` -Whether the run asked for a visible surface (`--headed`). .NET-only place: upstream hands it to `init` ([Headed](/api/E2E.Engine/EngineInitInfo/#E2E_Engine_EngineInitInfo_Headed)), which the port does not call per worker, so a session start carries it. +Whether the run asked for a visible surface (`--headed`). .NET-only place: upstream hands it to `init` ([Headed](/api/E2E.Engine/EngineInitInfo/#E2E_Engine_EngineInitInfo_Headed)), +which the port does not call per worker, so a session start carries it. **Value:** [bool](https://learn.microsoft.com/dotnet/api/system.boolean) diff --git a/docs-site/src/content/docs/api/E2E.Engine/IBrowserProvider.md b/docs-site/src/content/docs/api/E2E.Engine/IBrowserProvider.md index 2d488b9e..54038577 100644 --- a/docs-site/src/content/docs/api/E2E.Engine/IBrowserProvider.md +++ b/docs-site/src/content/docs/api/E2E.Engine/IBrowserProvider.md @@ -185,8 +185,8 @@ Task> SweepAsync(BrowserReleaseContext context, Cancellati Releases every lease of the run and target the provider still holds open, and resolves to their ids. Called once per target from finish, in the runner, after every worker exited and the leases prepare made were released: whatever it finds is a lease a worker acquired (a per-attempt browser, a replacement) and never gave back, -because the worker died before it could. Find them by what acquire tagged them with at the service: the run id -and the target. +because the worker died before it could. Find them by service tags or a shared journal scoped to the run id and +target. **Parameters** 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 new file mode 100644 index 00000000..b8268ee4 --- /dev/null +++ b/docs-site/src/content/docs/api/E2E.Engine/IEngine-1.md @@ -0,0 +1,54 @@ +--- +title: "IEngine" +description: "An engine that contributes fixtures to the sessions opened on it, which LaunchAsync types a host and its sessions by. Upstream's EngineHandle (d..." +editUrl: false +prev: false +next: false +sidebar: + label: "IEngine" + hidden: true +--- + + + +Namespace: [E2E.Engine](/api/E2E.Engine/) + + +```csharp +public interface IEngine : IEngine where TFixtures : class +``` + + +An engine that contributes fixtures to the sessions opened on it, which `LaunchAsync<T>` types a host and its sessions by. +Upstream's `EngineHandle` (`defineEngine`). + +**Type parameters** + +| Name | Description | +| --- | --- | +| `TFixtures` | What a session on this engine holds beside `Screen` and `App`, such as `Device` on a mobile engine. | + +[View source](https://github.com/hardkoded/e2e-dotnet/blob/main/src/E2E/Engine/IEngine.cs) + +## Methods + + + + +### CreateFixtures(IEngineSession) + + +```csharp +TFixtures CreateFixtures(IEngineSession session) +``` + + +The fixtures of one session, over the engine's own <code class="paramref">session</code>. + +**Parameters** + +| Name | Type | Description | +| --- | --- | --- | +| `session` | [IEngineSession](/api/E2E.Engine/IEngineSession/) | | + +**Returns:** `TFixtures` 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 a1ab006a..f6000322 100644 --- a/docs-site/src/content/docs/api/E2E.Engine/index.md +++ b/docs-site/src/content/docs/api/E2E.Engine/index.md @@ -148,6 +148,7 @@ Public types in the `E2E.Engine` namespace. | [IDisposableEngine](/api/E2E.Engine/IDisposableEngine/) | An engine with upstream's optional dispose hook (declared in engine/index.ts): worker shutdown within the cleanup budget, where the engine releases what its workers hold, or keeps the run-owned part of it when ReuseSignal is live. .NET-only name: upstream's engine has the member in the same contract as prepare and finish. | | [IDoctorEngine](/api/E2E.Engine/IDoctorEngine/) | An engine with upstream's optional doctor hook (declared in engine/index.ts): what e2e doctor asks once per target, instead of starting a run. Without it the target gets one engine check with status skip. .NET-only name: upstream's Engine declares the member, and the port keeps its optional hooks in their own interfaces (IPreparableEngine), so an engine without the hook compiles unchanged. | | [IEngine](/api/E2E.Engine/IEngine/) | The body of one target. Core knows this contract and never an engine's internals. Version is the engine version. It is not part of the replay cache key: a recording re-finds its nodes at replay. | +| [IEngine<TFixtures>](/api/E2E.Engine/IEngine-1/) | An engine that contributes fixtures to the sessions opened on it, which LaunchAsync<T> types a host and its sessions by. Upstream's EngineHandle (defineEngine). | | [IEngineFixtureHost](/api/E2E.Engine/IEngineFixtureHost/) | An engine session that contributes a fixture, which the harness tells about the attempt when it starts. .NET-only: upstream's engine declares fixtures, factories the harness calls with an EngineFixtureContext; the port's session builds its own fixture (Device), so this hands it the context. | | [IEngineSession](/api/E2E.Engine/IEngineSession/) | One attempt's session with the app. Disposed at the end of the attempt, after afterEach. | | [IPreparableEngine](/api/E2E.Engine/IPreparableEngine/) | An engine with upstream's optional prepare and finish hooks (declared in engine/index.ts): what a run provisions once per target before any worker starts, such as a hosted device, and gives back after the last worker ended, so the provisioning happens once per run instead of per worker. The run's own path calls them: Runner.RunAsync and the run fixtures of E2E.NUnit and E2E.XUnit.V3 prepare each engine once and finish it when the run ends, and a host that starts the engine on its own, as e2e explore and e2e mcp do, calls them around the one attempt (upstream's openStandaloneAttempt), prepare when the session opens and finish when it closes, on every path. .NET-only name: upstream tests the engine handle for the members. WebEngine does not implement it, because it leases for the attempt it starts. | diff --git a/docs-site/src/content/docs/api/E2E/E2ESessionOptions.md b/docs-site/src/content/docs/api/E2E/E2ESessionOptions.md index 105ec33c..85d6e211 100644 --- a/docs-site/src/content/docs/api/E2E/E2ESessionOptions.md +++ b/docs-site/src/content/docs/api/E2E/E2ESessionOptions.md @@ -424,7 +424,7 @@ public string? LinkBase { get; init; } ``` -The target's `app.linkBase`, which `App.OpenAsync(path)` joins a path to on a device. It applies only to a pinned app with no [BaseUrl](/api/E2E/E2ESessionOptions/#E2E_E2ESessionOptions_BaseUrl); with a base URL a path resolves against that URL. +The target's `app.linkBase`, which `App.OpenAsync(path)` joins a path to on a device. It applies only to a pinned app with no [BaseUrl](#E2E_E2ESessionOptions_BaseUrl); with a base URL a path resolves against that URL. **Value:** [string](https://learn.microsoft.com/dotnet/api/system.string) diff --git a/docs-site/src/content/docs/api/E2E/Host-1.md b/docs-site/src/content/docs/api/E2E/Host-1.md new file mode 100644 index 00000000..ebcd7920 --- /dev/null +++ b/docs-site/src/content/docs/api/E2E/Host-1.md @@ -0,0 +1,126 @@ +--- +title: "Host" +description: "A host on an engine that contributes fixtures: its sessions are Session. Upstream's Host (core/launch.ts)." +editUrl: false +prev: false +next: false +sidebar: + label: "Host" + hidden: true +--- + + + +Namespace: [E2E](/api/E2E/) + + +```csharp +public sealed class Host : IAsyncDisposable where TFixtures : class +``` + + +A host on an engine that contributes fixtures: its sessions are `Session<T>`. Upstream's `Host` (`core/launch.ts`). + +**Type parameters** + +| Name | Description | +| --- | --- | +| `TFixtures` | What the engine contributes, as `IEngine<T>` declares. | + +**Inheritance:** [object](https://learn.microsoft.com/dotnet/api/system.object) + +**Implements:** [IAsyncDisposable](https://learn.microsoft.com/dotnet/api/system.iasyncdisposable) + +[View source](https://github.com/hardkoded/e2e-dotnet/blob/main/src/E2E/Core/Launch.cs) + +## Properties + + + + +### Platform + + +```csharp +public string Platform { get; } +``` + + +The engine's platform label: `web`, `ios`, `android`, or an engine's own string. + +**Value:** [string](https://learn.microsoft.com/dotnet/api/system.string) + +## Methods + + + + +### CloseAsync() + + +```csharp +public Task CloseAsync() +``` + + +Closes the open session, then the engine. Idempotent. Throws an [AggregateException](https://learn.microsoft.com/dotnet/api/system.aggregateexception) of the failures closing found. Upstream's `close`. + +**Returns:** [Task](https://learn.microsoft.com/dotnet/api/system.threading.tasks.task) + + + + +### DisposeAsync() + + +```csharp +public ValueTask DisposeAsync() +``` + + +Closes the open session, then the engine. Idempotent. Throws an [AggregateException](https://learn.microsoft.com/dotnet/api/system.aggregateexception) of the failures closing found. Upstream's `close`. + +**Returns:** [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask) + + + + +### NewSessionAsync(NewSessionOptions?, CancellationToken) + + +```csharp +public Task> NewSessionAsync(NewSessionOptions? options = null, CancellationToken cancellationToken = default) +``` + + +Opens a session. One at a time: the previous one must be closed. + +**Parameters** + +| Name | Type | Description | +| --- | --- | --- | +| `options` | [NewSessionOptions](/api/E2E/NewSessionOptions/) | | +| `cancellationToken` | [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken) | | + +**Returns:** [Task<Session<TFixtures>>](https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1) + + + + +### Secret(string) + + +```csharp +public Secret Secret(string name) +``` + + +The handle of a secret passed to `LaunchAsync`, for `FillAsync` or an agent's params. An unknown name throws `SECRET_UNAVAILABLE`. + +**Parameters** + +| Name | Type | Description | +| --- | --- | --- | +| `name` | [string](https://learn.microsoft.com/dotnet/api/system.string) | | + +**Returns:** [Secret](/api/E2E/Secret/) diff --git a/docs-site/src/content/docs/api/E2E/Launch.md b/docs-site/src/content/docs/api/E2E/Launch.md index 86f9ed29..9c5c4f0f 100644 --- a/docs-site/src/content/docs/api/E2E/Launch.md +++ b/docs-site/src/content/docs/api/E2E/Launch.md @@ -52,3 +52,32 @@ opens sessions on it. Each launch needs its own engine instance. | `cancellationToken` | [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken) | | **Returns:** [Task<Host>](https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1) + + + +### `LaunchAsync(IEngine, LaunchOptions?, CancellationToken)` + + +```csharp +public static Task> LaunchAsync(IEngine engine, LaunchOptions? options = null, CancellationToken cancellationToken = default) where TFixtures : class +``` + + +Launches an engine that contributes fixtures (`IEngine<T>`), so each session of the host holds them as `Fixtures`. +Upstream's `launch`. + +**Type parameters** + +| Name | Description | +| --- | --- | +| `TFixtures` | | + +**Parameters** + +| Name | Type | Description | +| --- | --- | --- | +| `engine` | `IEngine<TFixtures>` | | +| `options` | [LaunchOptions](/api/E2E/LaunchOptions/) | | +| `cancellationToken` | [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken) | | + +**Returns:** [Task<Host<TFixtures>>](https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1) diff --git a/docs-site/src/content/docs/api/E2E/LaunchOptions.md b/docs-site/src/content/docs/api/E2E/LaunchOptions.md index e17b00e3..8aa6f2ff 100644 --- a/docs-site/src/content/docs/api/E2E/LaunchOptions.md +++ b/docs-site/src/content/docs/api/E2E/LaunchOptions.md @@ -147,7 +147,8 @@ public TimeSpan? Timeout { get; init; } ``` -Default timeout of one operation: an action, a wait, a read. Without it an action gets 30 seconds. An agent step has its own, `ActAsync`'s -timeout. There is no session deadline. +Default timeout of one operation: an action, a wait, a read, and `App.OpenAsync` or `App.RestartAsync`. Without it an action, a wait, +or a read gets 30 seconds, and an app open or restart 120 seconds. A session changes it with [SetDefaultTimeout(TimeSpan)](/api/E2E/Session/#E2E_Session_SetDefaultTimeout_System_TimeSpan_). An agent +step has its own, `ActAsync`'s timeout. There is no session deadline. **Value:** [TimeSpan?](https://learn.microsoft.com/dotnet/api/system.timespan) diff --git a/docs-site/src/content/docs/api/E2E/ScriptedModel.md b/docs-site/src/content/docs/api/E2E/ScriptedModel.md index 069c8036..c2766ca7 100644 --- a/docs-site/src/content/docs/api/E2E/ScriptedModel.md +++ b/docs-site/src/content/docs/api/E2E/ScriptedModel.md @@ -29,7 +29,7 @@ and the judge may answer a judgment (a request with a [Schema](/api/E2E/ModelReq **Implements:** [IAgentModel](/api/E2E/IAgentModel/) -[View source](https://github.com/hardkoded/e2e-dotnet/blob/main/src/E2E/Agent/Model.cs) +[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) ## Constructors diff --git a/docs-site/src/content/docs/api/E2E/Session-1.md b/docs-site/src/content/docs/api/E2E/Session-1.md new file mode 100644 index 00000000..a27b977b --- /dev/null +++ b/docs-site/src/content/docs/api/E2E/Session-1.md @@ -0,0 +1,53 @@ +--- +title: "Session" +description: "A session on an engine that contributes fixtures of its own: Fixtures holds them, such as Device on a mobile engine. Upstream's Session (core/launc..." +editUrl: false +prev: false +next: false +sidebar: + label: "Session" + hidden: true +--- + + + +Namespace: [E2E](/api/E2E/) + + +```csharp +public sealed class Session : Session, IAsyncDisposable where TFixtures : class +``` + + +A session on an engine that contributes fixtures of its own: `Fixtures` holds them, such as `Device` on a mobile engine. Upstream's +`Session` (`core/launch.ts`), the session type intersected with the engine's fixtures; C# has no intersection, so the +engine's fixtures are one member. + +**Type parameters** + +| Name | Description | +| --- | --- | +| `TFixtures` | What the engine contributes, as `IEngine<T>` declares. | + +**Inheritance:** [object](https://learn.microsoft.com/dotnet/api/system.object) → [Session](/api/E2E/Session/) + +**Implements:** [IAsyncDisposable](https://learn.microsoft.com/dotnet/api/system.iasyncdisposable) + +[View source](https://github.com/hardkoded/e2e-dotnet/blob/main/src/E2E/Core/Launch.cs) + +## Properties + + + + +### Fixtures + + +```csharp +public TFixtures Fixtures { get; } +``` + + +What the engine contributes beside [Screen](/api/E2E/Session/#E2E_Session_Screen), [App](/api/E2E/Session/#E2E_Session_App), and [Platform](/api/E2E/Session/#E2E_Session_Platform). + +**Value:** `TFixtures` diff --git a/docs-site/src/content/docs/api/E2E/Session.md b/docs-site/src/content/docs/api/E2E/Session.md index fcd7be45..853e721f 100644 --- a/docs-site/src/content/docs/api/E2E/Session.md +++ b/docs-site/src/content/docs/api/E2E/Session.md @@ -15,7 +15,7 @@ Namespace: [E2E](/api/E2E/) ```csharp -public sealed class Session : IAsyncDisposable +public class Session : IAsyncDisposable ``` @@ -26,6 +26,8 @@ One isolated session: a browser context, or the app on a device. Holds [Screen]( **Implements:** [IAsyncDisposable](https://learn.microsoft.com/dotnet/api/system.iasyncdisposable) +**Derived:** [Session<TFixtures>](/api/E2E/Session-1/) + [View source](https://github.com/hardkoded/e2e-dotnet/blob/main/src/E2E/Core/Launch.cs) ## Properties @@ -142,3 +144,23 @@ Captures the session's state (cookies, storage, app data) in memory. Persist it | `cancellationToken` | [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken) | | **Returns:** [Task<SessionState>](https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1) + + + + +### SetDefaultTimeout(TimeSpan) + + +```csharp +public void SetDefaultTimeout(TimeSpan timeout) +``` + + +The default timeout of operations started from now on: actions, waits, reads, and app opens and restarts. A running operation keeps the +deadline it started with. Throws `INVALID_ARGUMENT` unless <code class="paramref">timeout</code> is positive and finite. Upstream's `setDefaultTimeout`. + +**Parameters** + +| Name | Type | Description | +| --- | --- | --- | +| `timeout` | [TimeSpan](https://learn.microsoft.com/dotnet/api/system.timespan) | | diff --git a/docs-site/src/content/docs/api/E2E/index.md b/docs-site/src/content/docs/api/E2E/index.md index 7ba0819c..e12bf5d2 100644 --- a/docs-site/src/content/docs/api/E2E/index.md +++ b/docs-site/src/content/docs/api/E2E/index.md @@ -100,6 +100,7 @@ The core. Agent, Screen, Expect, the engines, model clients, config, and the rep | [GotoOptions](/api/E2E/GotoOptions/) | Options of GotoAsync. | | [GrammarToolsOptions](/api/E2E/GrammarToolsOptions/) | What CreateGrammarTools runs a tool body under (upstream's GrammarToolOptions). | | [Host](/api/E2E/Host/) | One engine instance, initialized: the owner of the sessions opened on it, one at a time. Upstream's Host (core/launch.ts). | +| [Host<TFixtures>](/api/E2E/Host-1/) | A host on an engine that contributes fixtures: its sessions are Session<T>. Upstream's Host (core/launch.ts). | | [HoverAtActionEvent](/api/E2E/HoverAtActionEvent/) | A hoverAt the step dispatched. Mobile engines have no hoverAt. | | [Launch](/api/E2E/Launch/) | launch from @e2e-dev/core: drive a browser or a device from plain code, with no test runner, config file, or report. A host is one worker on one engine instance: it prepares the engine, initializes it, and opens sessions on it one at a time. Parallel work is more hosts. Upstream's core/launch.ts. | | [LaunchApp](/api/E2E/LaunchApp/) | The app a host drives: what app.open() opens on a browser, or launches on a device. Upstream's LaunchApp (core/launch.ts), a pick of the target's app. | @@ -161,6 +162,7 @@ The core. Agent, Screen, Expect, the engines, model clients, config, and the rep | [Secrets](/api/E2E/Secrets/) | The secrets declared in e2e.config.json. Each value comes from E2E_SECRET_{NAME} when it is set, else from the config. The name is uppercased and every character other than A-Z and 0-9 becomes an underscore. | | [SelectOption](/api/E2E/SelectOption/) | One option of a select-like control, named by exactly one of its Label, its Value, or its Index. Upstream's SelectOption object forms { label }, { value }, and { index }; the plain string form is SelectOptionAsync. A select takes one option per call. | | [Session](/api/E2E/Session/) | One isolated session: a browser context, or the app on a device. Holds Screen, App, Platform, and Browser. Upstream's Session and SessionControls (core/launch.ts), over the port's E2ESession. | +| [Session<TFixtures>](/api/E2E/Session-1/) | A session on an engine that contributes fixtures of its own: Fixtures holds them, such as Device on a mobile engine. Upstream's Session (core/launch.ts), the session type intersected with the engine's fixtures; C# has no intersection, so the engine's fixtures are one member. | | [SessionState](/api/E2E/SessionState/) | What a session's SaveStateAsync captures (the engine's cookies, storage, or app data), held in memory. Upstream's SessionState (core/state.ts). It leaves the process only encrypted, under a key the caller holds, as a session-state-1 document; there is no plaintext export. Pass it to NewSessionAsync to start a session from it, on a host of the same engine, platform, and app. | | [SessionStateKeyOptions](/api/E2E/SessionStateKeyOptions/) | The options of ExportAsync(SessionStateKeyOptions) and ImportAsync: the AES-256-GCM key, 32 bytes the caller keeps. Upstream's SessionStateKeyOptions. | | [SkipException](/api/E2E/SkipException/) | Thrown by Skip when a test stops early and is reported skipped. | diff --git a/docs-site/src/content/docs/docs/core.mdx b/docs-site/src/content/docs/docs/core.mdx index 3a884de8..64f15df9 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`. +`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. ```csharp using E2E; diff --git a/skills/e2e-dotnet/references/host.md b/skills/e2e-dotnet/references/host.md index 604d06c3..6994e9ab 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`. +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. ```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 f82af832..1692a435 100644 --- a/src/E2E.Mobile/MobileEngine.cs +++ b/src/E2E.Mobile/MobileEngine.cs @@ -79,11 +79,17 @@ public sealed record MobileStartInfo /// fresh launch of the pinned app. The device is a simulator, an emulator, or a connected phone, named by the options, /// discovered, or leased from an . /// -public sealed partial class MobileEngine : IPreparableEngine, IDisposableEngine, IDoctorEngine +public sealed partial class MobileEngine : IPreparableEngine, IDisposableEngine, IDoctorEngine, IEngine { /// The version of the engine, as upstream's @e2e-dev/mobile numbers the surface this one follows. 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) => + 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"); + private static readonly Dictionary LoopbackNotes = new() { [MobilePlatform.Ios] = "a simulator shares this machine's loopback, and a hosted device cannot reach it at all", diff --git a/src/E2E.Mobile/MobileFixtures.cs b/src/E2E.Mobile/MobileFixtures.cs new file mode 100644 index 00000000..82de1664 --- /dev/null +++ b/src/E2E.Mobile/MobileFixtures.cs @@ -0,0 +1,18 @@ +// Copyright 2026 TesterArmy. +// Modified by Dario Kondratiuk. +// SPDX-License-Identifier: Apache-2.0 + +namespace E2E.Mobile; + +/// +/// What a session on a holds beside Screen and App: the fixture. Read it from +/// on a host launched through . Upstream's MobileFixtures +/// (mobile/fixtures.ts). +/// +public sealed class MobileFixtures +{ + internal MobileFixtures(Device device) => Device = device; + + /// Deterministic device management for the session. + public Device Device { get; } +} diff --git a/src/E2E/Core/Launch.cs b/src/E2E/Core/Launch.cs index 01462e90..74cb06e5 100644 --- a/src/E2E/Core/Launch.cs +++ b/src/E2E/Core/Launch.cs @@ -83,7 +83,7 @@ public sealed record NewSessionOptions /// One isolated session: a browser context, or the app on a device. Holds , , , and /// . Upstream's Session and SessionControls (core/launch.ts), over the port's . /// -public sealed class Session : IAsyncDisposable +public class Session : IAsyncDisposable { private readonly E2ESession _session; private readonly StandaloneAttempt _attempt; @@ -112,6 +112,9 @@ internal Session(StandaloneAttempt attempt, StateIdentity identity, Action onClo /// The engine's platform label: web, ios, android, or an engine's own string. public string Platform => _session.Context.Platform; + /// The engine's own session behind this one, which builds the engine's fixtures from. + internal IEngineSession EngineSession => Engine.EngineSession.Unwrap(_session.Engine); + internal E2ESession E2E => _session; /// Captures the session's state (cookies, storage, app data) in memory. Persist it only with . Upstream's saveState. @@ -158,6 +161,23 @@ private async Task CloseOnceAsync() } } +/// +/// A session on an engine that contributes fixtures of its own: holds them, such as Device on a mobile engine. Upstream's +/// Session<Fixtures> (core/launch.ts), the session type intersected with the engine's fixtures; C# has no intersection, so the +/// engine's fixtures are one member. +/// +/// What the engine contributes, as declares. +public sealed class Session : Session + where TFixtures : class +{ + internal Session(StandaloneAttempt attempt, StateIdentity identity, Action onClosed, Func fixtures) + : base(attempt, identity, onClosed) => + Fixtures = fixtures(EngineSession); + + /// What the engine contributes beside , , and . + public TFixtures Fixtures { get; } +} + /// One engine instance, initialized: the owner of the sessions opened on it, one at a time. Upstream's Host (core/launch.ts). public sealed class Host : IAsyncDisposable { @@ -172,12 +192,14 @@ public sealed class Host : IAsyncDisposable private readonly TimeSpan? _timeout; private readonly LaunchApp? _app; private readonly bool _headed; + private readonly Func _newSession; private readonly Lock _gate = new(); private readonly Lazy _closing; private Session? _open; - internal Host(StandaloneHost host, IEngine engine, string target, string projectRoot, string output, bool ownsArtifacts, IReadOnlyDictionary secrets, StateIdentity identity, TimeSpan? timeout, LaunchApp? app, bool headed) + internal Host(StandaloneHost host, IEngine engine, string target, string projectRoot, string output, bool ownsArtifacts, IReadOnlyDictionary secrets, StateIdentity identity, TimeSpan? timeout, LaunchApp? app, bool headed, Func? newSession = null) { + _newSession = newSession ?? ((attempt, sessionIdentity, onClosed) => new Session(attempt, sessionIdentity, onClosed)); _headed = headed; _app = app; _host = host; @@ -222,7 +244,7 @@ public Task NewSessionAsync(NewSessionOptions? options = null, Cancella var attempt = await _host.OpenAttemptAsync(SessionOptions(restored), cancellationToken, hosted: true).ConfigureAwait(false); try { - var session = new Session(attempt, _identity, () => Release(attempt)); + var session = _newSession(attempt, _identity, () => Release(attempt)); if (_timeout is { } timeout) { session.SetDefaultTimeout(timeout); @@ -348,6 +370,34 @@ private async Task CloseOnceAsync() } +/// +/// A host on an engine that contributes fixtures: its sessions are . Upstream's Host<Fixtures> (core/launch.ts). +/// +/// What the engine contributes, as declares. +public sealed class Host : IAsyncDisposable + where TFixtures : class +{ + private readonly Host _host; + + internal Host(Host host) => _host = host; + + /// + public string Platform => _host.Platform; + + /// + public Secret Secret(string name) => _host.Secret(name); + + /// + public async Task> NewSessionAsync(NewSessionOptions? options = null, CancellationToken cancellationToken = default) => + (Session)await _host.NewSessionAsync(options, cancellationToken).ConfigureAwait(false); + + /// + public Task CloseAsync() => _host.CloseAsync(); + + /// + public ValueTask DisposeAsync() => _host.DisposeAsync(); +} + /// /// launch from @e2e-dev/core: drive a browser or a device from plain code, with no test runner, config file, or report. A host is /// one worker on one engine instance: it prepares the engine, initializes it, and opens sessions on it one at a time. Parallel work is more hosts. @@ -366,7 +416,25 @@ public static class Launch /// Launches : prepares it (a first-run browser download, a device lease), initializes one worker, and returns the host that /// opens sessions on it. Each launch needs its own engine instance. /// - public static async Task LaunchAsync(IEngine engine, LaunchOptions? options = null, CancellationToken cancellationToken = default) + public static Task LaunchAsync(IEngine engine, LaunchOptions? options = null, CancellationToken cancellationToken = default) => + LaunchCoreAsync(engine, options, null, cancellationToken); + + /// + /// Launches an engine that contributes fixtures (), so each session of the host holds them as . + /// Upstream's launch<Fixtures>. + /// + public static async Task> LaunchAsync(IEngine engine, LaunchOptions? options = null, CancellationToken cancellationToken = default) + where TFixtures : class + { + var host = await LaunchCoreAsync( + engine, + options, + (attempt, identity, onClosed) => new Session(attempt, identity, onClosed, engine.CreateFixtures), + cancellationToken).ConfigureAwait(false); + return new Host(host); + } + + private static async Task LaunchCoreAsync(IEngine engine, LaunchOptions? options, Func? newSession, CancellationToken cancellationToken) { if (engine is null) { @@ -416,7 +484,7 @@ public static async Task LaunchAsync(IEngine engine, LaunchOptions? option Headed = options.Headed, Notice = options.OnNotice is { } notice ? (_, message) => OpenSession.Notify(notice, message) : null, }).ConfigureAwait(false); - return new Host(worker, engine, target, projectRoot, output, ownsArtifacts, secrets, identity, options.Timeout, app, options.Headed); + return new Host(worker, engine, target, projectRoot, output, ownsArtifacts, secrets, identity, options.Timeout, app, options.Headed, newSession); } catch { diff --git a/src/E2E/Engine/IEngine.cs b/src/E2E/Engine/IEngine.cs index 868ee3b8..d3dc4ced 100644 --- a/src/E2E/Engine/IEngine.cs +++ b/src/E2E/Engine/IEngine.cs @@ -121,6 +121,18 @@ public interface IEngineFixtureHost void CreateFixtures(EngineFixtureContext context); } +/// +/// An engine that contributes fixtures to the sessions opened on it, which types a host and its sessions by. +/// Upstream's EngineHandle<Fixtures> (defineEngine<Fixtures>). +/// +/// What a session on this engine holds beside Screen and App, such as Device on a mobile engine. +public interface IEngine : IEngine + where TFixtures : class +{ + /// The fixtures of one session, over the engine's own . + TFixtures CreateFixtures(IEngineSession session); +} + /// Passed to once per test attempt. public sealed class EngineStartOptions { diff --git a/tests/E2E.Tests/Core/CoreFakeEngine.cs b/tests/E2E.Tests/Core/CoreFakeEngine.cs index c59c5881..d3145a9f 100644 --- a/tests/E2E.Tests/Core/CoreFakeEngine.cs +++ b/tests/E2E.Tests/Core/CoreFakeEngine.cs @@ -13,7 +13,7 @@ namespace E2E.Tests.Core; /// the restoredStates, inits, attemptsStarted and disposes counts the core tests read, and the device and links options: /// a device engine pins an app and relaunches it, and one with links opens them, as session.openLink does. /// -internal sealed class CoreFakeEngine : IEngine +internal sealed class CoreFakeEngine : IEngine { private readonly List _restored = []; private readonly List<(SemanticNode Node, LocatorAction Action)> _performed = []; @@ -81,6 +81,9 @@ 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 Task StartAsync(EngineStartOptions options, CancellationToken cancellationToken) { Interlocked.Increment(ref _starts); @@ -169,3 +172,6 @@ public ValueTask DisposeAsync() } } } + +/// What the fake engine contributes to a session: upstream's gadget fixture. +internal sealed record CoreFakeFixtures(string Gadget); diff --git a/tests/E2E.Tests/Core/CoreTests.cs b/tests/E2E.Tests/Core/CoreTests.cs index f7ed8782..5842605b 100644 --- a/tests/E2E.Tests/Core/CoreTests.cs +++ b/tests/E2E.Tests/Core/CoreTests.cs @@ -18,7 +18,7 @@ public sealed class CoreTests : IAsyncLifetime private readonly string _dir = Directory.CreateTempSubdirectory("e2e-core-tests-").FullName; - private readonly List _hosts = []; + private readonly List _hosts = []; public Task InitializeAsync() => Task.CompletedTask; @@ -28,7 +28,7 @@ public async Task DisposeAsync() { try { - await opened.CloseAsync(); + await opened.DisposeAsync(); } catch (AggregateException) { @@ -42,6 +42,13 @@ public async Task DisposeAsync() private static List Password() => [new SemanticNode { Ref = "password", Role = "textbox", Name = "Password", Text = "" }]; private async Task HostOf(CoreFakeEngine engine, LaunchOptions? options = null) + { + var opened = await Launch.LaunchAsync((IEngine)engine, (options ?? new LaunchOptions()) with { Cwd = _dir, Env = new Dictionary() }); + _hosts.Add(opened); + return opened; + } + + private async Task> FixtureHostOf(CoreFakeEngine engine, LaunchOptions? options = null) { var opened = await Launch.LaunchAsync(engine, (options ?? new LaunchOptions()) with { Cwd = _dir, Env = new Dictionary() }); _hosts.Add(opened); @@ -51,18 +58,24 @@ private async Task HostOf(CoreFakeEngine engine, LaunchOptions? options = private static Task Mismatch(Host target, SessionState state) => Assert.ThrowsAsync(() => target.NewSessionAsync(new NewSessionOptions { State = state })); - // Partial: the port's session has no fixtures beyond screen, app, platform, and browser (no `gadget` and no key listing), and no `agent` on it. + // The port's session also holds Browser, the web engine's fixture that every port session carries, so it is in the expected members. [Fact] - public async Task Partial_Opens_sessions_one_at_a_time_on_one_engine_instance_each_with_screen_app_and_platform() + public async Task Opens_sessions_one_at_a_time_on_one_engine_instance_each_with_screen_app_and_platform() { - var fake = new CoreFakeEngine(); - var opened = await HostOf(fake, new LaunchOptions { App = FakeApp }); + var fake = new CoreFakeEngine(scene: [new SemanticNode { Ref = "price", Role = "text", Name = "Price", Text = "39,000", TestId = "sale-price" }]); + var opened = await FixtureHostOf(fake, new LaunchOptions { App = FakeApp }); Assert.Equal("fake", opened.Platform); var first = await opened.NewSessionAsync(); await first.App.OpenAsync("/"); - Assert.Equal("fake", first.Platform); - Assert.NotNull(first.Screen); + Assert.Equal("39,000", await first.Screen.GetByTestId("sale-price").TextContentAsync()); + Assert.Equal("gadget on fake", first.Fixtures.Gadget); + var members = typeof(Session).GetProperties().Select(member => member.Name) + .Concat(typeof(Session).GetMethods().Where(method => !method.IsSpecialName && method.DeclaringType != typeof(object)).Select(method => method.Name)) + .Order(StringComparer.Ordinal) + .ToList(); + Assert.Equal(["App", "Browser", "CloseAsync", "DisposeAsync", "Fixtures", "Platform", "SaveStateAsync", "Screen", "SetDefaultTimeout"], members); + Assert.Null(typeof(Session).GetProperty("Agent")); Assert.Equal("WORKER_PROTOCOL", (await Assert.ThrowsAsync(() => opened.NewSessionAsync())).Code); await first.CloseAsync(); await first.CloseAsync();