Speculation Module

The Speculation module provides monitoring of prefetch status updates from the browser. It is defined in the Prefetch specification's Automated testing section as an extension to WebDriver BiDi.

Scope note: The Prefetch specification defines only the speculation.prefetchStatusUpdated event. There are no commands to add or remove speculation rules—those are configured by the page itself via the Speculation Rules API (e.g., <script type="speculationrules"> in HTML). This module is intentionally limited to what the spec defines.

Overview

The Speculation module allows you to:

• Subscribe to prefetch status updates (pending, ready, success, failure)
• Monitor when the browser prefetches resources
• Observe prefetch lifecycle for testing and diagnostics

Accessing the Module

SpeculationModule speculation = driver.Speculation;

Prefetch Status Event

The OnPrefetchStatusUpdated event fires when the browser updates the status of a prefetched resource. Subscribe to it to observe prefetch lifecycle.

Subscribe to Prefetch Status Updates

driver.Speculation.OnPrefetchStatusUpdated.AddObserver((e) =>
{
    Console.WriteLine($"Prefetch {e.Url}: {e.Status}");
});

SubscribeCommandParameters subscribe = new SubscribeCommandParameters(
    driver.Speculation.OnPrefetchStatusUpdated.EventName);
await driver.Session.SubscribeAsync(subscribe);

PreloadingStatus Values

Status	Description
Pending	The prefetch has begun
Ready	The prefetch is complete and available
Success	The prefetch was activated (e.g., user navigated to it)
Failure	The prefetch failed or expired

Event Payload

Each event provides:

• BrowsingContextId – The top-level browsing context of the navigable the update concerns; for a prefetch started by a document in a frame, that is the frame's top-level browsing context, not the frame
• Url – The URL that was prefetched
• Status – The current PreloadingStatus

Example: Monitoring Prefetch During Navigation

var collected = new List<PrefetchStatusUpdatedEventArgs>();

driver.Speculation.OnPrefetchStatusUpdated.AddObserver((e) =>
{
    collected.Add(e);
});

var subscribe = new SubscribeCommandParameters(
    driver.Speculation.OnPrefetchStatusUpdated.EventName);
await driver.Session.SubscribeAsync(subscribe);

await driver.BrowsingContext.NavigateAsync(
    new NavigateCommandParameters(contextId, "https://example.com")
    { Wait = ReadinessState.Complete });

await Task.Delay(2000);

foreach (var evt in collected)
{
    Console.WriteLine($"{evt.Url} -> {evt.Status}");
}

Browser Support

Browser	Prefetch Status Event
Chrome/Edge	⚠️ Experimental
Firefox	❌ Not supported
Safari	❌ Not supported

Note: Support is experimental. Enable with --enable-features=SpeculationRulesPrefetchProxy for Chrome/Edge.

Speculation Rules (Page-Configured)

Prefetch and prerender rules are not set via WebDriver BiDi. Pages configure them using the Speculation Rules API, for example:

<script type="speculationrules">
{
  "prefetch": [{
    "source": "list",
    "urls": ["https://example.com/next-page"]
  }]
}
</script>

The Speculation module lets you observe when the browser acts on these rules—it does not create or modify them.

Next Steps

• Network Module: Monitoring network performance
• Browser Module: Browser-level operations
• Browsing Context Module: Navigation management
• API Reference: Complete API documentation

Further Reading

• Prefetch Specification – Automated testing – WebDriver BiDi speculation module definition
• Speculation Rules API – How pages configure prefetch/prerender