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
13 changes: 13 additions & 0 deletions docs-site/public/api/E2E.Engine.WebApp.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<link rel="canonical" href="https://www.hardkoded.com/e2e-dotnet/api/E2E.Engine/WebApp/">
<meta http-equiv="refresh" content="0; url=/e2e-dotnet/api/E2E.Engine/WebApp/">
<title>Redirecting…</title>
<script>location.replace("/e2e-dotnet/api/E2E.Engine/WebApp/" + (location.hash || ""));</script>
</head>
<body>
<p><a href="/e2e-dotnet/api/E2E.Engine/WebApp/">Continue</a></p>
</body>
</html>
13 changes: 13 additions & 0 deletions docs-site/public/api/E2E.Engine.WebFixtures.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<link rel="canonical" href="https://www.hardkoded.com/e2e-dotnet/api/E2E.Engine/WebFixtures/">
<meta http-equiv="refresh" content="0; url=/e2e-dotnet/api/E2E.Engine/WebFixtures/">
<title>Redirecting…</title>
<script>location.replace("/e2e-dotnet/api/E2E.Engine/WebFixtures/" + (location.hash || ""));</script>
</head>
<body>
<p><a href="/e2e-dotnet/api/E2E.Engine/WebFixtures/">Continue</a></p>
</body>
</html>
11 changes: 7 additions & 4 deletions docs-site/src/content/docs/api/E2E.Engine/IEngine-1.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,27 +28,30 @@ Upstream's `EngineHandle<Fixtures>` (`defineEngine<Fixtures>`).
| --- | --- |
| `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

<a id="E2E_Engine_IEngine_1_CreateFixtures_"></a>
<a id="E2E_Engine_IEngine_1_CreateFixtures_E2E_Engine_IEngineSession_"></a>
<a id="E2E_Engine_IEngine_1_CreateFixtures_E2E_Engine_IEngineSession_E2E_Session_"></a>

### 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 &lt;code class="paramref"&gt;session&lt;/code&gt;.
The fixtures of one session, over the engine's own &lt;code class="paramref"&gt;session&lt;/code&gt; and the &lt;code class="paramref"&gt;controls&lt;/code&gt; the harness built (its `Browser` and `App`).

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `session` | [IEngineSession](/api/E2E.Engine/IEngineSession/) | |
| `controls` | [Session](/api/E2E/Session/) | |

**Returns:** `TFixtures`
43 changes: 43 additions & 0 deletions docs-site/src/content/docs/api/E2E.Engine/WebApp.md
Original file line number Diff line number Diff line change
@@ -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
---

<a id="E2E_Engine_WebApp"></a>

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

<a id="E2E_Engine_WebApp_BaseUrl_"></a>
<a id="E2E_Engine_WebApp_BaseUrl"></a>

### 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)
26 changes: 24 additions & 2 deletions docs-site/src/content/docs/api/E2E.Engine/WebEngine.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Namespace: [E2E.Engine](/api/E2E.Engine/)


```csharp
public sealed class WebEngine : IDoctorEngine, IEngine, IAsyncDisposable
public sealed class WebEngine : IEngine<WebFixtures>, IDoctorEngine, IEngine, IAsyncDisposable
```


Expand All @@ -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&lt;WebFixtures&gt;`, [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)

Expand Down Expand Up @@ -137,6 +137,28 @@ public string Version { get; }

## Methods

<a id="E2E_Engine_WebEngine_CreateFixtures_"></a>
<a id="E2E_Engine_WebEngine_CreateFixtures_E2E_Engine_IEngineSession_E2E_Session_"></a>

### 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/)

<a id="E2E_Engine_WebEngine_DisposeAsync_"></a>
<a id="E2E_Engine_WebEngine_DisposeAsync"></a>

Expand Down
59 changes: 59 additions & 0 deletions docs-site/src/content/docs/api/E2E.Engine/WebFixtures.md
Original file line number Diff line number Diff line change
@@ -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
---

