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
14 changes: 14 additions & 0 deletions DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -560,3 +560,17 @@ published by hand by the owner.
write to an allowed host fails the step. A page that writes on its own (telemetry) needs `WritableUrls`.
- **`BlockedRequest.RefusedWrite` is `null` for allow-list refusals**, so existing `BlockedRequest` equality is
unchanged.
## Run defaults

- **A harness sets the viewport, user agent and headers once per run.** A live site tells monitors from people by user
agent and headers (the docs site turns its telemetry off for a monitor), and a responsive site is in its phone layout
at Chrome's default viewport. Repeating `set viewport`, `set useragent` and `set headers` in every journey is how one
gets forgotten.
- **The journey builds on the run, it does not undo it.** `set headers` merges (a header it repeats wins) because
Chrome's own call replaces the whole set and a journey adding one header should not drop the monitor header;
`set device` leaves the run's user agent in place for the same reason. `set viewport`, `set device` and `set useragent`
still replace what they name.
- **No allow-list option was added**: `AllowedHosts` already is the run-level default.
- **A click that hits nothing is not this change**: at the phone viewport `find role link click` completed with no effect.
The default viewport is the fix for that site; a click that reports it missed its target is separate.

3 changes: 3 additions & 0 deletions docs/cli/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,9 @@ cdp run site/journeys/*.journey --base-url ./site --artifacts .artifacts/journey
| `--build-type`, `--env` | the build type and the environment's name, for `build-type:` and `env:` conditions |
| `--read-only` | refuse every request that is not GET, HEAD or OPTIONS, so the run cannot change a live site; see [safety](../journeys/safety.md#read-only-runs) |
| `--writable` | a URL glob a read-only run may write to anyway (repeatable), such as a telemetry endpoint |
| `--viewport` | the viewport the run starts with, `1280x800`; without it Chrome's default applies, which a responsive site may treat as a phone |
| `--user-agent` | the user agent of the run |
| `--header` | a request header every page sends (repeatable), `"Name: value"` |
| `--file-root` | the folder `file://` URLs may point into, when the base URL is not a folder |
| `--artifacts` | the folder `screenshot` and `network har stop` write into; off unless given |
| `--timeout` | seconds an action waits for its element (default 5) |
Expand Down
14 changes: 14 additions & 0 deletions docs/journeys/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,20 @@ end
as two journey files with different `@requires`, one per flag state.
- Indentation is for people; it means nothing to the parser.
- agent-browser has no conditions, so a journey with blocks cannot be exported to it (`ToAgentBrowserBatch` says so).
## Run defaults

A harness that runs journeys against a live site sets three things once for the run, so no journey repeats them:

| Option | Does |
|---|---|
| `JourneyOptions.Viewport` (`viewport`, `--viewport 1280x800`) | the size the run starts with. Without it Chrome's default applies, and a responsive site may be in its mobile layout, where a link in a collapsed menu can be clicked with no effect and no error |
| `JourneyOptions.UserAgent` (`userAgent`, `--user-agent`) | the user agent of every request and of `navigator.userAgent`, e.g. one that tells the site the traffic is a monitor |
| `JourneyOptions.Headers` (`headers`, `--header "Name: value"`) | headers every page sends |

They are in place before the first step. A journey's own lines build on them: `set viewport` and `set device` replace the
viewport, `set useragent` replaces the user agent (`set device` does not: the run's identity stays), and `set headers`
adds to the run's headers, winning for a name it repeats, instead of replacing them. The hosts a run may reach are
`JourneyOptions.AllowedHosts` (`--allow`), as before.

## URLs

Expand Down
1 change: 1 addition & 0 deletions docs/journeys/playwright.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,7 @@ adapters do.
|---|---|
| `baseUrl` | what relative `open` URLs resolve against; its host is allowed |
| `allowedHosts` | host patterns allowed beyond the base URL's host and the journey's `allow` lines |
| `viewport`, `userAgent`, `headers` | the run's defaults, in place before the first step (see [run defaults](index.md#run-defaults)); `userAgent` needs Chromium |
| `secrets` | resolves `$env:NAME`; the process environment by default |
| `artifactsDir` | where `screenshot` writes; without it screenshot steps are skipped |
| `journeyDir` | the folder `upload` reads from |
Expand Down
43 changes: 34 additions & 9 deletions js/journeys/src/run.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,15 @@ export interface RunOptions {
readOnly?: boolean;
/** URL globs (`**` anything, `*` anything but `/`) a read-only run may write to anyway, such as a telemetry endpoint. */
writableUrls?: string[];
/**
* Request headers every page of the run sends, such as one that marks the traffic as a monitor. A journey's own
* `set headers` adds to them (and wins for a header it names) rather than replacing them.
*/
headers?: Record<string, string>;
/** The user agent of the run. A journey's own `set useragent` replaces it; `set device` does not. Needs Chromium. */
userAgent?: string;
/** The viewport the run starts with; without it the context's applies. A journey's `set viewport` or `set device` replaces it. */
viewport?: { width: number; height: number };
/** Resolves `$env:NAME`; the process environment by default. */
secrets?: (name: string) => string | undefined;
/** Where `screenshot` writes. Without it, screenshot steps are skipped with a warning. */
Expand Down Expand Up @@ -236,6 +245,10 @@ export class JourneyRun {
};
await page.route('**/*', guard);
this.disposers.push(() => page.unroute('**/*', guard));
// The run's viewport, user agent and headers, set before the first step so the journey starts as the harness wants.
if (this.options.viewport) await page.setViewportSize(this.options.viewport);
if (this.options.userAgent !== undefined) await this.setUserAgent(this.options.userAgent);
if (this.options.headers && Object.keys(this.options.headers).length > 0) await page.context().setExtraHTTPHeaders(this.options.headers);

