Lightpanda: the headless browser designed for AI and automation
// Copyright (C) 2023-2026 Lightpanda (Selecy SAS)
//
// Francis Bouvier <[email protected]>
// Pierre Tachoire <[email protected]>
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as
// published by the Free Software Foundation, either version 3 of the
// License, or (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.
const std = @import("std");
const lp = @import("lightpanda");
const uuidv4 = @import("../../id.zig").uuidv4;
const js = @import("../../browser/js/js.zig");
const URL = @import("../../browser/URL.zig");
const Node = @import("../../browser/webapi/Node.zig");
const Frame = @import("../../browser/Frame.zig");
const Viewport = @import("../../browser/Viewport.zig");
const Selector = @import("../../browser/webapi/selector/Selector.zig");
const xpath = @import("../../browser/xpath/Evaluator.zig");
const XPathParser = @import("../../browser/xpath/Parser.zig");
const Notification = @import("../../Notification.zig");
const BiDi = @import("BiDi.zig");
const script = @import("script.zig");
const execute = @import("execute.zig");
const remote_value = @import("remote_value.zig");
const log = lp.log;
// The one browser.ClientWindow every browsing context lives in.
pub const client_window = "default";
pub const Context = struct {
// The BiDi navigable id. Stable across navigations.
id: [36]u8,
frame_id: u32,
// Regenerated by onFrameNavigate for every root navigation, including
// ones the page itself initiates.
navigation_id: [36]u8,
// The window realm's id, reported by the script module. A navigation
// means a new document and so a new realm.
realm_id: [36]u8,
// A navigate command whose `wait` hasn't been satisfied yet.
pending_navigate: ?PendingNavigate = null,
// Whether script.realmCreated was sent or not. If sent, we'll send
// script.realmDestroyed on teardown.
realm_announced: bool = false,
};
const PendingNavigate = struct {
until: Until,
reply: BiDi.Reply,
pub const Until = enum { interactive, complete };
};
pub fn processMessage(cmd: *BiDi.Command, action: []const u8) !void {
const command = std.meta.stringToEnum(enum {
getTree,
create,
navigate,
reload,
traverseHistory,
close,
locateNodes,
setViewport,
}, action) orelse return error.UnknownCommand;
switch (command) {
.getTree => return getTree(cmd),
.create => return create(cmd),
.navigate => return bidiNavigate(cmd),
.reload => return bidiReload(cmd),
.traverseHistory => return bidiTraverseHistory(cmd),
.close => return close(cmd),
.locateNodes => return locateNodes(cmd),
.setViewport => return setViewport(cmd),
}
}
fn getTree(cmd: *BiDi.Command) !void {
const bidi = cmd.bidi;
const ctx = &(bidi.browsing_context orelse {
return cmd.sendResult(.{ .contexts = &[_]Info{} });
});
const url: []const u8 = if (bidi.user_context.session.currentFrame()) |frame| frame.url else "about:blank";
return cmd.sendResult(.{
.contexts = &[_]Info{.{
.url = url,
.context = &ctx.id,
.userContext = bidi.user_context.id(),
.clientWindow = client_window,
}},
});
}
fn create(cmd: *BiDi.Command) !void {
const p = try cmd.params(struct {
type: enum { tab, window },
userContext: ?[]const u8 = null,
referenceContext: ?[]const u8 = null,
background: bool = false,
});
const bidi = cmd.bidi;
if (bidi.browsing_context != null) {
log.debug(.not_implemented, "bidi.BrowingContext", .{ .feature = "multiple user contexts" });
return cmd.sendError("unsupported operation", "only a single browsing context is supported");
}
const requested = p.userContext orelse "default";
if (std.mem.eql(u8, requested, bidi.user_context.id()) == false) {
return cmd.sendError("no such user context", "unknown user context");
}
const ctx = openContext(bidi) catch |err| switch (err) {
error.CreatePage => return cmd.sendError("unknown error", "failed to create page"),
else => return err,
};
return cmd.sendResult(.{ .context = &ctx.id });
}
// The top-level browsing context, on a fresh about:blank page.
pub fn openContext(bidi: *BiDi) !*Context {
const page = bidi.user_context.session.createPage() catch |err| {
log.err(.bidi, "create page", .{ .err = err });
return error.CreatePage;
};
bidi.browsing_context = .{
.id = undefined,
.realm_id = undefined,
.frame_id = page.frame_id,
.navigation_id = undefined,
};
const ctx = &bidi.browsing_context.?;
uuidv4(&ctx.id);
uuidv4(&ctx.realm_id);
uuidv4(&ctx.navigation_id);
try bidi.sendEvent("browsingContext.contextCreated", .{
.context = &ctx.id,
.url = "about:blank",
.userContext = bidi.user_context.id(),
.clientWindow = client_window,
.originalOpener = null,
.children = null,
});
// A fresh page has no document; give it one so evaluation and getTree
// have something to work against before the first navigate.
if (page.frame()) |frame| {
frame.navigate("about:blank", .{
.reason = .address_bar,
.kind = .{ .push = null },
}) catch |err| {
log.warn(.bidi, "blank navigate", .{ .err = err });
};
try announceRealm(bidi, frame);
}
return ctx;
}
fn announceRealm(bidi: *BiDi, frame: *const Frame) !void {
const ctx = &(bidi.browsing_context orelse return);
if (ctx.realm_announced) {
return;
}
ctx.realm_announced = true;
const origin = (URL.getOrigin(bidi.message_arena.allocator(), frame.url) catch null) orelse "null";
return bidi.sendEvent("script.realmCreated", .{
.realm = &ctx.realm_id,
.origin = origin,
.type = "window",
.context = &ctx.id,
});
}
fn bidiNavigate(cmd: *BiDi.Command) !void {
const p = try cmd.params(struct {
url: [:0]const u8,
context: []const u8,
wait: NavigateOpts.Wait = .none,
});
const ctx = (try requireContext(cmd, p.context)) orelse return;
return navigate(cmd, ctx, .{ .url = p.url, .wait = p.wait });
}
fn bidiReload(cmd: *BiDi.Command) !void {
const p = try cmd.params(struct {
context: []const u8,
wait: NavigateOpts.Wait = .none,
});
const ctx = (try requireContext(cmd, p.context)) orelse return;
return reload(cmd, ctx, p.wait);
}
fn bidiTraverseHistory(cmd: *BiDi.Command) !void {
const p = try cmd.params(struct {
context: []const u8,
delta: i32,
});
const ctx = (try requireContext(cmd, p.context)) orelse return;
const frame = cmd.bidi.user_context.session.currentFrame() orelse {
return cmd.sendError("unknown error", "no frame");
};
if (canTraverse(frame, p.delta) == false) {
return cmd.sendError("no such history entry", "no history entry at that delta");
}
if (p.delta == 0) {
// the current entry, history.go(0) would reload it
return cmd.sendDone();
}
return traverse(cmd, ctx, frame, p.delta);
}
pub const NavigateOpts = struct {
url: [:0]const u8,
wait: Wait,
pub const Wait = enum { none, interactive, complete };
};
pub fn navigate(cmd: *BiDi.Command, ctx: *Context, opts: NavigateOpts) !void {
const frame = cmd.bidi.user_context.session.currentFrame() orelse {
return cmd.sendError("unknown error", "no frame");
};
const encoded_url = URL.resolveNavigation(frame.call_arena, opts.url, .{}) catch {
return cmd.sendError("invalid argument", "invalid url");
};
return startNavigation(cmd, ctx, frame, encoded_url, .{ .reason = .address_bar, .kind = .{ .push = null } }, opts.wait);
}
// Reloads the current document, replaying its method and body like CDP's
// Page.reload.
pub fn reload(cmd: *BiDi.Command, ctx: *Context, wait: NavigateOpts.Wait) !void {
const frame = cmd.bidi.user_context.session.currentFrame() orelse {
return cmd.sendError("unknown error", "no frame");
};
// the frame's arena, which these live in, is gone once the reload commits
const arena = cmd.arena;
const url = try arena.dupeSentinel(u8, frame.url, 0);
var nav_opts: Frame.NavigateOpts = .{ .reason = .address_bar, .kind = .reload };
if (frame._navigated_options) |prev| {
nav_opts.method = prev.method;
nav_opts.body = if (prev.body) |b| try arena.dupe(u8, b) else null;
nav_opts.header = if (prev.header) |h| try arena.dupeSentinel(u8, h, 0) else null;
}
return startNavigation(cmd, ctx, frame, url, nav_opts, wait);
}
fn startNavigation(cmd: *BiDi.Command, ctx: *Context, frame: *Frame, url: [:0]const u8, nav_opts: Frame.NavigateOpts, wait: NavigateOpts.Wait) !void {
const bidi = cmd.bidi;
// A second navigate supersedes an in-flight one; answer the old command
// so the client isn't left waiting on it forever.
try rejectPending(bidi, ctx, "navigation superseded");
// Set before starting: a navigation can reach its wait condition
// synchronously (about:blank), which would fire the lifecycle callback
// before we got a chance to record the pending command.
switch (wait) {
.none => {},
.interactive => ctx.pending_navigate = .{ .reply = cmd.takeReply(), .until = .interactive },
.complete => ctx.pending_navigate = .{ .reply = cmd.takeReply(), .until = .complete },
}
// Same fast path as CDP's Page.navigate: a root frame that never
// navigated has nothing to preserve, so it navigates in place; a live
// page goes through the pending-Page replacement machinery.
const nav_result = if (frame._load_state == .waiting)
frame.navigate(url, nav_opts)
else
bidi.user_context.session.initiateRootNavigation(frame._frame_id, url, nav_opts);
nav_result catch |err| {
log.debug(.bidi, "navigate", .{ .err = err });
if (wait != .none and ctx.pending_navigate == null) {
// the lifecycle already answered it
return;
}
ctx.pending_navigate = null;
return cmd.sendError("unknown error", "navigation failed");
};
if (wait == .none) {
return cmd.sendResult(.{ .navigation = &ctx.navigation_id, .url = url });
}
}
// Whether the session history has an entry `delta` steps from the current one.
pub fn canTraverse(frame: *const Frame, delta: i32) bool {
const navigation = frame._session.navigationFor(frame);
const target = @as(i64, @intCast(navigation._index)) + delta;
return target >= 0 and target < navigation._entries.items.len;
}
// Traverses the session history like history.go(delta), popstate and
// hashchange included. A same-document entry answers right away, any other
// once the new document loads.
pub fn traverse(cmd: *BiDi.Command, ctx: *Context, frame: *Frame, delta: i32) !void {
{
// History expects to be called from JS, with an active local.
const prev_local = frame.js.local;
defer frame.js.local = prev_local;
var ls: js.Local.Scope = undefined;
frame.js.localScope(&ls);
defer ls.deinit();
frame.js.local = &ls.local;
try frame.window._history.go(delta, frame);
}
return answerAfterNavigation(cmd, ctx, frame);
}
// For commands that start a navigation, e.g. clicking a link.
pub fn answerAfterNavigation(cmd: *BiDi.Command, ctx: *Context, frame: *const Frame) !void {
if (frame._queued_navigation == null) {
return cmd.sendDone();
}
// There was an already queued navigation, reject the previous pending command
try rejectPending(cmd.bidi, ctx, "navigation superseded");
ctx.pending_navigate = .{ .reply = cmd.takeReply(), .until = .complete };
}
fn close(cmd: *BiDi.Command) !void {
const p = try cmd.params(struct {
context: []const u8,
});
const ctx = (try requireContext(cmd, p.context)) orelse return;
try destroy(cmd, ctx);
return cmd.sendResult(struct {}{});
}
// Closes the page behind `ctx` and reports it gone.
pub fn destroy(cmd: *BiDi.Command, ctx: *Context) !void {
const bidi = cmd.bidi;
try rejectPending(bidi, ctx, "browsing context closed");
// ctx points into bidi.browsing_context, which is about to be cleared
const gone = ctx.*;
// the input state map is keyed by top-level browsing context
bidi.input_state.reset(bidi.app.allocator);
// the frame's url doesn't survive closePage
const url: []const u8 = if (bidi.user_context.session.currentFrame()) |frame|
try cmd.arena.dupe(u8, frame.url)
else
"about:blank";
bidi.user_context.session.closePage(gone.frame_id);
bidi.browsing_context = null;
try cmd.sendEvent("browsingContext.contextDestroyed", .{
.context = &gone.id,
.url = url,
.userContext = bidi.user_context.id(),
.clientWindow = client_window,
.originalOpener = null,
.children = null,
});
}
fn locateNodes(cmd: *BiDi.Command) !void {
const p = try cmd.params(struct {
context: []const u8,
locator: struct {
type: enum { css, xpath, innerText, accessibility, context },
value: std.json.Value,
},
maxNodeCount: ?u32 = null,
serializationOptions: remote_value.SerializationOptions = .{},
startNodes: []const std.json.Value = &.{},
});
if ((try requireContext(cmd, p.context)) == null) {
return;
}
if (p.maxNodeCount == 0) {
return cmd.sendError("invalid argument", "maxNodeCount must be at least 1");
}
const selector = switch (p.locator.type) {
.css, .xpath => switch (p.locator.value) {
.string => |str| str,
else => return cmd.sendError("invalid argument", "locator value must be a string"),
},
.innerText, .accessibility, .context => {
log.debug(.not_implemented, "bidi.locateNodes", .{ .locator = @tagName(p.locator.type) });
return cmd.sendError("unsupported operation", "locator type is not supported");
},
};
const locator: Locator = if (p.locator.type == .css) .{ .css = selector } else .{ .xpath = selector };
const bidi = cmd.bidi;
const frame = bidi.user_context.session.currentFrame() orelse {
return cmd.sendError("no such frame", "no frame");
};
const arena = cmd.arena;
// The document is the default root
var roots: []const *Node = &.{frame.window._document.asNode()};
if (p.startNodes.len > 0) {
const start_nodes = try arena.alloc(*Node, p.startNodes.len);
for (p.startNodes, start_nodes) |ref, *node| {
const shared_id = switch (ref) {
.object => |o| o.get("sharedId") orelse .null,
else => .null,
};
node.* = remote_value.nodeFromSharedId(&bidi.node_registry, shared_id) catch {
return cmd.sendError("no such node", "unknown start node");
};
if (node.*.is(Node.Element) == null and node.*.is(Node.Document) == null and node.*.is(Node.DocumentFragment) == null) {
return cmd.sendError("invalid argument", "start nodes must be elements, documents or document fragments");
}
}
roots = start_nodes;
}
var ls: js.Local.Scope = undefined;
frame.js.localScope(&ls);
defer ls.deinit();
var serializer = remote_value.Serializer.init(bidi, arena, frame, &ls.local, p.serializationOptions.options(false));
// Serialized straight from each root's result, stopping at maxNodeCount.
const max = p.maxNodeCount orelse std.math.maxInt(u32);
var remotes: std.ArrayList(remote_value.Remote) = .empty;
for (roots) |root| {
const remaining = max - @as(u32, @intCast(remotes.items.len));
const nodes = locator.locate(arena, root, remaining, frame) catch |err| switch (err) {
error.InvalidSelector => return cmd.sendError("invalid selector", "invalid selector"),
error.NodeSetExpected => return cmd.sendError("invalid selector", "xpath expression must select nodes"),
else => return err,
};
try appendNodes(&remotes, arena, &serializer, nodes, max);
if (remotes.items.len >= max) {
break;
}
}
return cmd.sendResult(.{ .nodes = remotes.items });
}
// What a locator selects, shared by browsingContext.locateNodes and the HTTP
// session's element finders. The last three are WebDriver-only strategies.
pub const Locator = union(enum) {
css: []const u8,
xpath: []const u8,
tag_name: []const u8, // webdriver-only
link_text: []const u8, // webdriver-only
partial_link_text: []const u8, // webdriver-only
pub fn locate(self: Locator, arena: std.mem.Allocator, root: *Node, max: u32, frame: *Frame) ![]const *Node {
if (max == 0) {
return &.{};
}
switch (self) {
.css => |selector| {
if (max == 1) {
const element = Selector.querySelector(root, selector, frame) catch |err| return badSelector("css", selector, err);
const found = element orelse return &.{};
const nodes = try arena.alloc(*Node, 1);
nodes[0] = found.asNode();
return nodes;
}
const list = Selector.querySelectorAll(root, selector, frame) catch |err| return badSelector("css", selector, err);
defer list.deinit(frame.page);
return arena.dupe(*Node, list._nodes[0..@min(list._nodes.len, max)]);
},
.xpath => |expression| {
// TODO: max == 1 could stop at the first match like css
const parsed = XPathParser.parse(arena, expression) catch |err| return badSelector("xpath", expression, err);
const result = xpath.evaluate(arena, parsed, root, frame) catch |err| return badSelector("xpath", expression, err);
const nodes = switch (result) {
.node_set => |nodes| nodes,
else => return error.NodeSetExpected,
};
return nodes[0..@min(nodes.len, max)];
},
.tag_name, .link_text, .partial_link_text => {},
}
const tag_name = switch (self) {
.tag_name => |name| name,
else => "a", // link_text or partial_link_test all sub-filter from <a>
};
var elements = root.getElementsByTagName(tag_name, frame) catch |err| switch (err) {
error.InvalidTagName => return badSelector("tag name", tag_name, err),
else => return err,
};
var text: std.Io.Writer.Allocating = .init(arena);
var found: std.ArrayList(*Node) = .empty;
switch (elements) {
inline else => |*list| while (list.next()) |element| {
const matches = switch (self) {
.tag_name => true,
.link_text, .partial_link_text => |needle| blk: {
// an <a> outside HTML has no rendered text
if (element.getTag() != .a) {
break :blk false;
}
text.clearRetainingCapacity();
try element.getInnerText(&text.writer, frame);
const rendered = std.mem.trim(u8, text.written(), &std.ascii.whitespace);
break :blk switch (self) {
.link_text => std.mem.eql(u8, rendered, needle),
else => std.mem.find(u8, rendered, needle) != null,
};
},
else => unreachable, // css and xpath returned above
};
if (matches) {
try found.append(arena, element.asNode());
if (found.items.len == max) {
break;
}
}
},
}
return found.items;
}
};
fn badSelector(kind: []const u8, selector: []const u8, err: anyerror) error{InvalidSelector} {
log.debug(.bidi, "locate", .{ .kind = kind, .selector = selector, .err = err });
return error.InvalidSelector;
}
fn appendNodes(remotes: *std.ArrayList(remote_value.Remote), arena: std.mem.Allocator, serializer: *remote_value.Serializer, nodes: []const *Node, max: u32) !void {
// Try to optimize this a little for the inherit inefficiency of ArrayList with Arena.
const take = @min(nodes.len, max - remotes.items.len);
try remotes.ensureTotalCapacityPrecise(arena, remotes.items.len + take);
for (nodes[0..take]) |node| {
remotes.appendAssumeCapacity(try serializer.domNode(node));
}
}
fn setViewport(cmd: *BiDi.Command) !void {
const p = try cmd.params(struct {
context: ?[]const u8 = null,
userContexts: ?[]const []const u8 = null,
viewport: Setting(struct { width: u32, height: u32 }) = .keep,
devicePixelRatio: Setting(f32) = .keep,
});
const bidi = cmd.bidi;
if ((p.context == null) == (p.userContexts == null)) {
return cmd.sendError("invalid argument", "exactly one of context and userContexts is required");
}
if (p.context) |context| {
_ = (try requireContext(cmd, context)) orelse return;
}
if (p.userContexts) |user_contexts| {
for (user_contexts) |user_context| {
if (std.mem.eql(u8, user_context, bidi.user_context.id()) == false) {
return cmd.sendError("no such user context", "unknown user context");
}
}
}
var viewport = bidi.browser.getViewport();
switch (p.viewport) {
.keep => {},
.reset => {
viewport.width = Viewport.default.width;
viewport.height = Viewport.default.height;
},
.set => |size| {
if (size.width == 0 or size.height == 0) {
return cmd.sendError("invalid argument", "viewport dimensions must be positive");
}
viewport.width = size.width;
viewport.height = size.height;
},
}
switch (p.devicePixelRatio) {
.keep => {},
.reset => viewport.scale = Viewport.default.scale,
.set => |scale| {
if (scale <= 0) {
return cmd.sendError("invalid argument", "devicePixelRatio must be positive");
}
viewport.scale = scale;
},
}
bidi.browser.setViewportOverride(viewport);
return cmd.sendDone();
}
// A parameter that's left alone when absent, and reset to its default by null.
fn Setting(comptime T: type) type {
return union(enum) {
keep,
reset,
set: T,
pub fn jsonParse(arena: std.mem.Allocator, source: anytype, opts: std.json.ParseOptions) !@This() {
const value = try std.json.innerParse(?T, arena, source, opts);
return if (value) |v| .{ .set = v } else .reset;
}
};
}
pub fn requireContext(cmd: *BiDi.Command, context: []const u8) !?*Context {
if (cmd.bidi.browsing_context) |*ctx| {
if (std.mem.eql(u8, &ctx.id, context)) {
return ctx;
}
}
try cmd.sendError("no such frame", "unknown context");
return null;
}
// Answers `ctx`'s pending navigate command, if any, and clears it.
fn answerPending(bidi: *BiDi, ctx: *Context, url: []const u8) !void {
const pending = ctx.pending_navigate orelse return;
ctx.pending_navigate = null;
switch (pending.reply) {
.bidi => |id| return bidi.sendResult(id, .{
.url = url,
.navigation = &ctx.navigation_id,
}),
// WebDriver's Navigate To answers null
.http => return bidi.respondHTTP(null),
}
}
// Fails `ctx`'s pending navigate command, if any, and clears it. BiDi has no
// navigation-specific error code, so every reason is an "unknown error" and
// only the message distinguishes them.
fn rejectPending(bidi: *BiDi, ctx: *Context, message: []const u8) !void {
const pending = ctx.pending_navigate orelse return;
ctx.pending_navigate = null;
return bidi.replyError(pending.reply, "unknown error", message);
}
pub fn registerNotifications(bidi: *BiDi) !void {
const notification = bidi.notification;
try notification.register(.frame_loaded, bidi, onFrameLoaded);
try notification.register(.frame_remove, bidi, onFrameRemove);
try notification.register(.frame_created, bidi, onFrameCreated);
try notification.register(.frame_destroyed, bidi, onFrameDestroyed);
try notification.register(.frame_navigate, bidi, onFrameNavigate);
try notification.register(.frame_navigate_failed, bidi, onFrameNavigateFailed);
try notification.register(.frame_dom_content_loaded, bidi, onFrameDOMContentLoaded);
}
// The page whose nodes and persisted values these belong to is going away.
fn onFrameRemove(ptr: *anyopaque, _: Notification.FrameRemove) !void {
const bidi: *BiDi = @ptrCast(@alignCast(ptr));
bidi.resetRealm();
}
// A new root document, so a new window realm.
fn onFrameCreated(ptr: *anyopaque, frame: *Frame) !void {
const bidi: *BiDi = @ptrCast(@alignCast(ptr));
if (frame.parent != null or rootContext(bidi, frame._frame_id) == null) {
return;
}
return announceRealm(bidi, frame);
}
fn onFrameDestroyed(ptr: *anyopaque, frame: *const Frame) !void {
const bidi: *BiDi = @ptrCast(@alignCast(ptr));
script.Pending.contextDestroyed(bidi, frame.js.id);
execute.Pending.contextDestroyed(bidi, frame.js.id);
}
fn onFrameNavigate(ptr: *anyopaque, msg: *const Notification.FrameNavigate) !void {
const bidi: *BiDi = @ptrCast(@alignCast(ptr));
const ctx = rootContext(bidi, msg.frame_id) orelse return;
if (msg.is_pending_root == false) {
bidi.resetRealm();
} else {
// pending root keeps its old page and thus its sharedIds and handles
// reachable until frameRemove commits the replacement.
}
uuidv4(&ctx.navigation_id);
try bidi.sendEvent("browsingContext.navigationStarted", .{
.context = &ctx.id,
.navigation = &ctx.navigation_id,
.timestamp = msg.timestamp,
.url = msg.url,
});
}
fn onFrameNavigateFailed(ptr: *anyopaque, msg: *const Notification.FrameNavigateFailed) !void {
const bidi: *BiDi = @ptrCast(@alignCast(ptr));
const ctx = rootContext(bidi, msg.frame_id) orelse return;
try bidi.sendEvent("browsingContext.navigationFailed", .{
.context = &ctx.id,
.navigation = &ctx.navigation_id,
.timestamp = msg.timestamp,
.url = msg.url,
});
try rejectPending(bidi, ctx, "navigation failed");
}
fn onFrameDOMContentLoaded(ptr: *anyopaque, msg: *const Notification.FrameDOMContentLoaded) !void {
return frameLifecycleEvent(ptr, "browsingContext.domContentLoaded", .interactive, msg.frame_id, msg.timestamp);
}
fn onFrameLoaded(ptr: *anyopaque, msg: *const Notification.FrameLoaded) !void {
return frameLifecycleEvent(ptr, "browsingContext.load", .complete, msg.frame_id, msg.timestamp);
}
fn frameLifecycleEvent(
ptr: *anyopaque,
comptime method: []const u8,
reached: PendingNavigate.Until,
frame_id: u32,
timestamp: u64,
) !void {
const bidi: *BiDi = @ptrCast(@alignCast(ptr));
const ctx = rootContext(bidi, frame_id) orelse return;
const url: []const u8 = if (bidi.user_context.session.currentFrame()) |frame| frame.url else "";
try bidi.sendEvent(method, .{
.context = &ctx.id,
.navigation = &ctx.navigation_id,
.timestamp = timestamp,
.url = url,
});
// The response comes after the matching event — drivers key off the
// event, and answering first would let a client see the command
// complete before the lifecycle it waited for.
if (ctx.pending_navigate) |pending| {
if (pending.until == reached) {
try answerPending(bidi, ctx, url);
}
}
}
// Only the root frame maps to the BiDi context; child-frame events are
// dropped until child navigables are supported.
fn rootContext(bidi: *BiDi, frame_id: u32) ?*Context {
if (bidi.browsing_context) |*ctx| {
if (ctx.frame_id == frame_id) {
return ctx;
}
}
return null;
}
// BrowsingContextInfo for getTree. Events send children: null instead of a
// (recursive) list, so they use ad-hoc structs.
const Info = struct {
context: []const u8,
url: []const u8,
userContext: []const u8,
clientWindow: []const u8,
originalOpener: ?[]const u8 = null,
children: []const Info = &.{},
};
const testing = @import("testing.zig");
test "bidi.browsing_context: locateNodes" {
testing.silenceLog(&.{.not_implemented});
var ctx = try testing.context();
defer ctx.deinit();
const context_id = try ctx.createContext(.{ .url = "bidi/locate.html" });
try ctx.processMessage(.{
.id = 1,
.method = "browsingContext.locateNodes",
.params = .{ .context = context_id, .locator = .{ .type = "css", .value = ".item" } },
});
try ctx.expectSentResult(.{ .nodes = .{
.{ .type = "node", .sharedId = "1", .value = .{ .nodeType = 1, .localName = "li", .attributes = .{ .class = "item" } } },
.{ .type = "node", .sharedId = "2", .value = .{ .localName = "li" } },
.{ .type = "node", .sharedId = "3", .value = .{ .localName = "li" } },
.{ .type = "node", .sharedId = "4", .value = .{ .localName = "span" } },
} }, .{ .id = 1 });
// maxNodeCount truncates in document order
try ctx.processMessage(.{
.id = 2,
.method = "browsingContext.locateNodes",
.params = .{ .context = context_id, .locator = .{ .type = "css", .value = ".item" }, .maxNodeCount = 2 },
});
try ctx.expectSentResult(.{ .nodes = .{
.{ .type = "node", .sharedId = "1" },
.{ .type = "node", .sharedId = "2" },
} }, .{ .id = 2 });
// xpath, with serializationOptions
try ctx.processMessage(.{
.id = 3,
.method = "browsingContext.locateNodes",
.params = .{
.context = context_id,
.locator = .{ .type = "xpath", .value = "//div[@id='other']" },
.serializationOptions = .{ .maxDomDepth = 1 },
},
});
try ctx.expectSentResult(.{ .nodes = .{
.{ .type = "node", .value = .{
.localName = "div",
.children = .{.{ .type = "node", .sharedId = "4", .value = .{ .localName = "span" } }},
} },
} }, .{ .id = 3 });
// startNodes scope the search
try ctx.processMessage(.{
.id = 4,
.method = "browsingContext.locateNodes",
.params = .{
.context = context_id,
.locator = .{ .type = "css", .value = ".item" },
.startNodes = .{.{ .sharedId = "5" }},
},
});
try ctx.expectSentResult(.{ .nodes = .{
.{ .type = "node", .sharedId = "4" },
} }, .{ .id = 4 });
try ctx.processMessage(.{
.id = 5,
.method = "browsingContext.locateNodes",
.params = .{
.context = context_id,
.locator = .{ .type = "xpath", .value = ".//*[@class='item']" },
.startNodes = .{ .{ .sharedId = "5" }, .{ .sharedId = "1" } },
},
});
try ctx.expectSentResult(.{ .nodes = .{
.{ .type = "node", .sharedId = "4" },
} }, .{ .id = 5 });
// maxNodeCount 1 takes the querySelector path; the first root has no match
try ctx.processMessage(.{
.id = 14,
.method = "browsingContext.locateNodes",
.params = .{
.context = context_id,
.locator = .{ .type = "css", .value = ".item" },
.startNodes = .{ .{ .sharedId = "1" }, .{ .sharedId = "5" } },
.maxNodeCount = 1,
},
});
try ctx.expectSentResult(.{ .nodes = .{
.{ .type = "node", .sharedId = "4" },
} }, .{ .id = 14 });
try ctx.processMessage(.{
.id = 15,
.method = "browsingContext.locateNodes",
.params = .{ .context = context_id, .locator = .{ .type = "css", .value = ".item[" }, .maxNodeCount = 1 },
});
try ctx.expectSentError("invalid selector", null, .{ .id = 15 });
// An absolute xpath ignores the start node, as in any browser.
try ctx.processMessage(.{
.id = 13,
.method = "browsingContext.locateNodes",
.params = .{
.context = context_id,
.locator = .{ .type = "xpath", .value = "//li" },
.startNodes = .{.{ .sharedId = "5" }},
},
});
try ctx.expectSentResult(.{ .nodes = .{
.{ .type = "node", .sharedId = "1" },
.{ .type = "node", .sharedId = "2" },
.{ .type = "node", .sharedId = "3" },
} }, .{ .id = 13 });
// errors
try ctx.processMessage(.{
.id = 6,
.method = "browsingContext.locateNodes",
.params = .{ .context = context_id, .locator = .{ .type = "css", .value = ".item[" } },
});
try ctx.expectSentError("invalid selector", null, .{ .id = 6 });
try ctx.processMessage(.{
.id = 7,
.method = "browsingContext.locateNodes",
.params = .{ .context = context_id, .locator = .{ .type = "xpath", .value = "count(//li)" } },
});
try ctx.expectSentError("invalid selector", null, .{ .id = 7 });
try ctx.processMessage(.{
.id = 8,
.method = "browsingContext.locateNodes",
.params = .{ .context = context_id, .locator = .{ .type = "xpath", .value = "//li[" } },
});
try ctx.expectSentError("invalid selector", null, .{ .id = 8 });
try ctx.processMessage(.{
.id = 9,
.method = "browsingContext.locateNodes",
.params = .{ .context = context_id, .locator = .{ .type = "css", .value = ".item" }, .startNodes = .{.{ .sharedId = "999" }} },
});
try ctx.expectSentError("no such node", null, .{ .id = 9 });
try ctx.processMessage(.{
.id = 10,
.method = "browsingContext.locateNodes",
.params = .{ .context = context_id, .locator = .{ .type = "css", .value = ".item" }, .maxNodeCount = 0 },
});
try ctx.expectSentError("invalid argument", null, .{ .id = 10 });
try ctx.processMessage(.{
.id = 11,
.method = "browsingContext.locateNodes",
.params = .{ .context = context_id, .locator = .{ .type = "innerText", .value = "a" } },
});
try ctx.expectSentError("unsupported operation", null, .{ .id = 11 });
try ctx.processMessage(.{
.id = 12,
.method = "browsingContext.locateNodes",
.params = .{ .context = "nope", .locator = .{ .type = "css", .value = ".item" } },
});
try ctx.expectSentError("no such frame", null, .{ .id = 12 });
}
test "bidi.browsing_context: window realm lifecycle" {
var ctx = try testing.context();
defer ctx.deinit();
try ctx.startSession();
try ctx.processMessage(.{ .id = 1, .method = "session.subscribe", .params = .{ .events = .{"script"} } });
try ctx.processMessage(.{ .id = 2, .method = "browsingContext.create", .params = .{ .type = "tab" } });
const bc = &(ctx.bidi().browsing_context orelse return error.NoBrowsingContext);
const context_id = try testing.arena.dupe(u8, &bc.id);
const realm1 = try testing.arena.dupe(u8, &bc.realm_id);
try ctx.expectSentEvent("script.realmCreated", .{ .realm = realm1, .type = "window", .context = context_id, .origin = "null" });
// a navigation is a new document and so a new realm
try ctx.processMessage(.{
.id = 3,
.method = "browsingContext.navigate",
.params = .{ .context = context_id, .url = testing.test_server ++ "bidi/values.html", .wait = "complete" },
});
try ctx.wait();
const realm2 = try testing.arena.dupe(u8, &bc.realm_id);
try testing.expect(std.mem.eql(u8, realm1, realm2) == false);
try ctx.expectSentEvent("script.realmDestroyed", .{ .realm = realm1 });
try ctx.expectSentEvent("script.realmCreated", .{ .realm = realm2, .type = "window", .context = context_id, .origin = "http://127.0.0.1:9582" });
try ctx.expectSentResult(.{ .navigation = &bc.navigation_id }, .{ .id = 3 });
}
test "bidi.browsing_context: setViewport" {
var ctx = try testing.context();
defer ctx.deinit();
const context_id = try ctx.createContext(.{ .url = "bidi/values.html" });
try ctx.processMessage(.{
.id = 1,
.method = "browsingContext.setViewport",
.params = .{ .context = context_id, .viewport = .{ .width = 375, .height = 812 }, .devicePixelRatio = 3 },
});
try ctx.expectSentResult(null, .{ .id = 1 });
try ctx.processMessage(.{
.id = 2,
.method = "script.evaluate",
.params = .{ .expression = "`${innerWidth}x${innerHeight}@${devicePixelRatio}`", .awaitPromise = false, .target = .{ .context = context_id } },
});
try ctx.expectSentResult(.{ .type = "success", .result = .{ .type = "string", .value = "375x812@3" } }, .{ .id = 2 });
// an absent field is kept, a null one is reset
try ctx.processMessage(.{
.id = 3,
.method = "browsingContext.setViewport",
.params = .{ .userContexts = .{"default"}, .viewport = null },
});
try ctx.expectSentResult(null, .{ .id = 3 });
const viewport = ctx.bidi().browser.getViewport();
try testing.expectEqual(Viewport.default.width, viewport.width);
try testing.expectEqual(Viewport.default.height, viewport.height);
try testing.expectEqual(3, viewport.scale);
try ctx.processMessage(.{ .id = 4, .method = "browsingContext.setViewport", .params = .{ .viewport = null } });
try ctx.expectSentError("invalid argument", null, .{ .id = 4 });
try ctx.processMessage(.{ .id = 5, .method = "browsingContext.setViewport", .params = .{ .context = "nope" } });
try ctx.expectSentError("no such frame", null, .{ .id = 5 });
try ctx.processMessage(.{ .id = 6, .method = "browsingContext.setViewport", .params = .{ .userContexts = .{"nope"} } });
try ctx.expectSentError("no such user context", null, .{ .id = 6 });
try ctx.processMessage(.{
.id = 7,
.method = "browsingContext.setViewport",
.params = .{ .context = context_id, .viewport = .{ .width = 0, .height = 10 } },
});
try ctx.expectSentError("invalid argument", null, .{ .id = 7 });
}
test "bidi.browsing_context: traverseHistory and reload" {
var ctx = try testing.context();
defer ctx.deinit();
const context_id = try ctx.createContext(.{ .url = "bidi/values.html" });
try ctx.processMessage(.{
.id = 1,
.method = "browsingContext.navigate",
.params = .{ .context = context_id, .url = testing.test_server ++ "bidi/locate.html", .wait = "complete" },
});
try ctx.wait();
try ctx.expectSentResult(.{ .url = testing.test_server ++ "bidi/locate.html" }, .{ .id = 1 });
// about:blank, values.html, locate.html
try ctx.processMessage(.{ .id = 2, .method = "browsingContext.traverseHistory", .params = .{ .context = context_id, .delta = 1 } });
try ctx.expectSentError("no such history entry", null, .{ .id = 2 });
try ctx.processMessage(.{ .id = 3, .method = "browsingContext.traverseHistory", .params = .{ .context = context_id, .delta = -3 } });
try ctx.expectSentError("no such history entry", null, .{ .id = 3 });
try ctx.processMessage(.{ .id = 4, .method = "browsingContext.traverseHistory", .params = .{ .context = "nope", .delta = -1 } });
try ctx.expectSentError("no such frame", null, .{ .id = 4 });
try ctx.processMessage(.{ .id = 5, .method = "browsingContext.traverseHistory", .params = .{ .context = context_id, .delta = -1 } });
try ctx.wait();
try ctx.expectSentResult(.{ .url = testing.test_server ++ "bidi/values.html" }, .{ .id = 5 });
try testing.expectEqual(testing.test_server ++ "bidi/values.html", (try ctx.frame()).url);
// a same-document entry answers without a load
try ctx.processMessage(.{
.id = 6,
.method = "script.evaluate",
.params = .{ .expression = "history.pushState(null, '', '#pushed')", .awaitPromise = false, .target = .{ .context = context_id } },
});
try ctx.processMessage(.{ .id = 7, .method = "browsingContext.traverseHistory", .params = .{ .context = context_id, .delta = -1 } });
try ctx.expectSentResult(null, .{ .id = 7 });
try testing.expectEqual(testing.test_server ++ "bidi/values.html", (try ctx.frame()).url);
try ctx.processMessage(.{ .id = 8, .method = "browsingContext.reload", .params = .{ .context = context_id, .wait = "complete" } });
try ctx.wait();
try ctx.expectSentResult(.{ .url = testing.test_server ++ "bidi/values.html" }, .{ .id = 8 });
}