<a id="E2E_Engine_WebFixtures"></a>

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

<a id="E2E_Engine_WebFixtures_App_"></a>
<a id="E2E_Engine_WebFixtures_App"></a>

### App


```csharp
public WebApp App { get; }
```


The app, with its base URL always set.

**Value:** [WebApp](/api/E2E.Engine/WebApp/)

<a id="E2E_Engine_WebFixtures_Browser_"></a>
<a id="E2E_Engine_WebFixtures_Browser"></a>

### Browser


```csharp
public Browser Browser { get; }
```


The browser fixture.

**Value:** [Browser](/api/E2E/Browser/)
2 changes: 2 additions & 0 deletions docs-site/src/content/docs/api/E2E.Engine/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down
4 changes: 3 additions & 1 deletion docs-site/src/content/docs/api/E2E/App.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Namespace: [E2E](/api/E2E/)


```csharp
public sealed class App
public class App
```


Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs-site/src/content/docs/docs/core.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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<TFixtures>`, such as `MobileEngine` with `MobileFixtures`) makes `LaunchAsync` return a `Host<TFixtures>` whose sessions are `Session<TFixtures>`: `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<TFixtures>`, such as `MobileEngine` with `MobileFixtures`) makes `LaunchAsync` return a `Host<TFixtures>` whose sessions are `Session<TFixtures>`: `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;
Expand Down
2 changes: 1 addition & 1 deletion skills/e2e-dotnet/references/host.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<TFixtures>`, such as `MobileEngine` with `MobileFixtures`) makes `LaunchAsync` return a `Host<TFixtures>` whose sessions are `Session<TFixtures>`: `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<TFixtures>`, such as `MobileEngine` with `MobileFixtures`) makes `LaunchAsync` return a `Host<TFixtures>` whose sessions are `Session<TFixtures>`: `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
Expand Down
2 changes: 1 addition & 1 deletion src/E2E.Mobile/MobileEngine.cs
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ public sealed partial class MobileEngine : IPreparableEngine, IDisposableEngine,
public const string EngineVersion = "0.11.0";