const commands = journey.steps.map((s) => s.command);
if (commands.some((c) => c.type === 'har' || c.type === 'requests' || c.type === 'expectRequest')) {
Expand Down Expand Up @@ -541,6 +554,8 @@ export class JourneyRun {
if (!device) throw new StepError(`Playwright has no device called '${c.device}'.`);
await this.page.setViewportSize(device.viewport);
this.warn('set device changes only the viewport: user agent and touch are fixed when the context is created (use a Playwright project).');
// The run's identity stays: only the journey's own `set useragent` replaces it.
if (this.options.userAgent !== undefined) await this.setUserAgent(this.options.userAgent);
break;
}
case 'geo':
Expand All @@ -551,16 +566,9 @@ export class JourneyRun {
this.offline = c.offline ?? !this.offline;
await context.setOffline(this.offline);
break;
case 'headers': await context.setExtraHTTPHeaders(JSON.parse(c.headers!) as Record<string, string>); break;
case 'headers': await context.setExtraHTTPHeaders(mergeHeaders(this.options.headers, JSON.parse(c.headers!) as Record<string, string>)); break;
case 'useragent':
// Playwright fixes the user agent when the context is created; Chromium's own override changes it for the page,
// header and navigator.userAgent both.
try {
const session = await context.newCDPSession(this.page);
await session.send('Emulation.setUserAgentOverride', { userAgent: c.userAgent! });
} catch {
throw new StepError('set useragent needs Chromium: set userAgent in the Playwright config for other browsers.');
}
await this.setUserAgent(c.userAgent!);
break;
case 'credentials':
throw new StepError('set credentials is not supported by the Playwright runner: set httpCredentials in the Playwright config (an extra header would be sent to every host).');
Expand All @@ -569,6 +577,17 @@ export class JourneyRun {
return undefined;
}

// Playwright fixes the user agent when the context is created; Chromium's own override changes it for the page,
// header and navigator.userAgent both.
private async setUserAgent(userAgent: string) {
try {
const session = await this.page.context().newCDPSession(this.page);
await session.send('Emulation.setUserAgentOverride', { userAgent });
} catch {
throw new StepError('set useragent needs Chromium: set userAgent in the Playwright config for other browsers.');
}
}

private async audit(c: Extract<Command, { type: 'audit' }>): Promise<Output> {
const Axe = this.options.axe;
if (!Axe) throw new StepError("a11y needs axe: pass `axe: (await import('@axe-core/playwright')).AxeBuilder` in the run options.");
Expand Down Expand Up @@ -780,6 +799,12 @@ function describeRequestExpectation(c: Extract<Command, { type: 'expectRequest'
return parts.join(' ');
}

// The run's headers with the journey's on top: a header the journey names wins (whatever its case), the others stay.
function mergeHeaders(defaults: Record<string, string> | undefined, journey: Record<string, string>): Record<string, string> {
const named = new Set(Object.keys(journey).map((n) => n.toLowerCase()));
return { ...Object.fromEntries(Object.entries(defaults ?? {}).filter(([n]) => !named.has(n.toLowerCase()))), ...journey };
}

const globToRegExp = (glob: string) =>
new RegExp('^' + glob.split('**').map((part) => part.split('*').map((s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('[^/]*')).join('.*') + '$');

Expand Down
85 changes: 85 additions & 0 deletions js/journeys/test/defaults.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
// A run's defaults (viewport, user agent, headers) are in place before the first step, a journey's own `set` lines
// build on them, and they show on both sides: what the page sees and what the server receives. The same cases as
// RunDefaultsTests in the .NET tests. Skips when Chrome is missing; CDP_BROWSER_REQUIRED=1 makes that a failure.

import assert from 'node:assert/strict';
import { createServer } from 'node:http';
import type { AddressInfo } from 'node:net';
import { after, before, test } from 'node:test';
import type { Browser } from 'playwright-core';
import { parseJourney, runJourney } from '../src/index.ts';
import type { RunOptions } from '../src/index.ts';
import { launchChrome } from './site.ts';

let browser: Browser | undefined;
let skip: string | false = false;
let origin = '';
let stop = () => {};

const header = (v: string | string[] | undefined) => String(v ?? 'none').replace(/&/g, '&amp;').replace(/</g, '&lt;');

before(async () => {
const server = createServer((req, res) => {
res.writeHead(200, { 'content-type': 'text/html' }).end(
'<!doctype html><title>Echo</title><link rel="icon" href="data:,">' +
`<p id="header">${header(req.headers['x-docs-synthetic-monitor'])}</p><p id="journey">${header(req.headers['x-journey'])}</p><p id="request-ua">${header(req.headers['user-agent'])}</p>` +
'<p id="ua"></p><p id="width"></p>' +
"<script>document.getElementById('ua').textContent = navigator.userAgent; document.getElementById('width').textContent = String(innerWidth);</script>",
);
});
await new Promise<void>((done) => server.listen(0, '127.0.0.1', done));
origin = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
stop = () => server.close();
({ browser, skip } = await launchChrome());
});

after(async () => {
await browser?.close();
stop();
});

const reads = 'open /echo\nget text #ua\nget text #width\nget text #header\nget text #journey\nget text #request-ua\n';
const monitor: Partial<RunOptions> = { headers: { 'X-Docs-Synthetic-Monitor': 'true' }, userAgent: 'Elastic/Synthetics', viewport: { width: 1111, height: 700 } };

// What the page saw (user agent, width) and what the server saw (header, journey header, user agent).
async function run(text: string, defaults: Partial<RunOptions>) {
const page = await (await browser!.newContext()).newPage();
const result = await runJourney(page, parseJourney(text, 'defaults.journey'), { baseUrl: origin + '/', actionTimeout: 3000, warn: () => {}, ...defaults });
assert.equal(result.failure, undefined, JSON.stringify(result.failure));
return result.checkpoints.filter((c) => c.command.startsWith('get text')).map((c) => c.output);
}

test('the run starts with its viewport, user agent and headers', async (t) => {
if (skip) return t.skip(skip);
assert.deepEqual(await run(reads, monitor), ['Elastic/Synthetics', '1111', 'true', 'none', 'Elastic/Synthetics']);
});

test('without defaults nothing changes', async (t) => {
if (skip) return t.skip(skip);
const seen = await run(reads, {});
assert.match(seen[0], /Chrome/);
assert.doesNotMatch(seen[0], /Elastic\/Synthetics/);
assert.equal(seen[2], 'none');
assert.notEqual(seen[1], '1111');
});

test("a journey's headers add to the run's and win when they name the same", async (t) => {
if (skip) return t.skip(skip);
assert.deepEqual(await run('set headers \'{"x-journey": "1", "X-Docs-Synthetic-Monitor": "override"}\'\n' + reads, monitor), ['Elastic/Synthetics', '1111', 'override', '1', 'Elastic/Synthetics']);
assert.deepEqual((await run('set headers \'{"x-journey": "1"}\'\n' + reads, monitor)).slice(2), ['true', '1', 'Elastic/Synthetics']);
});

test("a journey's user agent replaces the run's and the header stays", async (t) => {
if (skip) return t.skip(skip);
assert.deepEqual(await run('set useragent Other/1.0\n' + reads, monitor), ['Other/1.0', '1111', 'true', 'none', 'Other/1.0']);
});

test("a journey's viewport replaces the run's", async (t) => {
if (skip) return t.skip(skip);
assert.equal((await run('set viewport 800 600\n' + reads, monitor))[1], '800');
});

test("a device keeps the run's user agent", async (t) => {
if (skip) return t.skip(skip);
assert.equal((await run("set device 'iPhone 14'\n" + reads, monitor))[0], 'Elastic/Synthetics');
});
47 changes: 45 additions & 2 deletions src/Nullean.Cdp.Cli/CdpCli.cs
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,43 @@ public int Batch(string file, string? baseUrl, bool resolveSecrets)
return ExitCode.Ok;
}

// "Name: value", as curl takes it. Null, after saying why, when one is not.
private Dictionary<string, string>? ParseHeaders(IReadOnlyList<string> headers)
{
var parsed = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
foreach (var header in headers)
{
var colon = header.IndexOf(':', StringComparison.Ordinal);
var name = colon > 0 ? header[..colon].Trim() : "";
if (name.Length == 0 || name.Any(c => c is <= ' ' or > '~' or ':'))
{
error.WriteLine($"'{header}' is not a header: use --header \"Name: value\".");
return null;
}

parsed[name] = header[(colon + 1)..].Trim();
}

return parsed;
}

// "1280x800": the size the run starts with; none when not given. False, after saying why, when it is malformed.
private bool ParseViewport(string? viewport, out JourneyViewport? size)
{
size = null;
if (viewport is null)
return true;
var parts = viewport.Split('x');
if (parts.Length == 2 && int.TryParse(parts[0], NumberStyles.None, CultureInfo.InvariantCulture, out var width) && int.TryParse(parts[1], NumberStyles.None, CultureInfo.InvariantCulture, out var height) && width > 0 && height > 0)
{
size = new JourneyViewport(width, height);
return true;
}

error.WriteLine($"'{viewport}' is not a viewport: use --viewport <width>x<height>, e.g. 1280x800.");
return false;
}

public async Task<int> RunAsync(
IReadOnlyList<string> files,
string? baseUrl,
Expand All @@ -97,11 +134,14 @@ public async Task<int> RunAsync(
string? buildType = null,
string? env = null,
bool readOnly = false,
IReadOnlyList<string>? writable = null
IReadOnlyList<string>? writable = null,
IReadOnlyList<string>? headers = null,
string? userAgent = null,
string? viewport = null
)
{
var (ok, root) = ParseBase(baseUrl);
if (!ok || !ValidAllow(allow) || Load(files) is not { } journeys)
if (!ok || !ValidAllow(allow) || ParseHeaders(headers ?? []) is not { } extraHeaders || !ParseViewport(viewport, out var size) || Load(files) is not { } journeys)
return ExitCode.Usage;
if (await LaunchAsync(headed, cancellationToken).ConfigureAwait(false) is not { } browser)
return ExitCode.Browser;
Expand All @@ -118,6 +158,9 @@ public async Task<int> RunAsync(
Env = env,
ReadOnly = readOnly,
WritableUrls = writable ?? [],
Headers = extraHeaders,
UserAgent = userAgent,
Viewport = size,
FileRoot = fileRoot is null ? null : Path.GetFullPath(fileRoot),
ArtifactsDirectory = artifacts is null ? null : Path.GetFullPath(artifacts),
Secrets = environment,
Expand Down
8 changes: 7 additions & 1 deletion src/Nullean.Cdp.Cli/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,9 @@ internal sealed class CdpCommands
/// <param name="env">The environment's name, for env: conditions.</param>
/// <param name="readOnly">Refuse every request that is not GET, HEAD or OPTIONS, so the run cannot change a live site.</param>
/// <param name="writable">URL glob a read-only run may write to anyway (repeatable): ** anything, * anything but /.</param>
/// <param name="header">A request header every page sends (repeatable): "Name: value".</param>
/// <param name="userAgent">The user agent of the run.</param>
/// <param name="viewport">The viewport the run starts with: 1280x800. Without it Chrome's default applies, which a responsive site may treat as a phone.</param>
/// <param name="headed">Show the browser window.</param>
/// <param name="json">Print JSON; everything under a "page" key came from the page.</param>
/// <param name="maxOutput">Characters per checkpoint before it is cut (0 for no limit).</param>
Expand All @@ -43,12 +46,15 @@ public static Task<int> Run(
string? env = null,
bool readOnly = false,
string[]? writable = null,
string[]? header = null,
string? userAgent = null,
string? viewport = null,
bool headed = false,
bool json = false,
int maxOutput = CdpCli.DefaultMaxOutput,
double? timeout = null,
CancellationToken cancellationToken = default
) => Cli().RunAsync(files, baseUrl, allow ?? [], fileRoot, headed, json, maxOutput, timeout, cancellationToken, artifacts, feature, buildType, env, readOnly, writable);
) => Cli().RunAsync(files, baseUrl, allow ?? [], fileRoot, headed, json, maxOutput, timeout, cancellationToken, artifacts, feature, buildType, env, readOnly, writable, header, userAgent, viewport);

/// <summary>Parse journeys without running them, and report every error with its line.</summary>
/// <param name="files">Journey files.</param>
Expand Down
Loading
Loading