diff --git a/DECISIONS.md b/DECISIONS.md
index 0a3e811..eefae2f 100644
--- a/DECISIONS.md
+++ b/DECISIONS.md
@@ -586,6 +586,24 @@ 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.
+## Preconditions
+
+- **A run can wait for a deploy before it starts.** `JourneyPreconditions.WaitAsync` opens a page until a response header or an
+ element's text or attribute shows a value (exact, contains or regex). A deploy that has not landed, or whose cache has not
+ cleared, still shows the old value; failing there says so once, instead of failing every journey.
+- **Every look is a new context.** A context has no cache, so a stale copy cannot satisfy the wait, and the run's user agent,
+ headers, allow list and read-only rule apply to it like to a journey, which keeps a monitor identifiable.
+- **Header and element go through one browser path.** Chrome reports the main document's response (`Page.Response`: status and
+ headers) from the `Network` events every page already collects since the timeout diagnostics, so no second HTTP client and no
+ HTML parser is needed, and an element that script adds is seen as a visitor sees it.
+- **`Timeout`, `Interval` and `Retries` are separate.** A look that works and shows another value is not an error: the wait goes on
+ until `Timeout` (default 10 s, every 500 ms). A look that fails (the page did not load in time, the connection dropped) counts
+ against `Retries` (default 2) and the wait gives up when they run out, so a dead origin fails in seconds and not after the
+ whole timeout. A host outside the allow list is refused before any look.
+- **Not a journey step.** It is a run-level check the runner makes once, before any journey: `# @requires` and `wait` stay as they are.
+- **What it cannot see:** it shows the value of the page it opened. A value that does not change between two deploys, such as a
+ version shared by a content-only deploy, passes at once.
+
## Run defaults
- **A harness sets the viewport, user agent and headers once per run.** A live site tells monitors from people by user
diff --git a/docs/library/network.md b/docs/library/network.md
index 4d260f0..3264342 100644
--- a/docs/library/network.md
+++ b/docs/library/network.md
@@ -48,3 +48,31 @@ network har stop checkout.har
In a journey the file goes into the artifacts folder (`--artifacts`), and secrets typed during the run are replaced by
their `$env:` references. With the allow list on, each request waits for its verdict, which adds a little to
`blocked`; record with the guard off when the timings themselves are the point.
+
+## Wait for a deploy
+
+`JourneyPreconditions.WaitAsync` waits until a page shows a value before anything runs against it: a response header of the page's document, or
+an element's text or attribute. A site whose deploy has not landed, or whose cache has not cleared, still shows the old value.
+
+```csharp
+var precondition = new JourneyPrecondition
+{
+ Path = "/docs",
+ Selector = "meta[name='docs:build']",
+ Attribute = "content",
+ Expected = "1.74.1",
+ Timeout = TimeSpan.FromSeconds(10),
+ Retries = 2,
+};
+
+PreconditionResult result = await JourneyPreconditions.WaitAsync(browser, precondition, new JourneyOptions { BaseUrl = new Uri("https://docs-demo.elastic.dev/") });
+if (!result.Passed)
+ Console.Error.WriteLine(result.Message);
+```
+
+Set `Header` instead of `Selector` to read a response header. `Match` is `Exact` by default; `Contains` and `Regex` are the others.
+The wait looks again every `Interval` (500 ms) until `Timeout` (10 s). A look that fails, because the page did not load or the
+connection dropped, counts against `Retries` (2), and the wait ends when they are used up. Each look is a new context, so nothing is cached, and
+the options' allow list, user agent, headers and read-only rule apply.
+
+`Page.Response` has the status and headers of the response that served the page's current document.
diff --git a/src/Nullean.Cdp.Journeys/JourneyPreconditions.cs b/src/Nullean.Cdp.Journeys/JourneyPreconditions.cs
new file mode 100644
index 0000000..3217ed8
--- /dev/null
+++ b/src/Nullean.Cdp.Journeys/JourneyPreconditions.cs
@@ -0,0 +1,216 @@
+using System.Globalization;
+using System.Text.RegularExpressions;
+using Nullean.Cdp.Protocol;
+
+namespace Nullean.Cdp.Journeys;
+
+///
+/// Something a site must show before journeys run against it: a response header or an element's text or attribute on one
+/// page, equal to a value. A deploy that has not landed, or whose cache has not cleared, still shows the old value; waiting for
+/// the new one first turns that into a clear failure and keeps it from showing up as a failure of every journey.
+///
+public sealed record JourneyPrecondition
+{
+ /// The page to open: an absolute URL, or a path that resolves.
+ public required string Path { get; init; }
+
+ /// A response header of the page's document. Set this, or .
+ public string? Header { get; init; }
+
+ /// A CSS selector for an element, such as meta[name='docs:build']. Set this, or .
+ public string? Selector { get; init; }
+
+ /// With : the attribute to read, such as content. The element's text when null.
+ public string? Attribute { get; init; }
+
+ /// The value to wait for.
+ public required string Expected { get; init; }
+
+ /// How is compared with what the page shows.
+ public TextMatch Match { get; init; } = TextMatch.Exact;
+
+ /// How long to wait for the value in all. Default: 10 seconds.
+ public TimeSpan Timeout { get; init; } = TimeSpan.FromSeconds(10);
+
+ /// How long to wait between looks. Default: half a second.
+ public TimeSpan Interval { get; init; } = TimeSpan.FromMilliseconds(500);
+
+ ///
+ /// How many times a look that fails (the page did not load, the connection dropped) is tried again before the wait gives up. A look
+ /// that works and shows another value is not a failure: the wait goes on until . Default: 2.
+ ///
+ public int Retries { get; init; } = 2;
+
+ /// What the precondition looks at, in words: the docs:build header of /docs.
+ public string Subject =>
+ Header is not null
+ ? $"the {Header} response header of {Path}"
+ : $"{(Attribute is null ? "the text" : $"the {Attribute} attribute")} of {Selector} on {Path}";
+}
+
+/// How waiting for a ended.
+/// The page showed the value.
+/// Plain text: what matched, or what was expected and what was last seen.
+/// How many looks it took.
+/// How long it waited.
+public sealed record PreconditionResult(bool Passed, string Message, int Attempts, TimeSpan Elapsed);
+
+/// Waits for what a site must show before a run starts.
+public static class JourneyPreconditions
+{
+ private const int MaxSeen = 200;
+ private static readonly TimeSpan RegexTimeout = TimeSpan.FromSeconds(1);
+
+ ///
+ /// Opens the page in a fresh context (so nothing is cached) until it shows the value of , the wait
+ /// times out, or looks fail more often than allows. The run's allow list, user agent,
+ /// headers and read-only rule of apply, so a monitor stays identifiable and cannot write.
+ ///
+ public static async Task WaitAsync(
+ Browser browser,
+ JourneyPrecondition precondition,
+ JourneyOptions? options = null,
+ CancellationToken cancellationToken = default
+ )
+ {
+ ArgumentNullException.ThrowIfNull(browser);
+ ArgumentNullException.ThrowIfNull(precondition);
+ options ??= new JourneyOptions();
+ Validate(precondition);
+ var url = Resolve(precondition.Path, options);
+ var allowList = options.AllowList([]);
+ if (allowList.Refusal(url) is { } refusal)
+ return new PreconditionResult(false, $"Did not look at {url}: {refusal}.", 0, TimeSpan.Zero);
+
+ var started = System.Diagnostics.Stopwatch.StartNew();
+ var attempts = 0;
+ var failures = 0;
+ string? seen;
+ while (true)
+ {
+ attempts++;
+ try
+ {
+ seen = await LookAsync(browser, precondition, url, allowList, options, Remaining(precondition, started), cancellationToken).ConfigureAwait(
+ false
+ );
+ if (seen is not null && Matches(precondition, seen))
+ return new PreconditionResult(true, $"{Capitalise(precondition.Subject)} is {Quote(seen)}.", attempts, started.Elapsed);
+ }
+ catch (Exception e) when (IsLookFailure(e, cancellationToken))
+ {
+ failures++;
+ seen = null;
+ if (failures > precondition.Retries)
+ return new PreconditionResult(
+ false,
+ $"Could not look at {url} for {Describe(precondition)}: {failures} looks failed, the last with: {e.Message}",
+ attempts,
+ started.Elapsed
+ );
+ }
+
+ if (started.Elapsed + precondition.Interval >= precondition.Timeout)
+ return new PreconditionResult(false, Timeout(precondition, seen, attempts, started.Elapsed), attempts, started.Elapsed);
+ await Task.Delay(precondition.Interval, cancellationToken).ConfigureAwait(false);
+ }
+ }
+
+ private static TimeSpan Remaining(JourneyPrecondition precondition, System.Diagnostics.Stopwatch started)
+ {
+ var left = precondition.Timeout - started.Elapsed;
+ return left > TimeSpan.FromSeconds(1) ? left : TimeSpan.FromSeconds(1);
+ }
+
+ // What the page shows, or null when it shows nothing to compare: no such header, no such element.
+ private static async Task LookAsync(
+ Browser browser,
+ JourneyPrecondition precondition,
+ Uri url,
+ JourneyAllowList allowList,
+ JourneyOptions options,
+ TimeSpan budget,
+ CancellationToken cancellationToken
+ )
+ {
+ await using var context = await browser.NewContextAsync(cancellationToken).ConfigureAwait(false);
+ var page = await context.NewPageAsync(cancellationToken).ConfigureAwait(false);
+ page.NavigationTimeout = options.NavigationTimeout is { } navigation && navigation < budget ? navigation : budget;
+ await using var guard = options.GuardNetwork || options.ReadOnly
+ ? await page.GuardNetworkAsync(options.GuardNetwork ? allowList.Allows : _ => true, options.GuardOptions(), cancellationToken).ConfigureAwait(false)
+ : null;
+ await JourneyRunner.ApplyDefaultsAsync(page, options, cancellationToken).ConfigureAwait(false);
+ await page.GotoAsync(url.AbsoluteUri, cancellationToken).ConfigureAwait(false);
+ if (precondition.Header is { } header)
+ return page.Response?.Header(header);
+ var element = page.Css(precondition.Selector!);
+ if (await element.CountAsync(cancellationToken).ConfigureAwait(false) == 0)
+ return null;
+ return precondition.Attribute is { } attribute
+ ? await element.First.AttributeAsync(attribute, cancellationToken).ConfigureAwait(false)
+ : await element.First.TextAsync(cancellationToken).ConfigureAwait(false);
+ }
+
+ private static bool IsLookFailure(Exception e, CancellationToken cancellationToken) =>
+ e is TimeoutException or PageNavigationException or CdpException or CdpDisconnectedException ||
+ (e is OperationCanceledException && !cancellationToken.IsCancellationRequested);
+
+ private static bool Matches(JourneyPrecondition precondition, string seen) => precondition.Match switch
+ {
+ TextMatch.Contains => seen.Contains(precondition.Expected, StringComparison.Ordinal),
+ TextMatch.Regex => Regex.IsMatch(seen, precondition.Expected, RegexOptions.CultureInvariant, RegexTimeout),
+ _ => string.Equals(seen, precondition.Expected, StringComparison.Ordinal),
+ };
+
+ private static void Validate(JourneyPrecondition p)
+ {
+ if ((p.Header is null) == (p.Selector is null))
+ throw new ArgumentException(
+ "A precondition looks at a response header or at an element: set Header or Selector, not both and not neither.",
+ nameof(p)
+ );
+ if (p.Header is null && p.Attribute is not null && p.Attribute.Length == 0)
+ throw new ArgumentException("The attribute name is empty.", nameof(p));
+ if (p.Timeout <= TimeSpan.Zero || p.Interval <= TimeSpan.Zero)
+ throw new ArgumentOutOfRangeException(nameof(p), "The timeout and the interval are longer than zero.");
+ if (p.Retries < 0)
+ throw new ArgumentOutOfRangeException(nameof(p), "Retries are zero or more.");
+ if (p.Match == TextMatch.Regex)
+ {
+ try
+ {
+ _ = new Regex(p.Expected, RegexOptions.CultureInvariant, RegexTimeout);
+ }
+ catch (ArgumentException e)
+ {
+ throw new ArgumentException($"'{p.Expected}' is not a valid regular expression: {e.Message}", nameof(p), e);
+ }
+ }
+ }
+
+ private static Uri Resolve(string path, JourneyOptions options) =>
+ Uri.TryCreate(options.BaseUrl, path, out var url) && url.IsAbsoluteUri
+ ? url
+ : throw new ArgumentException($"'{path}' is not a URL, and the options have no base URL to resolve it against.", nameof(path));
+
+ private static string Timeout(JourneyPrecondition p, string? seen, int attempts, TimeSpan elapsed) =>
+ string.Create(
+ CultureInfo.InvariantCulture,
+ $"Timed out after {elapsed.TotalSeconds:0.#}s waiting for {p.Subject} to {Describe(p)}: last saw {(seen is null ? "nothing" : Quote(seen))} in {attempts} {(attempts == 1 ? "look" : "looks")}."
+ );
+
+ private static string Describe(JourneyPrecondition p) => p.Match switch
+ {
+ TextMatch.Contains => $"contain {Quote(p.Expected)}",
+ TextMatch.Regex => $"match {Quote(p.Expected)}",
+ _ => $"equal {Quote(p.Expected)}",
+ };
+
+ private static string Quote(string value)
+ {
+ var flat = value.ReplaceLineEndings(" ");
+ return $"\"{(flat.Length > MaxSeen ? flat[..MaxSeen] + "..." : flat)}\"";
+ }
+
+ private static string Capitalise(string text) => char.ToUpperInvariant(text[0]) + text[1..];
+}
diff --git a/src/Nullean.Cdp.Journeys/JourneyRunner.cs b/src/Nullean.Cdp.Journeys/JourneyRunner.cs
index 44fafa8..6f36bc8 100644
--- a/src/Nullean.Cdp.Journeys/JourneyRunner.cs
+++ b/src/Nullean.Cdp.Journeys/JourneyRunner.cs
@@ -106,9 +106,11 @@ internal NetworkGuardOptions GuardOptions()
};
}
- internal JourneyAllowList AllowList(Journey journey)
+ internal JourneyAllowList AllowList(Journey journey) => AllowList(journey.AllowedHosts);
+
+ internal JourneyAllowList AllowList(IEnumerable journeyHosts)
{
- var hosts = journey.AllowedHosts.Concat(AllowedHosts);
+ var hosts = journeyHosts.Concat(AllowedHosts);
if (BaseUrl is { Scheme: "http" or "https" } web)
hosts = hosts.Append(web.IdnHost);
// "file:///x/site/" and "file:///x/site/index.html" both give /x/site.
@@ -290,7 +292,7 @@ private static async Task FailureAsync(Run run, JourneyStep step
}
// The run's viewport, user agent and headers, set before the first step so the journey starts as the harness wants.
- private static async Task ApplyDefaultsAsync(Page page, JourneyOptions options, CancellationToken cancellationToken)
+ internal static async Task ApplyDefaultsAsync(Page page, JourneyOptions options, CancellationToken cancellationToken)
{
if (options.Viewport is { } viewport)
await page.SetViewportAsync(viewport.Width, viewport.Height, viewport.Scale, cancellationToken).ConfigureAwait(false);
diff --git a/src/Nullean.Cdp/Page.cs b/src/Nullean.Cdp/Page.cs
index 8fc14dd..2b61d27 100644
--- a/src/Nullean.Cdp/Page.cs
+++ b/src/Nullean.Cdp/Page.cs
@@ -35,6 +35,7 @@ internal Page(Browser browser, CdpConnection connection, string targetId, string
TargetId = targetId;
SessionId = sessionId;
ContextId = contextId;
+ _activity = new PageActivity(targetId);
}
internal Browser Browser { get; }
@@ -45,7 +46,13 @@ internal Page(Browser browser, CdpConnection connection, string targetId, string
internal int RecordingInteractions;
private readonly PageLog _log = new();
- private readonly PageActivity _activity = new();
+ private readonly PageActivity _activity;
+
+ ///
+ /// The response that served the main frame's current document, with its status and headers, or null before one
+ /// arrived (a file:// or about:blank page has none). A redirect shows the final response.
+ ///
+ public PageResponse? Response => _activity.Document;
/// The page's console calls since it was created or last cleared, oldest first.
public IReadOnlyList ConsoleMessages => _log.Console;
diff --git a/src/Nullean.Cdp/PageActivity.cs b/src/Nullean.Cdp/PageActivity.cs
index 3ff75ac..8b621f3 100644
--- a/src/Nullean.Cdp/PageActivity.cs
+++ b/src/Nullean.Cdp/PageActivity.cs
@@ -10,21 +10,32 @@ namespace Nullean.Cdp;
/// What the page is waiting on and what already went wrong, kept so a timeout can say why it timed out: the requests still in
/// flight (oldest first), and the last failed or error-status ones. Holds URLs and counts only, never bodies or headers.
///
-internal sealed class PageActivity
+internal sealed class PageActivity(string frameId)
{
private const int Shown = 5;
private const int Kept = 20;
private readonly ConcurrentDictionary _open = new(StringComparer.Ordinal);
private readonly ConcurrentQueue _problems = new();
+ private volatile PageResponse? _document;
private readonly record struct InFlight(string Method, string Url, long Started);
+ /// The latest response for a document in the page's main frame, or null before one arrived.
+ public PageResponse? Document => _document;
+
public void OnEvent(CdpEvent e)
{
var p = e.Params;
if (p.StringOrNull("requestId") is not { } id)
return;
+ if (
+ e.Method == "Network.responseReceived" && p.StringOrNull("type") == "Document" && p.StringOrNull("frameId") == frameId && p.TryGetProperty(
+ "response",
+ out var main
+ )
+ )
+ _document = PageResponse.From(main);
switch (e.Method)
{
// A redirect reuses the id: the new hop replaces the old one.
diff --git a/src/Nullean.Cdp/PageResponse.cs b/src/Nullean.Cdp/PageResponse.cs
new file mode 100644
index 0000000..2b23344
--- /dev/null
+++ b/src/Nullean.Cdp/PageResponse.cs
@@ -0,0 +1,26 @@
+using System.Text.Json;
+
+namespace Nullean.Cdp;
+
+/// The response that served a page's document: its URL, status and headers.
+/// The URL the response came from.
+/// The HTTP status code.
+/// The response headers by name, case-insensitive. A header sent more than once is joined with , (Chrome joins them with a newline).
+public sealed record PageResponse(string Url, int Status, IReadOnlyDictionary Headers)
+{
+ /// The value of , or null when the response has no such header.
+ public string? Header(string name) => Headers.TryGetValue(name, out var value) ? value : null;
+
+ internal static PageResponse From(JsonElement response)
+ {
+ var headers = new Dictionary(StringComparer.OrdinalIgnoreCase);
+ if (response.TryGetProperty("headers", out var sent) && sent.ValueKind == JsonValueKind.Object)
+ foreach (var header in sent.EnumerateObject())
+ headers[header.Name] = (header.Value.GetString() ?? string.Empty).Replace("\n", ", ", StringComparison.Ordinal);
+ return new PageResponse(
+ response.StringOrNull("url") ?? string.Empty,
+ response.TryGetProperty("status", out var status) && status.ValueKind == JsonValueKind.Number ? status.GetInt32() : 0,
+ headers
+ );
+ }
+}
diff --git a/tests/Nullean.Cdp.Tests/Live/PreconditionTests.cs b/tests/Nullean.Cdp.Tests/Live/PreconditionTests.cs
new file mode 100644
index 0000000..b2a77ed
--- /dev/null
+++ b/tests/Nullean.Cdp.Tests/Live/PreconditionTests.cs
@@ -0,0 +1,202 @@
+using AwesomeAssertions;
+using Nullean.Cdp.Journeys;
+
+namespace Nullean.Cdp.Tests.Live;
+
+[ClassDataSource(Shared = SharedType.PerTestSession)]
+public class PreconditionTests(ChromeFixture chrome)
+{
+ private static JourneyOptions Options(VersionServer server, TimeSpan? navigation = null) =>
+ new() { BaseUrl = new Uri(server.Url), NavigationTimeout = navigation };
+
+ [Test]
+ public async Task AHeaderThatChangesLateIsWaitedFor()
+ {
+ _ = chrome.Browser; // skips without a Chrome
+ await using var server = new VersionServer(n => n >= 3 ? "1.2.0" : "1.1.0");
+ var precondition = new JourneyPrecondition
+ {
+ Path = "/",
+ Header = "x-build",
+ Expected = "1.2.0",
+ Timeout = TimeSpan.FromSeconds(20),
+ Interval = TimeSpan.FromMilliseconds(100)
+ };
+
+ var result = await JourneyPreconditions.WaitAsync(chrome.Browser, precondition, Options(server));
+
+ result.Passed.Should().BeTrue(result.Message);
+ result.Attempts.Should().Be(3);
+ result.Message.Should().Be("The x-build response header of / is \"1.2.0\".");
+ }
+
+ [Test]
+ public async Task AnElementAttributeThatChangesLateIsWaitedFor()
+ {
+ _ = chrome.Browser;
+ await using var server = new VersionServer(n => n >= 2 ? "1.2.0" : "1.1.0");
+ var precondition = new JourneyPrecondition
+ {
+ Path = "/",
+ Selector = "meta[name='docs:build']",
+ Attribute = "content",
+ Expected = "1.2.0",
+ Timeout = TimeSpan.FromSeconds(20),
+ Interval = TimeSpan.FromMilliseconds(100),
+ };
+
+ var result = await JourneyPreconditions.WaitAsync(chrome.Browser, precondition, Options(server));
+
+ result.Passed.Should().BeTrue(result.Message);
+ result.Attempts.Should().Be(2);
+ }
+
+ [Test]
+ public async Task ElementTextAndRegexAndContainsAreMatched()
+ {
+ _ = chrome.Browser;
+ await using var server = new VersionServer(_ => "1.74.1-canary.0.3");
+ var text = new JourneyPrecondition { Path = "/", Selector = "#build", Expected = "1.74.1-canary.0.3" };
+ var regex = new JourneyPrecondition { Path = "/", Header = "X-Build", Expected = @"^1\.74\.\d+-canary", Match = TextMatch.Regex };
+ var contains = new JourneyPrecondition { Path = "/", Header = "x-build", Expected = "canary.0", Match = TextMatch.Contains };
+
+ (await JourneyPreconditions.WaitAsync(chrome.Browser, text, Options(server))).Passed.Should().BeTrue();
+ (await JourneyPreconditions.WaitAsync(chrome.Browser, regex, Options(server))).Passed.Should().BeTrue();
+ (await JourneyPreconditions.WaitAsync(chrome.Browser, contains, Options(server))).Passed.Should().BeTrue();
+ }
+
+ [Test]
+ public async Task AValueThatNeverArrivesFailsWithWhatWasExpectedAndLastSeen()
+ {
+ _ = chrome.Browser;
+ await using var server = new VersionServer(_ => "1.1.0");
+ var precondition = new JourneyPrecondition
+ {
+ Path = "/",
+ Header = "x-build",
+ Expected = "1.2.0",
+ Timeout = TimeSpan.FromSeconds(1),
+ Interval = TimeSpan.FromMilliseconds(200)
+ };
+
+ var result = await JourneyPreconditions.WaitAsync(chrome.Browser, precondition, Options(server));
+
+ result.Passed.Should().BeFalse();
+ result
+ .Message
+ .Should()
+ .StartWith("Timed out after ")
+ .And
+ .Contain("waiting for the x-build response header of / to equal \"1.2.0\": last saw \"1.1.0\" in ");
+ result.Attempts.Should().BeGreaterThanOrEqualTo(1);
+ }
+
+ [Test]
+ public async Task AMissingHeaderAndAMissingElementAreSeenAsNothing()
+ {
+ _ = chrome.Browser;
+ await using var server = new VersionServer(_ => "1.1.0");
+ var header = new JourneyPrecondition
+ {
+ Path = "/",
+ Header = "x-nothing",
+ Expected = "x",
+ Timeout = TimeSpan.FromMilliseconds(400),
+ Interval = TimeSpan.FromMilliseconds(100)
+ };
+ var element = new JourneyPrecondition
+ {
+ Path = "/",
+ Selector = "#nothing",
+ Expected = "x",
+ Timeout = TimeSpan.FromMilliseconds(400),
+ Interval = TimeSpan.FromMilliseconds(100)
+ };
+
+ (await JourneyPreconditions.WaitAsync(chrome.Browser, header, Options(server))).Message.Should().Contain("last saw nothing");
+ (await JourneyPreconditions.WaitAsync(chrome.Browser, element, Options(server))).Message.Should().Contain("last saw nothing");
+ }
+
+ [Test]
+ public async Task LooksThatFailAreRetriedAndGiveUpAfterTheRetries()
+ {
+ _ = chrome.Browser;
+ await using var flaky = new VersionServer(_ => "1.2.0", hangFirst: 2);
+ await using var down = new VersionServer(_ => "1.2.0", hangFirst: 100);
+ var precondition = new JourneyPrecondition
+ {
+ Path = "/",
+ Header = "x-build",
+ Expected = "1.2.0",
+ Timeout = TimeSpan.FromSeconds(30),
+ Interval = TimeSpan.FromMilliseconds(100),
+ Retries = 2
+ };
+
+ var recovered = await JourneyPreconditions.WaitAsync(chrome.Browser, precondition, Options(flaky, TimeSpan.FromMilliseconds(400)));
+ var gaveUp = await JourneyPreconditions.WaitAsync(chrome.Browser, precondition, Options(down, TimeSpan.FromMilliseconds(400)));
+
+ recovered.Passed.Should().BeTrue(recovered.Message);
+ recovered.Attempts.Should().Be(3);
+ gaveUp.Passed.Should().BeFalse();
+ gaveUp.Message.Should().Contain("3 looks failed, the last with:");
+ gaveUp.Attempts.Should().Be(3);
+ }
+
+ [Test]
+ public async Task AHostOutsideTheAllowListIsNotLookedAt()
+ {
+ _ = chrome.Browser;
+ await using var server = new VersionServer(_ => "1.2.0");
+ var precondition = new JourneyPrecondition { Path = "http://other.invalid/", Header = "x-build", Expected = "1.2.0" };
+
+ var result = await JourneyPreconditions.WaitAsync(chrome.Browser, precondition, Options(server));
+
+ result.Passed.Should().BeFalse();
+ result.Attempts.Should().Be(0);
+ result.Message.Should().Contain("other.invalid is not in the journey's allow list");
+ server.Requests.Should().Be(0);
+ }
+
+ [Test]
+ public async Task ABadRegexOrASourceThatIsNeitherHeaderNorElementIsRejectedUpFront()
+ {
+ _ = chrome.Browser;
+ await using var server = new VersionServer(_ => "1.2.0");
+
+ var badRegex =
+ () => JourneyPreconditions.WaitAsync(
+ chrome.Browser,
+ new JourneyPrecondition { Path = "/", Header = "x", Expected = "(", Match = TextMatch.Regex },
+ Options(server)
+ );
+ var neither = () => JourneyPreconditions.WaitAsync(chrome.Browser, new JourneyPrecondition { Path = "/", Expected = "x" }, Options(server));
+ var both =
+ () => JourneyPreconditions.WaitAsync(
+ chrome.Browser,
+ new JourneyPrecondition { Path = "/", Header = "x", Selector = "h1", Expected = "x" },
+ Options(server)
+ );
+
+ await badRegex.Should().ThrowAsync().WithMessage("'(' is not a valid regular expression*");
+ await neither.Should().ThrowAsync().WithMessage("A precondition looks at a response header or at an element*");
+ await both.Should().ThrowAsync();
+ }
+
+ [Test]
+ public async Task ThePageKnowsItsDocumentResponse()
+ {
+ _ = chrome.Browser;
+ await using var server = new VersionServer(_ => "9.9.9");
+ await using var context = await chrome.Browser.NewContextAsync();
+ var page = await context.NewPageAsync();
+ page.Response.Should().BeNull();
+
+ await page.GotoAsync(server.Url);
+
+ page.Response.Should().NotBeNull();
+ page.Response!.Status.Should().Be(200);
+ page.Response.Header("X-Build").Should().Be("9.9.9");
+ page.Response.Header("x-nothing").Should().BeNull();
+ }
+}
diff --git a/tests/Nullean.Cdp.Tests/Live/VersionServer.cs b/tests/Nullean.Cdp.Tests/Live/VersionServer.cs
new file mode 100644
index 0000000..35f131f
--- /dev/null
+++ b/tests/Nullean.Cdp.Tests/Live/VersionServer.cs
@@ -0,0 +1,95 @@
+using System.Net;
+using System.Net.Sockets;
+using System.Text;
+
+namespace Nullean.Cdp.Tests.Live;
+
+///
+/// A local HTTP server whose page names a build in a header and in a meta tag, and whose build changes as requests come in: a
+/// deploy that lands a moment after the run starts. The first requests can hang, as a struggling origin does.
+///
+internal sealed class VersionServer : IAsyncDisposable
+{
+ private readonly HttpListener _listener = new();
+ private readonly Task _serving;
+ private readonly Func _build;
+ private readonly int _hangFirst;
+ private int _requests;
+
+ public VersionServer(Func build, int hangFirst = 0)
+ {
+ _build = build;
+ _hangFirst = hangFirst;
+ var port = FreePort();
+ Url = $"http://localhost:{port}/";
+ _listener.Prefixes.Add(Url);
+ _listener.Start();
+ _serving = Task.Run(ServeAsync);
+ }
+
+ public string Url { get; }
+
+ public int Requests => Volatile.Read(ref _requests);
+
+ private async Task ServeAsync()
+ {
+ while (_listener.IsListening)
+ {
+ HttpListenerContext context;
+ try
+ {
+ context = await _listener.GetContextAsync();
+ }
+ catch (Exception e) when (e is HttpListenerException or ObjectDisposedException or InvalidOperationException)
+ {
+ return;
+ }
+
+ if (context.Request.Url!.AbsolutePath == "/favicon.ico")
+ {
+ context.Response.StatusCode = 404;
+ context.Response.Close();
+ continue;
+ }
+
+ var number = Interlocked.Increment(ref _requests);
+ _ = Task.Run(() => RespondAsync(context, number));
+ }
+ }
+
+ private async Task RespondAsync(HttpListenerContext context, int number)
+ {
+ try
+ {
+ if (number <= _hangFirst)
+ await Task.Delay(TimeSpan.FromSeconds(3));
+ var build = _build(number);
+ context.Response.ContentType = "text/html; charset=utf-8";
+ context.Response.AddHeader("x-build", build);
+ await context
+ .Response
+ .OutputStream
+ .WriteAsync(
+ Encoding.UTF8.GetBytes(
+ $"Landing
{build}
"
+ )
+ );
+ context.Response.Close();
+ }
+ catch (Exception e) when (e is HttpListenerException or ObjectDisposedException or IOException) { }
+ }
+
+ private static int FreePort()
+ {
+ using var probe = new TcpListener(IPAddress.Loopback, 0);
+ probe.Start();
+ return ((IPEndPoint)probe.LocalEndpoint).Port;
+ }
+
+ public async ValueTask DisposeAsync()
+ {
+ _listener.Stop();
+ _listener.Close();
+ await _serving;
+ }
+}