/// <summary>The fixtures of a session on this engine: its <c>Device</c>. A session no device engine started is a <c>WORKER_PROTOCOL</c> failure.</summary>
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");
Expand Down
4 changes: 2 additions & 2 deletions src/E2E/Core/Launch.cs
Original file line number Diff line number Diff line change
Expand Up @@ -170,9 +170,9 @@ private async Task CloseOnceAsync()
public sealed class Session<TFixtures> : Session
where TFixtures : class
{
internal Session(StandaloneAttempt attempt, StateIdentity identity, Action onClosed, Func<IEngineSession, TFixtures> fixtures)
internal Session(StandaloneAttempt attempt, StateIdentity identity, Action onClosed, Func<IEngineSession, Session, TFixtures> fixtures)
: base(attempt, identity, onClosed) =>
Fixtures = fixtures(EngineSession);
Fixtures = fixtures(EngineSession, this);

/// <summary>What the engine contributes beside <see cref="Session.Screen"/>, <see cref="Session.App"/>, and <see cref="Session.Platform"/>.</summary>
public TFixtures Fixtures { get; }
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 @@ -129,8 +129,8 @@ public interface IEngineFixtureHost
public interface IEngine<out TFixtures> : IEngine
where TFixtures : class
{
/// <summary>The fixtures of one session, over the engine's own <paramref name="session"/>.</summary>
TFixtures CreateFixtures(IEngineSession session);
/// <summary>The fixtures of one session, over the engine's own <paramref name="session"/> and the <paramref name="controls"/> the harness built (its <c>Browser</c> and <c>App</c>).</summary>
TFixtures CreateFixtures(IEngineSession session, Session controls);
}

/// <summary>Passed to <see cref="IEngine.StartAsync"/> once per test attempt.</summary>
Expand Down
11 changes: 10 additions & 1 deletion src/E2E/Engine/WebEngine.cs
Original file line number Diff line number Diff line change
Expand Up @@ -278,8 +278,17 @@ public sealed class WebEngineOptions
/// same node actions the document engine does. Install browsers once with
/// <c>playwright.ps1 install chromium</c> (or <c>firefox</c>, <c>webkit</c>) from this project's build output.
/// </summary>
public sealed partial class WebEngine : IEngine
public sealed partial class WebEngine : IEngine, IEngine<WebFixtures>
{
/// <summary>The fixtures of a session on this engine: its <c>Browser</c> and its <c>App</c> with the base URL set. A web target always declares <c>app.url</c>, so a session with none is a <c>WORKER_PROTOCOL</c> failure.</summary>
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";
Expand Down
34 changes: 34 additions & 0 deletions src/E2E/Engine/WebFixtures.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
// Copyright 2026 TesterArmy.
// Modified by Dario Kondratiuk.
// SPDX-License-Identifier: Apache-2.0

namespace E2E.Engine;

/// <summary><c>App</c> on a web target. A <see cref="WebEngine"/> target always declares <c>app.url</c>, so <see cref="BaseUrl"/> is always set. Upstream's <c>WebApp</c> (<c>web/fixtures.ts</c>).</summary>
public sealed class WebApp : App
{
internal WebApp(App app, string baseUrl)
: base(app) => BaseUrl = baseUrl;

/// <summary>The target's <c>app.url</c> with the run's port and no trailing slash: <c>$"{app.BaseUrl}/api/users"</c>.</summary>
public new string BaseUrl { get; }
}

/// <summary>
/// What a session on a <see cref="WebEngine"/> holds beside <c>Screen</c>: the <see cref="Browser"/> fixture, and <see cref="App"/> with its
/// <see cref="WebApp.BaseUrl"/> always set. Read it from <see cref="Session{TFixtures}.Fixtures"/>. Upstream's <c>WebFixtures</c> (<c>web/fixtures.ts</c>).
/// </summary>
public sealed class WebFixtures
{
internal WebFixtures(Browser browser, WebApp app)
{
Browser = browser;
App = app;
}

/// <summary>The browser fixture.</summary>
public Browser Browser { get; }

/// <summary>The app, with its base URL always set.</summary>
public WebApp App { get; }
}
21 changes: 20 additions & 1 deletion src/E2E/Run/Fixtures.cs
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ internal interface IArtifactSink
/// Opens and resets the app under test. A relative URL is resolved against
/// <see cref="BaseUrl"/>; no URL opens the base URL.
/// </summary>
public sealed class App
public class App
{
private readonly IEngineSession _session;
private readonly string? _baseUrl;
Expand Down Expand Up @@ -67,6 +67,25 @@ internal App(IEngineSession session, string? baseUrl, Func<CancellationToken> to
_steps = steps;
}

/// <summary>Copies an app, which <see cref="WebApp"/> extends (upstream's <c>WebApp extends App</c>).</summary>
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;
}

/// <summary>
/// The resolved base URL of the target's app, with the port the run allocated when <c>app.url</c> declared port 0 and no trailing
/// slash, so <c>$"{BaseUrl}/api/users"</c> joins with one slash; null when the test declares none. <see cref="OpenAsync"/> still
Expand Down
2 changes: 1 addition & 1 deletion tests/E2E.Tests/Core/CoreFakeEngine.cs
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ public IReadOnlyList<string> OpenedLinks
public EngineCapabilities Capabilities { get; }

/// <summary>Contributes the <c>gadget</c> fixture. Upstream's <c>fixtures: true</c>.</summary>
public CoreFakeFixtures CreateFixtures(IEngineSession session) => new("gadget on " + Platform);
public CoreFakeFixtures CreateFixtures(IEngineSession session, E2E.Session controls) => new("gadget on " + Platform);

public Task<IEngineSession> StartAsync(EngineStartOptions options, CancellationToken cancellationToken)
{
Expand Down
Loading