use std::collections::{BTreeMap, HashMap};
use crate::{
AgentSnapshot, DebugError, DebugResponse, KeyPhase, Modifiers as ControlModifiers, SemanticNode,
};
#[cfg(feature = "capture")]
use crate::{
DebugSnapshot, FrameMetrics, FrameWindowMetrics, LayoutBounds, LayoutDiagnosticRow,
LayoutEdges, LayoutOffset, LayoutSize, RendererMetrics, RevisionSet, ScriptMetrics,
ScriptSource, SnapshotCost, SnapshotRequest, TimingStats,
};
use blitz_dom::Document;
use blitz_script::ScriptDocument;
use blitz_traits::events::{
BlitzKeyEvent, BlitzPointerEvent, BlitzPointerId, KeyState, MouseEventButton,
MouseEventButtons, Point, PointerCoords, PointerDetails, UiEvent,
};
#[cfg(feature = "capture")]
use blitz_traits::node_id::NodeId;
use keyboard_types::{Code, Key, Location, Modifiers as KeyboardModifiers};
#[cfg(feature = "capture")]
pub(crate) struct CaptureSurface {
pub(crate) width: u32,
pub(crate) height: u32,
pub(crate) renderer: anyrender_vello_cpu::VelloCpuImageRenderer,
pub(crate) rgba: Vec<u8>,
}
#[cfg(feature = "capture")]
pub struct DocumentCapture {
surface: Option<CaptureSurface>,
}
#[cfg(feature = "capture")]
impl DocumentCapture {
pub fn new() -> Self {
Self { surface: None }
}
pub fn capture(
&mut self,
document: &mut ScriptDocument,
request: crate::CaptureRequest,
) -> Result<crate::CapturedImage, DebugError> {
capture_document_with_surface(document, request, &mut self.surface)
}
}
#[cfg(feature = "capture")]
impl Default for DocumentCapture {
fn default() -> Self {
Self::new()
}
}
#[cfg(feature = "capture")]
impl CaptureSurface {
pub(crate) fn new(width: u32, height: u32) -> Self {
use anyrender::ImageRenderer as _;
Self {
width,
height,
renderer: anyrender_vello_cpu::VelloCpuImageRenderer::new(width, height),
rgba: Vec::with_capacity((width as usize) * (height as usize) * 4),
}
}
pub(crate) fn size_to(&mut self, width: u32, height: u32) {
use anyrender::ImageRenderer as _;
if self.width == width && self.height == height {
return;
}
self.renderer.resize(width, height);
self.width = width;
self.height = height;
}
}
#[cfg(feature = "capture")]
pub fn capture_document(
script_document: &mut ScriptDocument,
request: crate::CaptureRequest,
) -> Result<crate::CapturedImage, DebugError> {
DocumentCapture::new().capture(script_document, request)
}
#[cfg(feature = "capture")]
pub(crate) fn capture_document_with_surface(
script_document: &mut ScriptDocument,
request: crate::CaptureRequest,
surface: &mut Option<CaptureSurface>,
) -> Result<crate::CapturedImage, DebugError> {
use anyrender::ImageRenderer;
use base64::Engine as _;
let scale = if request.scale.is_finite() && request.scale > 0.0 {
request.scale.clamp(0.1, 8.0)
} else {
1.0
};
let node_id = request.node_id;
script_document.inner_mut().resolve(0.0);
let (full_width, full_height) = {
let inner = script_document.inner();
let viewport = inner.viewport();
(viewport.window_size.0, viewport.window_size.1)
};
if full_width == 0 || full_height == 0 {
return Err(debug_error(
"captureUnavailable",
"the document has no viewport to draw",
));
}
let (crop_x, crop_y, crop_width, crop_height) = match node_id {
None => (
0.0_f64,
0.0_f64,
f64::from(full_width),
f64::from(full_height),
),
Some(id) => {
let inner = script_document.inner();
let rect = inner
.get_client_bounding_rect(NodeId::from_u64(id))
.ok_or_else(|| debug_error("unknownNode", &format!("no node {id}")))?;
if rect.width <= 0.0 || rect.height <= 0.0 {
return Err(debug_error(
"captureEmpty",
&format!("node {id} has a zero-sized box, so there is nothing to capture"),
));
}
(rect.x, rect.y, rect.width, rect.height)
}
};
let full_pixel_width = ((f64::from(full_width) * f64::from(scale)).round() as u32).max(1);
let full_pixel_height = ((f64::from(full_height) * f64::from(scale)).round() as u32).max(1);
let left = ((crop_x * f64::from(scale)).round().max(0.0) as u32).min(full_pixel_width);
let top = ((crop_y * f64::from(scale)).round().max(0.0) as u32).min(full_pixel_height);
let width = ((crop_width * f64::from(scale)).round() as u32)
.min(full_pixel_width.saturating_sub(left))
.max(1);
let height = ((crop_height * f64::from(scale)).round() as u32)
.min(full_pixel_height.saturating_sub(top))
.max(1);
const FRAME_ENVELOPE_RESERVE: usize = 64 * 1024;
const MAX_BASE64_BYTES: usize = crate::MAX_DEBUG_FRAME_BYTES - FRAME_ENVELOPE_RESERVE;
const MAX_RAW_BYTES: usize = (MAX_BASE64_BYTES / 4) * 3;
const MAX_PIXELS: u64 = (MAX_RAW_BYTES / 4) as u64;
if u64::from(width) * u64::from(height) > MAX_PIXELS {
return Err(debug_error(
"captureTooLarge",
&format!(
"{width}x{height} cannot fit in one diagnostic frame; capture a node or lower the scale"
),
));
}
let surface = surface.get_or_insert_with(|| CaptureSurface::new(width, height));
surface.size_to(width, height);
surface.renderer.reset();
let mut document = script_document.inner_mut();
surface.renderer.render_to_vec(
|scene| {
if node_id.is_some() {
blitz_paint::paint_scene_region(
scene,
&mut document,
blitz_paint::PaintRegion::crop(
f64::from(scale),
f64::from(left) / f64::from(scale),
f64::from(top) / f64::from(scale),
width,
height,
),
);
} else {
blitz_paint::paint_scene(
scene,
&mut document,
f64::from(scale),
width,
height,
0,
0,
);
}
},
&mut surface.rgba,
);
Ok(crate::CapturedImage {
width,
height,
rgba_base64: base64::engine::general_purpose::STANDARD.encode(&surface.rgba),
node_id,
})
}
fn drain_for_observer(document: &mut ScriptDocument) -> (u64, u64) {
const BUDGET: std::time::Duration = std::time::Duration::from_millis(16);
let started = std::time::Instant::now();
let (mut progressed, mut passes) = (0u64, 0u64);
while passes < 100 && started.elapsed() < BUDGET {
passes += 1;
if !document.poll_for_settle(None, false) {
break;
}
progressed += 1;
}
(progressed, passes)
}
#[cfg(feature = "capture")]
pub fn snapshot_document(
document: &mut ScriptDocument,
request: SnapshotRequest,
revision: u64,
) -> Result<DebugSnapshot, DebugError> {
let started = std::time::Instant::now();
let poll_started = std::time::Instant::now();
let polls = drain_for_observer(document).1;
let poll_ms = poll_started.elapsed().as_secs_f64() * 1_000.0;
let resolve_started = std::time::Instant::now();
document.inner_mut().resolve(0.0);
let snapshot_resolve_ms = resolve_started.elapsed().as_secs_f64() * 1_000.0;
let inner = document.inner();
let layout_node_limit = inner.tree().iter().count();
let active_element = inner.get_focussed_node_id().map(|id| id.as_u64());
let labels = LabelIndex::build(&inner);
let nodes: Vec<SemanticNode> = inner
.tree()
.iter()
.filter_map(|(id, node)| {
if !request.node_ids.is_empty() && !request.node_ids.contains(&id.as_u64()) {
return None;
}
let element = node.element_data()?;
if !dom_chain_is_attached(&inner, id, layout_node_limit)
|| !layout_chain_is_valid(&inner, id, layout_node_limit)
{
return None;
}
let rect = inner.get_client_bounding_rect(id);
let visible = node_is_visible(&inner, id)
&& rect
.as_ref()
.is_some_and(|rect| rect.width > 0.0 && rect.height > 0.0);
let role = semantic_role(element);
let value = if role == "generic" {
Some(
element
.attrs()
.iter()
.map(|attribute| format!("{}={}", attribute.name.local, attribute.value))
.collect::<Vec<_>>()
.join(" "),
)
} else {
semantic_value(element, &inner, id)
};
Some(SemanticNode {
dom_id: element_attr(element, "id").map(str::to_owned),
id: id.as_u64(),
parent: semantic_parent(&inner, id, None).map(|id| id.as_u64()),
name: semantic_name(element, node, &role, &inner, id, &labels),
role,
value,
enabled: element_attr(element, "disabled").is_none()
&& element_attr(element, "aria-disabled") != Some("true"),
focusable: focuses_on_click(element),
viewport_fixed: viewport_fixed_descendant(&inner, id, layout_node_limit),
visible,
selected: semantic_selected(element, &inner, id),
bounds: rect.and_then(|rect| {
let bounds = [rect.x, rect.y, rect.width, rect.height];
bounds
.iter()
.all(|value| value.is_finite())
.then_some(bounds)
}),
slot: element_attr(element, "data-slot").map(str::to_owned),
attributes: semantic_target_attributes(element),
})
})
.collect();
let total_ms = started.elapsed().as_secs_f64() * 1_000.0;
let revisions = RevisionSet {
document: revision,
style: 0,
layout: 0,
paint: 0,
};
let frame_stats = blitz_shell::latest_frame_stats();
let metrics = RendererMetrics {
revisions: revisions.clone(),
queue_depth: None,
invalidations_coalesced: polls.saturating_sub(1),
frame: frame_stats.as_ref().map(|stats| FrameMetrics {
input_to_present_ms: None,
style_ms: None,
layout_ms: None,
resolve_ms: stats.latest.resolve_ms,
scene_ms: stats.latest.paint_ms,
submit_ms: None,
present_ms: None,
renderer_ms: stats.latest.renderer_ms,
total_ms: stats.latest.total_ms,
age_ms: stats.latest.age_ms,
}),
frame_window: frame_stats.as_ref().map(|stats| FrameWindowMetrics {
frames_total: stats.frames_total,
window_frames: stats.window_frames,
resolve: timing_stats(stats.resolve),
scene: timing_stats(stats.paint),
renderer: timing_stats(stats.renderer),
total: timing_stats(stats.frame_total),
interval: timing_stats(stats.interval),
active_fps: stats.active_fps,
missed_refreshes: stats.missed_refreshes,
display_refresh_hz: stats.display_refresh_hz,
}),
snapshot: Some(SnapshotCost {
poll_ms,
resolve_ms: snapshot_resolve_ms,
total_ms,
}),
script: blitz_script::script_stats::latest_script_stats().map(|stats| ScriptMetrics {
mean_ms: stats.mean_ms,
p95_ms: stats.p95_ms,
max_ms: stats.max_ms,
window_polls: stats.window_polls,
total_polls: stats.total_polls,
productive_polls: stats.productive_polls,
spent_ms: stats.spent_ms,
breakdown: blitz_script::script_stats::work_breakdown()
.into_iter()
.take(12)
.map(|(label, calls, total_ms, worst_ms)| ScriptSource {
label,
calls,
total_ms,
worst_ms,
})
.collect(),
}),
resident_bytes: resident_bytes(),
};
let dom = request
.include_dom
.then(|| serde_json::to_value(&nodes).unwrap_or(serde_json::Value::Null));
let layout = request.include_layout.then(|| {
nodes
.iter()
.filter_map(|node| diagnostic_layout_row(&inner, node))
.collect()
});
let computed_style = request.include_computed_style.then(|| {
serde_json::Value::Array(
nodes
.iter()
.filter_map(|node| diagnostic_style_row(&inner, node))
.collect(),
)
});
Ok(DebugSnapshot {
revisions,
active_window: Some("blitz-main".into()),
active_element,
dom,
layout,
computed_style,
metrics,
})
}
pub(crate) fn element_attr<'a>(element: &'a blitz_dom::ElementData, name: &str) -> Option<&'a str> {
element
.attrs()
.iter()
.find(|attribute| attribute.name.local.as_ref() == name)
.map(|attribute| attribute.value.as_ref())
}
fn semantic_target_attributes(element: &blitz_dom::ElementData) -> BTreeMap<String, String> {
element
.attrs()
.iter()
.filter_map(|attribute| {
let name = attribute.name.local.as_ref();
(name.starts_with("aria-") || name.starts_with("data-")).then(|| {
let value: &str = attribute.value.as_ref();
(name.to_owned(), value.to_owned())
})
})
.collect()
}
pub(crate) fn semantic_role(element: &blitz_dom::ElementData) -> String {
semantic_role_ref(element).to_owned()
}
pub(crate) fn semantic_role_ref(element: &blitz_dom::ElementData) -> &str {
if let Some(role) = element_attr(element, "role") {
return role;
}
wire_role(blitz_dom::accessibility::implicit_role(element))
}
fn wire_role(role: blitz_dom::accesskit::Role) -> &'static str {
use blitz_dom::accesskit::Role;
match role {
Role::Link => "link",
Role::Button => "button",
Role::CheckBox => "checkbox",
Role::RadioButton => "radio",
Role::Slider => "slider",
Role::ComboBox => "combobox",
Role::ListBox => "combobox",
Role::ListBoxOption => "option",
Role::TextInput
| Role::MultilineTextInput
| Role::SearchInput
| Role::DateInput
| Role::DateTimeInput
| Role::WeekInput
| Role::MonthInput
| Role::TimeInput
| Role::EmailInput
| Role::NumberInput
| Role::PasswordInput
| Role::PhoneNumberInput
| Role::UrlInput
| Role::ColorWell => "textbox",
Role::Image => "img",
Role::Navigation => "navigation",
Role::Main => "main",
Role::Region => "region",
Role::Form => "form",
Role::List => "list",
Role::ListItem => "listitem",
Role::Table => "table",
Role::Row => "row",
Role::Cell => "cell",
Role::ColumnHeader => "columnheader",
Role::RowHeader => "rowheader",
Role::Heading => "heading",
_ => "generic",
}
}
pub(crate) struct LabelIndex {
by_control_id: std::collections::HashMap<String, String>,
labels: std::collections::HashMap<blitz_dom::NodeId, String>,
by_dom_id: std::collections::HashMap<String, blitz_dom::NodeId>,
}
impl LabelIndex {
pub(crate) fn build(document: &blitz_dom::BaseDocument) -> Self {
let mut by_control_id = std::collections::HashMap::new();
let mut labels = std::collections::HashMap::new();
let mut by_dom_id = std::collections::HashMap::new();
for (id, node) in document.tree().iter() {
let Some(element) = node.element_data() else {
continue;
};
if let Some(dom_id) = element_attr(element, "id") {
by_dom_id.entry(dom_id.to_owned()).or_insert(id);
}
if element.name.local.as_ref() != "label" {
continue;
}
let text = name_text(node, document);
if let Some(control) = element_attr(element, "for") {
by_control_id.insert(control.to_owned(), text.clone());
}
labels.insert(id, text);
}
Self {
by_control_id,
labels,
by_dom_id,
}
}
fn labelled_by(
&self,
document: &blitz_dom::BaseDocument,
element: &blitz_dom::ElementData,
) -> Option<String> {
let reference = element_attr(element, "aria-labelledby")?;
let mut name = String::new();
for token in reference.split_ascii_whitespace() {
let Some(node) = self
.by_dom_id
.get(token)
.and_then(|id| document.get_node(*id))
else {
continue;
};
if !name.is_empty() {
name.push(' ');
}
name.push_str(&name_text(node, document));
}
(!name.trim().is_empty()).then_some(name)
}
fn name_for(
&self,
document: &blitz_dom::BaseDocument,
id: blitz_dom::NodeId,
element: &blitz_dom::ElementData,
) -> Option<String> {
if let Some(dom_id) = element_attr(element, "id")
&& let Some(text) = self.by_control_id.get(dom_id)
&& !text.trim().is_empty()
{
return Some(text.clone());
}
let mut current = document.get_node(id)?.parent;
for _ in 0..16 {
let ancestor = current?;
if let Some(text) = self.labels.get(&ancestor)
&& !text.trim().is_empty()
{
return Some(text.clone());
}
current = document.get_node(ancestor)?.parent;
}
None
}
}
fn name_text(node: &blitz_dom::Node, document: &blitz_dom::BaseDocument) -> String {
fn is_inline(node: &blitz_dom::Node) -> bool {
use style::values::specified::box_::{DisplayInside, DisplayOutside};
if node.element_data().is_none() {
return true;
}
node.primary_styles().is_none_or(|styles| {
let display = styles.clone_display();
display.outside() == DisplayOutside::Inline && display.inside() == DisplayInside::Flow
})
}
fn write(node: &blitz_dom::Node, document: &blitz_dom::BaseDocument, out: &mut String) {
if let Some(element) = node.element_data()
&& matches!(
element.name.local.as_ref(),
"style" | "script" | "template" | "noscript"
)
{
return;
}
if let blitz_dom::node::NodeData::Text(text) = &node.data {
out.push_str(&text.content);
}
for child in &node.children {
let Some(child) = document.get_node(*child) else {
continue;
};
if child.element_data().is_some() && !node_is_individually_visible(child) {
continue;
}
let separate = !is_inline(child);
if separate {
out.push(' ');
}
write(child, document, out);
if separate {
out.push(' ');
}
}
}
let mut out = String::new();
write(node, document, &mut out);
out
}
pub(crate) fn names_from_contents(role: &str) -> bool {
matches!(
role,
"button"
| "link"
| "heading"
| "option"
| "alert"
| "status"
| "tooltip"
| "menuitem"
| "menuitemcheckbox"
| "menuitemradio"
| "tab"
| "treeitem"
| "cell"
| "gridcell"
| "columnheader"
| "rowheader"
| "row"
)
}
pub(crate) fn semantic_name(
element: &blitz_dom::ElementData,
node: &blitz_dom::Node,
role: &str,
document: &blitz_dom::BaseDocument,
id: blitz_dom::NodeId,
labels: &LabelIndex,
) -> String {
let name = labels
.labelled_by(document, element)
.map(std::borrow::Cow::Owned)
.or_else(|| element_attr(element, "aria-label").map(std::borrow::Cow::Borrowed))
.or_else(|| {
labels
.name_for(document, id, element)
.map(std::borrow::Cow::Owned)
})
.or_else(|| element_attr(element, "alt").map(std::borrow::Cow::Borrowed))
.or_else(|| element_attr(element, "title").map(std::borrow::Cow::Borrowed))
.or_else(|| {
(role == "option")
.then(|| element_attr(element, "label"))
.flatten()
.map(std::borrow::Cow::Borrowed)
})
.or_else(|| {
names_from_contents(role)
.then(|| name_text(node, document))
.filter(|text| !text.trim().is_empty())
.map(std::borrow::Cow::Owned)
})
.or_else(|| {
(role == "option")
.then(|| element_attr(element, "value"))
.flatten()
.map(std::borrow::Cow::Borrowed)
})
.or_else(|| {
matches!(role, "textbox" | "combobox")
.then(|| element_attr(element, "placeholder").map(std::borrow::Cow::Borrowed))
.flatten()
})
.unwrap_or_default();
normalize_text(&name)
}
pub(crate) fn normalize_text(text: &str) -> String {
let mut normalized = String::with_capacity(text.len().min(512));
let mut characters = 0;
for word in text.split_whitespace() {
if !normalized.is_empty() && characters < 512 {
normalized.push(' ');
characters += 1;
}
for character in word.chars() {
if characters == 512 {
return normalized;
}
normalized.push(character);
characters += 1;
}
}
normalized
}
pub(crate) fn exposed_text(
document: &blitz_dom::BaseDocument,
id: blitz_dom::NodeId,
node: &blitz_dom::Node,
) -> Option<String> {
let blitz_dom::node::NodeData::Text(text) = &node.data else {
return None;
};
let normalized = normalize_text(&text.content);
if normalized.is_empty() {
return None;
}
let mut current = document.get_node(id)?.parent;
for _ in 0..64 {
let Some(ancestor) = current else {
break;
};
let ancestor_node = document.get_node(ancestor)?;
if let Some(element) = ancestor_node.element_data() {
if matches!(
element.name.local.as_ref(),
"style" | "script" | "template" | "noscript" | "title"
) {
return None;
}
if names_from_contents(semantic_role_ref(element)) {
return None;
}
}
current = ancestor_node.parent;
}
Some(normalized)
}
fn semantic_value(
element: &blitz_dom::ElementData,
document: &blitz_dom::BaseDocument,
id: blitz_dom::NodeId,
) -> Option<String> {
if element.name.local.as_ref() == "select" {
return Some(document.select_value(id));
}
element
.text_input_data()
.map(|input| input.editor.text().to_string())
.or_else(|| {
element
.checkbox_input_checked()
.map(|checked| checked.to_string())
})
.or_else(|| element_attr(element, "aria-valuetext").map(str::to_string))
.or_else(|| element_attr(element, "aria-valuenow").map(str::to_string))
.or_else(|| element_attr(element, "value").map(str::to_string))
}
pub(crate) fn semantic_selected(
element: &blitz_dom::ElementData,
document: &blitz_dom::BaseDocument,
id: blitz_dom::NodeId,
) -> bool {
if element.name.local.as_ref() == "option" {
return document.option_is_selected(id);
}
if let Some(checked) = element.checkbox_input_checked() {
return checked;
}
let attribute_on = |name| match element_attr(element, name) {
Some("false") => false,
Some(_) => true,
None => false,
};
element_attr(element, "aria-selected") == Some("true")
|| element_attr(element, "aria-pressed") == Some("true")
|| element_attr(element, "aria-checked") == Some("true")
|| element_attr(element, "aria-current").is_some_and(|value| value != "false")
|| attribute_on("checked")
|| attribute_on("selected")
}
fn semantic_parent(
document: &blitz_dom::BaseDocument,
node_id: blitz_dom::NodeId,
root: Option<blitz_dom::NodeId>,
) -> Option<blitz_dom::NodeId> {
if Some(node_id) == root {
return None;
}
let mut current = document.get_node(node_id)?.parent;
while let Some(id) = current {
let node = document.get_node(id)?;
if node.element_data().is_some() {
return Some(id);
}
current = node.parent;
}
None
}
pub(crate) fn node_is_visible(
document: &blitz_dom::BaseDocument,
node_id: blitz_dom::NodeId,
) -> bool {
let mut current = Some(node_id);
while let Some(id) = current {
let Some(node) = document.get_node(id) else {
return false;
};
if !node_is_individually_visible(node) {
return false;
}
current = node.parent;
}
true
}
pub(crate) fn dom_chain_is_attached(
document: &blitz_dom::BaseDocument,
node_id: blitz_dom::NodeId,
node_limit: usize,
) -> bool {
let root = document.root_node().id;
let mut current = Some(node_id);
for _ in 0..=node_limit {
let Some(id) = current else {
return false;
};
if id == root {
return true;
}
let Some(node) = document.get_node(id) else {
return false;
};
current = node.parent;
}
false
}
pub(crate) fn layout_chain_is_valid(
document: &blitz_dom::BaseDocument,
node_id: blitz_dom::NodeId,
node_limit: usize,
) -> bool {
let mut current = Some(node_id);
for _ in 0..=node_limit {
let Some(id) = current else {
return true;
};
let Some(node) = document.get_node(id) else {
return false;
};
current = node.layout_parent.get();
}
false
}
pub(crate) fn viewport_fixed_descendant(
document: &blitz_dom::BaseDocument,
node_id: blitz_dom::NodeId,
node_limit: usize,
) -> bool {
use style::properties::generated::longhands::position::computed_value::T as Position;
let root_element = document.root_element().id;
let mut current = Some(node_id);
for _ in 0..=node_limit {
let Some(id) = current else { return false };
let Some(node) = document.get_node(id) else {
return false;
};
if node
.primary_styles()
.is_some_and(|styles| styles.clone_position() == Position::Fixed)
&& node.layout_parent.get() == Some(root_element)
{
return true;
}
current = node.layout_parent.get();
}
false
}
pub fn hover_agent_node(
document: &mut ScriptDocument,
node_id: u64,
) -> Result<(f32, f32), DebugError> {
let (node_id, position) = resolve_agent_node(document, node_id)?;
document.handle_pointer_move_to_node(
pointer_event_for_document(
document,
position,
MouseEventButton::Main,
MouseEventButtons::default(),
KeyboardModifiers::empty(),
),
node_id,
);
Ok(position)
}
pub fn press_agent_key(
document: &mut ScriptDocument,
key: &str,
code: &str,
) -> Result<(), DebugError> {
let parsed_key = key
.parse::<Key>()
.unwrap_or_else(|_| Key::Character(key.to_owned()));
let parsed_code = code.parse::<Code>().unwrap_or(Code::Unidentified);
for phase in [KeyPhase::Down, KeyPhase::Up] {
let event = key_event(
phase,
parsed_key.clone(),
parsed_code,
keyboard_modifiers(Default::default()),
);
document.handle_ui_event(match phase {
KeyPhase::Down => UiEvent::KeyDown(event),
KeyPhase::Up => UiEvent::KeyUp(event),
});
}
Ok(())
}
pub fn click_agent_node(
document: &mut ScriptDocument,
node_id: u64,
count: u8,
) -> Result<(f32, f32), DebugError> {
activate_agent_node(document, node_id, count)
}
pub fn focus_agent_node(
document: &mut ScriptDocument,
node_id: blitz_dom::NodeId,
) -> Result<(), DebugError> {
let focusable = document
.inner()
.get_node(node_id)
.and_then(|node| node.element_data())
.is_some_and(focuses_on_click);
if !focusable {
return Err(debug_error(
"notFocusable",
"node does not accept keyboard focus",
));
}
document.inner_mut().set_focus_to(node_id);
Ok(())
}
pub fn inspect_document(
document: &mut ScriptDocument,
root: Option<u64>,
max_depth: u32,
revision: u64,
) -> DebugResponse {
let ran_script = drain_for_observer(document).0 > 0;
if ran_script {
document.inner_mut().resolve(0.0);
}
let inner = document.inner();
let root = root.map(blitz_dom::NodeId::from_u64);
if root.is_some_and(|id| inner.get_node(id).is_none()) {
return control_error("unknownNode", "the requested root node does not exist");
}
let focused_node = inner.get_focussed_node_id().map(|id| id.as_u64());
let viewport = inner.viewport();
let viewport_scale = viewport.scale_f64();
let viewport_bounds = Some([
0.0,
0.0,
viewport.window_size.0 as f64 / viewport_scale,
viewport.window_size.1 as f64 / viewport_scale,
]);
let labels = LabelIndex::build(&inner);
let node_limit = inner.tree().iter().count();
let candidates = if let Some(root) = root {
semantic_subtree_ids(&inner, root, max_depth)
.into_iter()
.filter_map(|id| {
inner.get_node(id)?;
dom_chain_is_attached(&inner, id, node_limit).then(|| SemanticCandidate {
id,
parent: semantic_parent(&inner, id, Some(root)),
visible: node_is_visible(&inner, id),
})
})
.collect()
} else {
attached_semantic_candidates(&inner, max_depth)
};
let layout_validity = layout_chain_validities(&inner, &candidates, node_limit);
let nodes = candidates
.into_iter()
.filter_map(|candidate| {
let id = candidate.id;
let node = inner.get_node(id)?;
if layout_validity.get(&id) != Some(&true) {
return None;
}
let rect = inner.get_client_bounding_rect(id);
let bounds = rect.and_then(|rect| {
let bounds = [rect.x, rect.y, rect.width, rect.height];
bounds
.iter()
.all(|value| value.is_finite())
.then_some(bounds)
});
let Some(element) = node.element_data() else {
let text = exposed_text(&inner, id, node)?;
return Some(SemanticNode {
dom_id: None,
id: id.as_u64(),
parent: candidate.parent.map(|id| id.as_u64()),
role: "text".to_owned(),
name: text,
value: None,
enabled: true,
focusable: false,
viewport_fixed: false,
visible: candidate.visible,
selected: false,
bounds,
slot: None,
attributes: BTreeMap::new(),
});
};
let visible = candidate.visible
&& rect
.as_ref()
.is_some_and(|rect| rect.width > 0.0 && rect.height > 0.0);
let role = semantic_role(element);
let name = semantic_name(element, node, &role, &inner, id, &labels);
if role == "generic"
&& name.is_empty()
&& element_attr(element, "id").is_none()
&& element.name.ns.as_ref() == "http://www.w3.org/2000/svg"
&& matches!(
element.name.local.as_ref(),
"path"
| "line"
| "polyline"
| "polygon"
| "rect"
| "circle"
| "ellipse"
| "use"
)
{
return None;
}
let value = semantic_value(element, &inner, id);
Some(SemanticNode {
dom_id: element_attr(element, "id").map(str::to_owned),
id: id.as_u64(),
parent: candidate.parent.map(|id| id.as_u64()),
role,
name,
value,
enabled: element_attr(element, "disabled").is_none()
&& element_attr(element, "aria-disabled") != Some("true"),
focusable: focuses_on_click(element),
viewport_fixed: viewport_fixed_descendant(&inner, id, node_limit),
visible,
selected: semantic_selected(element, &inner, id),
bounds,
slot: element_attr(element, "data-slot").map(str::to_owned),
attributes: semantic_target_attributes(element),
})
})
.collect();
DebugResponse::AgentSnapshot(AgentSnapshot {
revision,
active_window: Some("blitz-main".into()),
focused_node,
viewport: viewport_bounds,
nodes,
})
}
#[cfg(feature = "capture")]
pub(crate) fn timing_stats(stats: blitz_shell::TimingStats) -> TimingStats {
TimingStats {
mean_ms: stats.mean_ms,
p95_ms: stats.p95_ms,
max_ms: stats.max_ms,
}
}
pub(crate) fn debug_error(code: &str, message: &str) -> DebugError {
DebugError {
code: code.into(),
message: message.into(),
}
}
pub(crate) fn focuses_on_click(element: &blitz_dom::ElementData) -> bool {
let tag = element.name.local.as_ref();
matches!(tag, "button" | "input" | "select" | "textarea")
|| tag == "a" && element_attr(element, "href").is_some()
|| element_attr(element, "tabindex")
.and_then(|value| value.parse::<i32>().ok())
.is_some_and(|value| value >= 0)
|| element_attr(element, "contenteditable").is_some_and(|value| value != "false")
}
#[cfg(feature = "capture")]
pub(crate) fn resident_bytes() -> Option<u64> {
let output = std::process::Command::new("ps")
.args(["-o", "rss=", "-p", &std::process::id().to_string()])
.output()
.ok()?;
if !output.status.success() {
return None;
}
std::str::from_utf8(&output.stdout)
.ok()?
.trim()
.parse::<u64>()
.ok()
.and_then(|kilobytes| kilobytes.checked_mul(1_024))
}
pub(crate) fn node_is_individually_visible(node: &blitz_dom::Node) -> bool {
if !node.flags.is_in_document() || node.is_display_none() {
return false;
}
if node.primary_styles().is_some_and(|style| {
use style::computed_values::visibility::T as Visibility;
matches!(
style.clone_visibility(),
Visibility::Hidden | Visibility::Collapse
)
}) {
return false;
}
!node.element_data().is_some_and(|element| {
element_attr(element, "hidden").is_some()
|| element_attr(element, "aria-hidden") == Some("true")
})
}
pub(crate) fn resolve_agent_node(
document: &mut ScriptDocument,
raw_node_id: u64,
) -> Result<(blitz_dom::NodeId, (f32, f32)), DebugError> {
resolve_agent_node_inner(document, raw_node_id, Area::Required)
}
#[derive(Clone, Copy, PartialEq, Eq)]
pub(crate) enum Area {
Required,
Optional,
}
pub(crate) fn resolve_agent_node_inner(
document: &mut ScriptDocument,
raw_node_id: u64,
area: Area,
) -> Result<(blitz_dom::NodeId, (f32, f32)), DebugError> {
let node_id = blitz_dom::NodeId::from_u64(raw_node_id);
document.inner_mut().resolve(0.0);
let inner = document.inner();
let node = inner
.get_node(node_id)
.ok_or_else(|| debug_error("unknownNode", "node does not exist"))?;
if !node_is_visible(&inner, node_id) {
return Err(debug_error("notInteractable", "node is not visible"));
}
let node_limit = inner.tree().iter().count();
if !dom_chain_is_attached(&inner, node_id, node_limit)
|| !layout_chain_is_valid(&inner, node_id, node_limit)
{
return Err(debug_error(
"notInteractable",
"node has a detached layout ancestor",
));
}
if node
.element_data()
.is_some_and(|element| element_attr(element, "disabled").is_some())
{
return Err(debug_error("notInteractable", "node is disabled"));
}
let rect = inner
.get_client_bounding_rect(node_id)
.filter(|rect| area == Area::Optional || (rect.width > 0.0 && rect.height > 0.0))
.ok_or_else(|| {
debug_error(
"notInteractable",
match area {
Area::Optional => "node has no layout box",
Area::Required => "node has no layout box a pointer can reach",
},
)
})?;
Ok((
node_id,
(
(rect.x + rect.width / 2.0) as f32,
(rect.y + rect.height / 2.0) as f32,
),
))
}
pub(crate) fn pointer_event(
position: (f32, f32),
button: MouseEventButton,
buttons: MouseEventButtons,
modifiers: KeyboardModifiers,
) -> BlitzPointerEvent {
BlitzPointerEvent {
id: BlitzPointerId::Mouse,
is_primary: true,
coords: pointer_coords(position),
button,
buttons,
mods: modifiers,
details: PointerDetails::default(),
element: Point::default(),
active_pointers: Default::default(),
}
}
pub(crate) fn pointer_event_for_document(
document: &ScriptDocument,
position: (f32, f32),
button: MouseEventButton,
buttons: MouseEventButtons,
modifiers: KeyboardModifiers,
) -> BlitzPointerEvent {
let mut event = pointer_event(position, button, buttons, modifiers);
let scroll = document.inner().viewport_scroll();
event.coords.page_x += scroll.x as f32;
event.coords.page_y += scroll.y as f32;
event
}
pub(crate) fn pointer_coords_for_document(
document: &ScriptDocument,
position: (f32, f32),
) -> PointerCoords {
let mut coords = pointer_coords(position);
let scroll = document.inner().viewport_scroll();
coords.page_x += scroll.x as f32;
coords.page_y += scroll.y as f32;
coords
}
pub(crate) struct SemanticCandidate {
pub(crate) id: blitz_dom::NodeId,
pub(crate) parent: Option<blitz_dom::NodeId>,
pub(crate) visible: bool,
}
#[derive(Clone, Copy)]
enum LayoutChainState {
Visiting,
Valid,
Invalid,
}
pub(crate) fn layout_chain_validities(
document: &blitz_dom::BaseDocument,
candidates: &[SemanticCandidate],
node_limit: usize,
) -> HashMap<blitz_dom::NodeId, bool> {
let mut states = HashMap::with_capacity(candidates.len());
for candidate in candidates {
if matches!(
states.get(&candidate.id),
Some(LayoutChainState::Valid | LayoutChainState::Invalid)
) {
continue;
}
let mut chain = Vec::new();
let mut current = Some(candidate.id);
let valid = loop {
let Some(id) = current else {
break true;
};
match states.get(&id) {
Some(LayoutChainState::Valid) => break true,
Some(LayoutChainState::Invalid | LayoutChainState::Visiting) => break false,
None => {}
}
if chain.len() > node_limit {
break false;
}
let Some(node) = document.get_node(id) else {
break false;
};
states.insert(id, LayoutChainState::Visiting);
chain.push(id);
current = node.layout_parent.get();
};
let resolved = if valid {
LayoutChainState::Valid
} else {
LayoutChainState::Invalid
};
for id in chain {
states.insert(id, resolved);
}
}
states
.into_iter()
.filter_map(|(id, state)| match state {
LayoutChainState::Valid => Some((id, true)),
LayoutChainState::Invalid => Some((id, false)),
LayoutChainState::Visiting => None,
})
.collect()
}
pub(crate) fn semantic_subtree_ids(
document: &blitz_dom::BaseDocument,
root: blitz_dom::NodeId,
max_depth: u32,
) -> Vec<blitz_dom::NodeId> {
let mut out = Vec::new();
let mut stack = vec![(root, 0_u32)];
while let Some((node_id, depth)) = stack.pop() {
let Some(node) = document.get_node(node_id) else {
continue;
};
if node.element_data().is_some() || node.is_text_node() {
out.push(node_id);
}
for &child_id in node.children.iter().rev() {
let child_depth = depth.saturating_add(
document
.get_node(child_id)
.is_some_and(|child| child.element_data().is_some()) as u32,
);
if max_depth == 0 || child_depth <= max_depth {
stack.push((child_id, child_depth));
}
}
}
out
}
pub(crate) fn pointer_coords((x, y): (f32, f32)) -> PointerCoords {
PointerCoords {
page_x: x,
page_y: y,
screen_x: x,
screen_y: y,
client_x: x,
client_y: y,
}
}
#[cfg(feature = "capture")]
pub(crate) fn diagnostic_style_row(
document: &blitz_dom::BaseDocument,
node: &SemanticNode,
) -> Option<serde_json::Value> {
let dom_node = document.get_node(NodeId::from_u64(node.id))?;
let styles = dom_node.primary_styles()?;
let current = styles.clone_color();
let hex = |absolute: style::color::AbsoluteColor| {
let [r, g, b, a] = *absolute
.to_color_space(style::color::ColorSpace::Srgb)
.raw_components();
let channel = |value: f32| (value.clamp(0.0, 1.0) * 255.0).round() as u8;
format!(
"#{:02x}{:02x}{:02x}{:02x}",
channel(r),
channel(g),
channel(b),
channel(a),
)
};
let radius = format!("{:?}", styles.get_border().border_top_left_radius.0.width);
let border = styles.get_border();
let border_width = border.border_top_width.0.to_f64_px();
let font_size = styles.clone_font_size().computed_size().px();
let has_text_content = !dom_node.text_content().trim().is_empty();
Some(serde_json::json!({
"nodeId": node.id,
"color": hex(current),
"backgroundColor": hex(
styles.clone_background_color().resolve_to_absolute(¤t),
),
"borderColor": hex(border.border_top_color.resolve_to_absolute(¤t)),
"borderWidth": format!("{border_width}px"),
"fontSize": format!("{font_size}px"),
"hasTextContent": has_text_content,
"opacity": styles.clone_opacity(),
"borderTopLeftRadius": radius,
"visibility": format!("{:?}", styles.clone_visibility()),
}))
}
pub(crate) fn keyboard_modifiers(modifiers: ControlModifiers) -> KeyboardModifiers {
let mut output = KeyboardModifiers::empty();
output.set(KeyboardModifiers::SHIFT, modifiers.shift);
output.set(KeyboardModifiers::CONTROL, modifiers.control);
output.set(KeyboardModifiers::ALT, modifiers.alt);
output.set(KeyboardModifiers::META, modifiers.meta);
output.set(KeyboardModifiers::SUPER, modifiers.meta);
output
}
pub(crate) fn key_event(
phase: KeyPhase,
key: Key,
code: Code,
modifiers: KeyboardModifiers,
) -> BlitzKeyEvent {
let text = match (&key, phase) {
(Key::Character(value), KeyPhase::Down)
if !modifiers.intersects(
KeyboardModifiers::CONTROL | KeyboardModifiers::ALT | KeyboardModifiers::META,
) =>
{
Some(value.clone().into())
}
_ => None,
};
BlitzKeyEvent {
key,
code,
modifiers,
location: Location::Standard,
is_auto_repeating: false,
is_composing: false,
state: match phase {
KeyPhase::Down => KeyState::Pressed,
KeyPhase::Up => KeyState::Released,
},
text,
}
}
pub(crate) fn attached_semantic_candidates(
document: &blitz_dom::BaseDocument,
max_depth: u32,
) -> Vec<SemanticCandidate> {
let root = document.root_node().id;
let mut candidates = Vec::new();
let mut stack = vec![(root, 0_u32, None, true)];
while let Some((id, depth, semantic_parent, ancestors_visible)) = stack.pop() {
let Some(node) = document.get_node(id) else {
continue;
};
let visible = ancestors_visible && node_is_individually_visible(node);
let is_element = node.element_data().is_some();
if is_element && max_depth != 0 && depth > max_depth {
continue;
}
if is_element || node.is_text_node() {
candidates.push(SemanticCandidate {
id,
parent: semantic_parent,
visible,
});
}
let child_depth = depth.saturating_add(is_element as u32);
let child_parent = if is_element {
Some(id)
} else {
semantic_parent
};
for &child in node.children.iter().rev() {
stack.push((child, child_depth, child_parent, visible));
}
}
candidates
}
pub(crate) fn control_error(code: &str, message: &str) -> DebugResponse {
DebugResponse::Error(debug_error(code, message))
}
#[cfg(feature = "capture")]
pub(crate) fn diagnostic_layout_row(
document: &blitz_dom::BaseDocument,
node: &SemanticNode,
) -> Option<LayoutDiagnosticRow> {
let bounds = node.bounds?;
let dom_node = document.get_node(NodeId::from_u64(node.id))?;
let layout = dom_node.final_layout();
let unzoom = |value: f32| match dom_node.primary_styles() {
Some(styles) => styles.effective_zoom.unzoom(value),
None => value,
};
let scroll_offset = dom_node.scroll_offset();
Some(LayoutDiagnosticRow {
node_id: node.id,
bounds: LayoutBounds::from(bounds),
scroll_offset: LayoutOffset {
x: f64::from(unzoom(scroll_offset.x as f32)),
y: f64::from(unzoom(scroll_offset.y as f32)),
},
client_size: LayoutSize {
width: f64::from(unzoom(layout.size.width)),
height: f64::from(unzoom(layout.size.height)),
},
scroll_size: LayoutSize {
width: f64::from(unzoom(layout.size.width + layout.scroll_width())),
height: f64::from(unzoom(layout.size.height + layout.scroll_height())),
},
scroll_range: LayoutSize {
width: f64::from(unzoom(layout.scroll_width())),
height: f64::from(unzoom(layout.scroll_height())),
},
border: LayoutEdges {
top: f64::from(unzoom(layout.border.top)),
right: f64::from(unzoom(layout.border.right)),
bottom: f64::from(unzoom(layout.border.bottom)),
left: f64::from(unzoom(layout.border.left)),
},
padding: LayoutEdges {
top: f64::from(unzoom(layout.padding.top)),
right: f64::from(unzoom(layout.padding.right)),
bottom: f64::from(unzoom(layout.padding.bottom)),
left: f64::from(unzoom(layout.padding.left)),
},
content_size: LayoutSize {
width: f64::from(unzoom(
layout.size.width
- layout.border.left
- layout.border.right
- layout.padding.left
- layout.padding.right,
)),
height: f64::from(unzoom(
layout.size.height
- layout.border.top
- layout.border.bottom
- layout.padding.top
- layout.padding.bottom,
)),
},
})
}
pub(crate) fn activate_agent_node(
document: &mut ScriptDocument,
raw_node_id: u64,
count: u8,
) -> Result<(f32, f32), DebugError> {
let (node_id, position) = resolve_agent_node_inner(document, raw_node_id, Area::Optional)?;
let focusable = document
.inner()
.get_node(node_id)
.and_then(|node| node.element_data())
.is_some_and(focuses_on_click);
for _ in 0..count {
let movement = pointer_event_for_document(
document,
position,
MouseEventButton::Main,
MouseEventButtons::default(),
KeyboardModifiers::empty(),
);
let down = pointer_event_for_document(
document,
position,
MouseEventButton::Main,
MouseEventButtons::Primary,
KeyboardModifiers::empty(),
);
let up = pointer_event_for_document(
document,
position,
MouseEventButton::Main,
MouseEventButtons::default(),
KeyboardModifiers::empty(),
);
for event in [
UiEvent::PointerMove(movement),
UiEvent::PointerDown(down),
UiEvent::PointerUp(up),
] {
if document.inner().get_node(node_id).is_none() {
break;
}
document.handle_ui_event_to_node(event, node_id);
}
if focusable && document.inner().get_node(node_id).is_some() {
document.inner_mut().set_focus_to(node_id);
}
}
Ok(position)
}
#[cfg(test)]
mod tests {
use super::*;
use blitz_dom::{Document, DocumentConfig};
#[test]
fn meta_also_sets_the_super_modifier() {
let modifiers = keyboard_modifiers(ControlModifiers {
meta: true,
..ControlModifiers::default()
});
assert!(modifiers.contains(KeyboardModifiers::META));
assert!(modifiers.contains(KeyboardModifiers::SUPER));
}
fn document() -> ScriptDocument {
let mut document = ScriptDocument::from_html(
r#"<style>
button { border: 0; padding: 0; margin: 0; font-size: 0; }
#padded { padding: 8px 12px; }
</style>
<button id="flat">Open dialog</button>
<button id="padded">Open dialog</button>"#,
DocumentConfig::default(),
);
document.inner_mut().resolve(0.0);
document
}
fn node_id(document: &ScriptDocument, selector: &str) -> u64 {
document
.inner()
.query_selector(selector)
.unwrap()
.expect("the fixture should contain the selector")
.as_u64()
}
#[test]
fn a_control_with_no_area_is_still_pressable() {
let mut document = document();
let flat = node_id(&document, "#flat");
let rect = document
.inner()
.get_client_bounding_rect(blitz_dom::NodeId::from_u64(flat));
assert!(
rect.is_some_and(|rect| rect.width == 0.0 || rect.height == 0.0),
"the flat button should lay out with no area"
);
activate_agent_node(&mut document, flat, 1)
.expect("a click is dispatched at the node, so it needs no area");
}
#[test]
fn a_control_with_no_area_still_refuses_a_pointer() {
let mut document = document();
let flat = node_id(&document, "#flat");
let error = hover_agent_node(&mut document, flat)
.expect_err("hover needs a box a pointer can land in");
assert!(
error.message.contains("no layout box"),
"unexpected error: {error:?}"
);
}
#[test]
fn a_hidden_control_is_still_refused() {
let mut document = ScriptDocument::from_html(
r#"<button id="gone" style="display: none">Open dialog</button>"#,
DocumentConfig::default(),
);
document.inner_mut().resolve(0.0);
let gone = node_id(&document, "#gone");
let error = activate_agent_node(&mut document, gone, 1)
.expect_err("a display:none control must stay unpressable");
assert!(
error.message.contains("not visible"),
"unexpected error: {error:?}"
);
}
#[test]
fn pointer_coordinates_keep_client_and_page_space_distinct_after_scroll() {
let mut document = document();
document
.inner_mut()
.set_viewport_scroll(blitz_dom::Point { x: 17.0, y: 600.0 });
let coords = pointer_coords_for_document(&document, (24.0, 32.0));
assert_eq!((coords.client_x, coords.client_y), (24.0, 32.0));
assert_eq!((coords.page_x, coords.page_y), (41.0, 632.0));
}
}
#[cfg(test)]
mod semantic_tests {
use super::*;
use blitz_dom::DocumentConfig;
const REPRO: &str = r#"<table aria-label="named table">
<thead><tr><th scope="col">Crate</th></tr></thead>
<tbody><tr><td>worktable</td></tr></tbody>
</table>
<section aria-label="a named section"><p>text</p></section>
<datalist id="t"><option value="u64"></option></datalist>
<pre>plain text in a pre</pre>
<div role="tooltip">tooltip text</div>"#;
fn tree(html: &str) -> Vec<SemanticNode> {
let mut document = ScriptDocument::from_html(html, DocumentConfig::default());
document.inner_mut().resolve(0.0);
match inspect_document(&mut document, None, 0, 1) {
DebugResponse::AgentSnapshot(snapshot) => snapshot.nodes,
other => panic!("inspection did not answer with a tree: {other:?}"),
}
}
fn roles<'a>(nodes: &'a [SemanticNode], role: &str) -> Vec<&'a SemanticNode> {
nodes.iter().filter(|node| node.role == role).collect()
}
fn names(nodes: &[SemanticNode], role: &str) -> Vec<String> {
roles(nodes, role)
.into_iter()
.map(|node| node.name.clone())
.collect()
}
#[test]
fn a_header_cell_is_a_header() {
let nodes = tree(REPRO);
assert_eq!(
roles(&nodes, "columnheader").len(),
1,
"a `<th scope=\"col\">` is a column header, not an ordinary cell"
);
assert_eq!(roles(&nodes, "cell").len(), 1, "only the `<td>` is a cell");
}
#[test]
fn a_cell_is_named_by_what_it_holds() {
let nodes = tree(REPRO);
assert_eq!(
names(&nodes, "cell"),
vec!["worktable".to_string()],
"a data cell's text is its accessible name, so a table of values is readable"
);
assert_eq!(
names(&nodes, "columnheader"),
vec!["Crate".to_string()],
"a header cell is named by its content too"
);
}
#[test]
fn a_row_is_named_by_its_cells() {
let nodes = tree(REPRO);
assert_eq!(
names(&nodes, "row"),
vec!["Crate".to_string(), "worktable".to_string()],
"a row is named from its contents, which is what makes a table row addressable"
);
}
#[test]
fn a_row_scoped_header_is_a_row_header() {
let nodes = tree(r#"<table><tr><th scope="row">Crate</th><td>worktable</td></tr></table>"#);
assert_eq!(
roles(&nodes, "rowheader").len(),
1,
"`scope=\"row\"` makes a header describe its row, which is what blitz-dom reports"
);
}
#[test]
fn a_named_section_is_a_region() {
let nodes = tree(REPRO);
assert_eq!(
names(&nodes, "region"),
vec!["a named section".to_string()],
"a `<section>` with an accessible name is a landmark, not a wrapper"
);
}
#[test]
fn text_the_page_shows_is_in_the_tree() {
let nodes = tree(REPRO);
assert!(
names(&nodes, "text").contains(&"plain text in a pre".to_string()),
"a `<pre>`'s text is not any element's name, so without a text node it is unreadable: \
{:?}",
names(&nodes, "text")
);
}
#[test]
fn fixed_boxes_are_identified_as_viewport_anchored() {
let nodes = tree(
"<main style='height:1600px'><button id='flow'>Flow</button>\
<section style='position:fixed;top:16px;left:16px'>\
<button id='fixed'>Fixed</button>\
</section></main>",
);
let flow = nodes
.iter()
.find(|node| node.dom_id.as_deref() == Some("flow"))
.expect("flow button is inspected");
let fixed = nodes
.iter()
.find(|node| node.dom_id.as_deref() == Some("fixed"))
.expect("fixed button is inspected");
assert!(!flow.viewport_fixed);
assert!(fixed.viewport_fixed);
}
#[test]
fn a_text_run_refuses_a_click_rather_than_panicking() {
let mut document =
ScriptDocument::from_html("<pre>plain text in a pre</pre>", DocumentConfig::default());
document.inner_mut().resolve(0.0);
let DebugResponse::AgentSnapshot(snapshot) = inspect_document(&mut document, None, 0, 1)
else {
panic!("inspection did not answer with a tree");
};
let text = snapshot
.nodes
.iter()
.find(|node| node.role == "text")
.expect("the pre's text is in the tree");
let error = activate_agent_node(&mut document, text.id, 1)
.expect_err("a text run has no box to press");
assert_eq!(error.code, "notInteractable", "unexpected error: {error:?}");
}
#[test]
fn text_that_already_names_a_node_is_not_repeated() {
let nodes = tree(REPRO);
let text = names(&nodes, "text");
assert!(
!text.contains(&"worktable".to_string()),
"the cell carries this text as its name, and the cell is the node a harness can act \
on: {text:?}"
);
let nodes = tree(r#"<button><span>Save</span></button>"#);
assert!(
names(&nodes, "text").is_empty(),
"a wrapper between a control and its text does not make the text a second node"
);
}
#[test]
fn a_stylesheet_is_not_text() {
let nodes = tree("<style>.a { color: red }</style><p>shown</p>");
assert_eq!(
names(&nodes, "text"),
vec!["shown".to_string()],
"a `<style>` is not rendered, and reading it out returns a stylesheet"
);
}
const RESPONSIVE_LABEL: &str = r#"<button>
<span>Book</span>
<span style="display: none">Book a diagnostic</span>
</button>"#;
#[test]
fn a_name_skips_a_subtree_that_is_not_rendered() {
let nodes = tree(RESPONSIVE_LABEL);
assert_eq!(
names(&nodes, "button"),
vec!["Book".to_string()],
"a display:none subtree contributes nothing to a name"
);
}
#[test]
fn a_name_skips_a_subtree_that_is_hidden_or_aria_hidden() {
let nodes = tree(
r#"<button>Save<span style="visibility: hidden">draft</span><span aria-hidden="true">now</span></button>"#,
);
assert_eq!(
names(&nodes, "button"),
vec!["Save".to_string()],
"an invisible box and an aria-hidden one are both outside the name"
);
}
#[test]
fn a_label_skips_what_it_does_not_show() {
let nodes = tree(
r#"<label for="url">Endpoint<span style="display: none"> (advanced)</span></label>
<input id="url" type="text">"#,
);
assert_eq!(
names(&nodes, "textbox"),
vec!["Endpoint".to_string()],
"the label a control is named by is read the same way a name is"
);
}
#[test]
fn a_value_only_option_is_named_by_its_value() {
let nodes = tree(REPRO);
assert_eq!(
names(&nodes, "option"),
vec!["u64".to_string()],
"a `<datalist>` option carries its text in `value`, which is what a browser announces"
);
}
#[test]
fn an_options_label_attribute_wins_over_its_text() {
let nodes = tree(r#"<select><option label="Sixty four bits">u64</option></select>"#);
assert_eq!(
names(&nodes, "option"),
vec!["Sixty four bits".to_string()],
"HTML gives `label` precedence over an option's own text"
);
}
#[test]
fn a_tooltip_says_what_it_says() {
let nodes = tree(REPRO);
assert_eq!(
names(&nodes, "tooltip"),
vec!["tooltip text".to_string()],
"a tooltip is named by its contents, and its contents are the whole point of it"
);
}
#[test]
fn an_unnamed_section_is_not_a_region() {
let nodes = tree("<section><p>text</p></section>");
assert!(
roles(&nodes, "region").is_empty(),
"HTML-AAM gives an unnamed section no landmark role, so a page of \
plain sections does not grow a landmark per wrapper"
);
}
#[test]
fn a_region_is_named_by_the_heading_it_points_at() {
let nodes = tree(
r#"<h2 id="title">Fleet health</h2>
<section aria-labelledby="title"><p>text</p></section>"#,
);
assert_eq!(
names(&nodes, "region"),
vec!["Fleet health".to_string()],
"a section named by reference is a named landmark, not an anonymous one"
);
}
#[test]
fn a_list_of_references_is_joined_in_the_order_it_is_written() {
let nodes = tree(
r#"<span id="unit">per second</span><span id="what">Requests</span>
<button aria-labelledby="what unit">?</button>"#,
);
assert_eq!(
names(&nodes, "button"),
vec!["Requests per second".to_string()],
"the ids are read in the order the author listed them, not in document order, \
and their text is joined by a single space"
);
}
#[test]
fn a_reference_outranks_an_aria_label_and_the_contents() {
let nodes = tree(
r#"<span id="title">Fleet health</span>
<button aria-labelledby="title" aria-label="overridden">Save</button>"#,
);
assert_eq!(
names(&nodes, "button"),
vec!["Fleet health".to_string()],
"ARIA ranks `aria-labelledby` above `aria-label`, which is above name from contents"
);
}
#[test]
fn a_referenced_element_names_even_when_it_is_not_rendered() {
let nodes = tree(
r#"<span id="title" style="display: none">Fleet <b>health</b></span>
<section aria-labelledby="title"><p>text</p></section>"#,
);
assert_eq!(
names(&nodes, "region"),
vec!["Fleet health".to_string()],
"a referenced element contributes its whole text even when it is hidden"
);
}
#[test]
fn a_reference_still_skips_what_is_hidden_inside_it() {
let nodes = tree(
r#"<span id="title">Book<span style="display: none"> a diagnostic</span></span>
<button aria-labelledby="title">?</button>"#,
);
assert_eq!(
names(&nodes, "button"),
vec!["Book".to_string()],
"the hidden half of a responsive label stays out of a name reached by reference too"
);
}
#[test]
fn a_reference_to_nothing_falls_through_to_the_next_rule() {
let nodes = tree(r#"<button aria-labelledby="deleted" aria-label="Save">?</button>"#);
assert_eq!(
names(&nodes, "button"),
vec!["Save".to_string()],
"an id that matches no element is not a name, so the rules below it stay reachable"
);
let nodes = tree(r#"<button aria-labelledby="deleted">Save</button>"#);
assert_eq!(
names(&nodes, "button"),
vec!["Save".to_string()],
"with nothing else declared the control is still named by its own contents"
);
}
#[test]
fn a_reference_that_resolves_to_no_text_falls_through_too() {
let nodes = tree(
r#"<span id="title"></span>
<button aria-labelledby="title">Save</button>"#,
);
assert_eq!(
names(&nodes, "button"),
vec!["Save".to_string()],
"an element that exists and says nothing gives no name, which is not the same as \
giving an empty one"
);
}
#[test]
fn an_element_that_references_itself_is_named_by_its_own_contents() {
let nodes = tree(
r#"<h2 id="self" aria-labelledby="self" aria-label="overridden">Fleet health</h2>"#,
);
assert_eq!(
names(&nodes, "heading"),
vec!["Fleet health".to_string()],
"a reference is read as text and never as another name computation"
);
}
}
#[cfg(test)]
mod role_projection_tests {
use super::*;
use blitz_dom::DocumentConfig;
fn role(html: &str) -> String {
let mut document = ScriptDocument::from_html(html, DocumentConfig::default());
document.inner_mut().resolve(0.0);
let id = document
.inner()
.query_selector("#it")
.unwrap()
.expect("the fixture should carry #it");
let inner = document.inner();
let element = inner
.get_node(id)
.and_then(|node| node.element_data())
.expect("#it should be an element");
semantic_role(element)
}
#[test]
fn the_reported_roles_are_the_ones_this_surface_has_always_reported() {
for (html, expected) in [
(r#"<a id="it" href="/x">x</a>"#, "link"),
(r#"<button id="it">x</button>"#, "button"),
(r#"<textarea id="it"></textarea>"#, "textbox"),
(r#"<input id="it">"#, "textbox"),
(r#"<select id="it"><option>a</option></select>"#, "combobox"),
(
r#"<select id="it" multiple><option>a</option></select>"#,
"combobox",
),
(r#"<option id="it">a</option>"#, "option"),
(r#"<img id="it" alt="x">"#, "img"),
(r#"<nav id="it">x</nav>"#, "navigation"),
(r#"<main id="it">x</main>"#, "main"),
(
r#"<section id="it" aria-label="named">x</section>"#,
"region",
),
(r#"<form id="it">x</form>"#, "form"),
(r#"<ul id="it"><li>a</li></ul>"#, "list"),
(r#"<ol id="it"><li>a</li></ol>"#, "list"),
(r#"<ul><li id="it">a</li></ul>"#, "listitem"),
(r#"<table id="it"><tr><td>a</td></tr></table>"#, "table"),
(r#"<table><tr id="it"><td>a</td></tr></table>"#, "row"),
(r#"<table><tr><td id="it">a</td></tr></table>"#, "cell"),
(
r#"<table><tr><th id="it">a</th></tr></table>"#,
"columnheader",
),
(
r#"<table><tr><th id="it" scope="row">a</th></tr></table>"#,
"rowheader",
),
(r#"<h2 id="it">x</h2>"#, "heading"),
(r#"<input id="it" type="checkbox">"#, "checkbox"),
(r#"<input id="it" type="radio">"#, "radio"),
(r#"<input id="it" type="submit">"#, "button"),
(r#"<input id="it" type="range">"#, "slider"),
(r#"<div id="it">x</div>"#, "generic"),
] {
assert_eq!(role(html), expected, "for {html}");
}
}
#[test]
fn elements_with_a_richer_accesskit_role_still_arrive_generic() {
for html in [
r#"<p id="it">x</p>"#,
r#"<article id="it">x</article>"#,
r#"<aside id="it">x</aside>"#,
r#"<header id="it">x</header>"#,
r#"<footer id="it">x</footer>"#,
r#"<section id="it">x</section>"#,
r#"<blockquote id="it">x</blockquote>"#,
r#"<figure id="it">x</figure>"#,
r#"<hr id="it">"#,
r#"<dl id="it"><dt>a</dt><dd>b</dd></dl>"#,
r#"<dialog id="it">x</dialog>"#,
r#"<fieldset id="it">x</fieldset>"#,
r#"<label id="it">x</label>"#,
r#"<table><thead id="it"><tr><td>a</td></tr></thead></table>"#,
r#"<code id="it">x</code>"#,
r#"<em id="it">x</em>"#,
r#"<strong id="it">x</strong>"#,
r#"<time id="it">x</time>"#,
r#"<iframe id="it"></iframe>"#,
r#"<progress id="it"></progress>"#,
r#"<meter id="it"></meter>"#,
r#"<output id="it"></output>"#,
r#"<details><summary id="it">x</summary>y</details>"#,
r#"<a id="it">no href</a>"#,
r#"<input id="it" type="password">"#,
r#"<input id="it" type="email">"#,
r#"<input id="it" type="color">"#,
r#"<input id="it" type="date">"#,
r#"<input id="it" type="search">"#,
] {
let reported = role(html);
let expected = if html.contains("type=\"password\"")
|| html.contains("type=\"email\"")
|| html.contains("type=\"color\"")
|| html.contains("type=\"date\"")
|| html.contains("type=\"search\"")
{
"textbox"
} else {
"generic"
};
assert_eq!(reported, expected, "for {html}");
}
}
#[test]
fn an_explicit_role_is_reported_as_written() {
assert_eq!(role(r#"<div id="it" role="switch">x</div>"#), "switch");
assert_eq!(role(r#"<div id="it" role="tooltip">x</div>"#), "tooltip");
assert_eq!(
role(r#"<button id="it" role="menuitem">x</button>"#),
"menuitem",
"an author's role overrides the element's own"
);
}
}
#[cfg(test)]
mod runtime_tests {
use super::*;
use crate::SemanticNode;
use crate::document::{
SemanticCandidate, diagnostic_layout_row, diagnostic_style_row, dom_chain_is_attached,
element_attr, layout_chain_is_valid, layout_chain_validities, node_is_visible,
semantic_name, semantic_role, semantic_selected,
};
use blitz_dom::DocumentConfig;
#[test]
fn semantic_visibility_includes_display_none_ancestors() {
let mut document = ScriptDocument::from_html(
"<main><button id='shown'>Run</button><div style='display:none'><button id='hidden'>Hidden</button></div></main>",
DocumentConfig::default(),
);
document.inner_mut().resolve(0.0);
let inner = document.inner();
let node_id = |value: &str| {
inner
.tree()
.iter()
.find_map(|(id, node)| {
node.element_data()
.is_some_and(|element| element_attr(element, "id") == Some(value))
.then_some(id)
})
.unwrap()
};
let shown = node_id("shown");
let hidden = node_id("hidden");
assert!(node_is_visible(&inner, shown));
assert!(!node_is_visible(&inner, hidden));
let shown_node = inner.get_node(shown).unwrap();
let shown_element = shown_node.element_data().unwrap();
assert_eq!(semantic_role(shown_element), "button");
let labels = crate::document::LabelIndex::build(&inner);
assert_eq!(
semantic_name(shown_element, shown_node, "button", &inner, shown, &labels),
"Run"
);
}
#[test]
fn a_style_element_is_not_part_of_a_name() {
let mut document = ScriptDocument::from_html(
"<main>\
<a id='logo' href='/'>\
<svg><style>.logo path { fill: red; }</style></svg>\
Honey\
</a>\
<a id='scripted' href='/x'><script>var noise = 1;</script>Docs</a>\
</main>",
DocumentConfig::default(),
);
document.execute_scripts();
document.inner_mut().resolve(0.0);
let inner = document.inner();
let labels = crate::document::LabelIndex::build(&inner);
let named = |value: &str| {
let id = inner
.tree()
.iter()
.find_map(|(id, node)| {
node.element_data()
.is_some_and(|element| element_attr(element, "id") == Some(value))
.then_some(id)
})
.unwrap();
let node = inner.get_node(id).unwrap();
let element = node.element_data().unwrap();
let role = semantic_role(element);
semantic_name(element, node, &role, &inner, id, &labels)
};
assert_eq!(named("logo"), "Honey", "a stylesheet is not part of a name");
assert_eq!(named("scripted"), "Docs", "and neither is a script");
}
#[test]
fn stacked_lines_are_separated_and_inline_ones_are_not() {
let mut document = ScriptDocument::from_html(
"<main>\
<div id='stacked' role='alert'>\
<div>This page could not load</div>\
<div>WebSocket connection failed</div>\
</div>\
<div id='inline' role='alert'><span>Work</span><span>Tables</span></div>\
<div id='atomic' role='alert'>\
<span style='display: inline-block'>Registry</span>\
<span style='display: inline-block'>unavailable</span>\
</div>\
</main>",
DocumentConfig::default(),
);
document.inner_mut().resolve(0.0);
let inner = document.inner();
let labels = crate::document::LabelIndex::build(&inner);
let named = |value: &str| {
let id = inner
.tree()
.iter()
.find_map(|(id, node)| {
node.element_data()
.is_some_and(|element| element_attr(element, "id") == Some(value))
.then_some(id)
})
.unwrap();
let node = inner.get_node(id).unwrap();
let element = node.element_data().unwrap();
let role = semantic_role(element);
semantic_name(element, node, &role, &inner, id, &labels)
};
assert_eq!(
named("stacked"),
"This page could not load WebSocket connection failed",
"block-level lines are separate words"
);
assert_eq!(
named("inline"),
"WorkTables",
"inline spans are one word, as the page draws them"
);
assert_eq!(
named("atomic"),
"Registry unavailable",
"an inline-block is an atomic inline, and a browser separates it"
);
}
#[test]
fn a_field_is_named_by_its_label() {
let mut document = ScriptDocument::from_html(
"<main>\
<label for='endpoint'>Endpoint URL</label><input id='endpoint'>\
<label>Wrapped<input id='wrapped'></label>\
<label for='overridden'>Ignored</label>\
<input id='overridden' aria-label='Author own name'>\
<input id='placeheld' placeholder='Search everything'>\
<input id='nameless'>\
</main>",
DocumentConfig::default(),
);
document.inner_mut().resolve(0.0);
let inner = document.inner();
let labels = crate::document::LabelIndex::build(&inner);
let named = |value: &str| {
let id = inner
.tree()
.iter()
.find_map(|(id, node)| {
node.element_data()
.is_some_and(|element| element_attr(element, "id") == Some(value))
.then_some(id)
})
.unwrap();
let node = inner.get_node(id).unwrap();
let element = node.element_data().unwrap();
let role = semantic_role(element);
semantic_name(element, node, &role, &inner, id, &labels)
};
assert_eq!(named("endpoint"), "Endpoint URL", "a `for` association");
assert_eq!(named("wrapped"), "Wrapped", "a label wrapped around it");
assert_eq!(
named("overridden"),
"Author own name",
"`aria-label` is the author overriding the visible text, and wins"
);
assert_eq!(
named("placeheld"),
"Search everything",
"a placeholder is the last resort, and names most search fields"
);
assert_eq!(named("nameless"), "", "nothing names it, so it has no name");
}
#[test]
fn a_live_region_is_named_by_what_it_says() {
let mut document = ScriptDocument::from_html(
"<main>\
<p id='refusal' role='alert'>that is not an address</p>\
<p id='saved' role='status'>Settings saved</p>\
<div id='wrapper'><span>inner text</span></div>\
</main>",
DocumentConfig::default(),
);
document.inner_mut().resolve(0.0);
let inner = document.inner();
let labels = crate::document::LabelIndex::build(&inner);
let named = |value: &str| {
let id = inner
.tree()
.iter()
.find_map(|(id, node)| {
node.element_data()
.is_some_and(|element| element_attr(element, "id") == Some(value))
.then_some(id)
})
.unwrap();
let node = inner.get_node(id).unwrap();
let element = node.element_data().unwrap();
let role = semantic_role(element);
semantic_name(element, node, &role, &inner, id, &labels)
};
assert_eq!(named("refusal"), "that is not an address");
assert_eq!(named("saved"), "Settings saved");
assert_eq!(
named("wrapper"),
"",
"a container named by its subtree would make every selector match everything"
);
}
#[test]
fn rooted_inspection_returns_only_the_requested_dom_subtree() {
let mut document = ScriptDocument::from_html(
"<main><section id='left'><button>Left action</button></section><section id='right'><button>Right action</button></section></main>",
DocumentConfig::default(),
);
document.inner_mut().resolve(0.0);
let root = document
.inner()
.query_selector("#left")
.unwrap()
.unwrap()
.as_u64();
let DebugResponse::AgentSnapshot(snapshot) =
inspect_document(&mut document, Some(root), 40, 7)
else {
panic!("rooted inspection did not return a semantic snapshot");
};
let names: Vec<_> = snapshot
.nodes
.iter()
.map(|node| node.name.as_str())
.collect();
assert!(names.contains(&"Left action"));
assert!(!names.contains(&"Right action"));
assert_eq!(snapshot.revision, 7);
}
#[test]
fn semantic_geometry_rejects_a_detached_layout_ancestor() {
let mut document = ScriptDocument::from_html(
"<main><button id='target'>Run</button></main>",
DocumentConfig::default(),
);
document.inner_mut().resolve(0.0);
let inner = document.inner();
let target = inner.query_selector("#target").unwrap().unwrap();
let node_limit = inner.tree().iter().count();
assert!(layout_chain_is_valid(&inner, target, node_limit));
let candidate = || SemanticCandidate {
id: target,
parent: None,
visible: true,
};
assert_eq!(
layout_chain_validities(&inner, &[candidate()], node_limit).get(&target),
Some(&true)
);
let missing_parent = (1..=1024)
.map(blitz_dom::NodeId::from_u64)
.find(|id| inner.get_node(*id).is_none())
.expect("the fixture must leave at least one node id unused");
inner
.get_node(target)
.unwrap()
.layout_parent
.set(Some(missing_parent));
assert!(!layout_chain_is_valid(&inner, target, node_limit));
assert_eq!(
layout_chain_validities(&inner, &[candidate()], node_limit).get(&target),
Some(&false)
);
}
#[test]
fn semantic_geometry_rejects_a_retained_dom_subtree() {
let mut document = ScriptDocument::from_html(
"<main><section id='removed'><button id='target'>Run</button></section></main>",
DocumentConfig::default(),
);
let (removed, target) = {
let inner = document.inner();
(
inner.query_selector("#removed").unwrap().unwrap(),
inner.query_selector("#target").unwrap().unwrap(),
)
};
let node_limit = document.inner().tree().iter().count();
assert!(dom_chain_is_attached(&document.inner(), target, node_limit));
blitz_dom::DocumentMutator::new(&mut document.inner_mut()).remove_node(removed);
let inner = document.inner();
assert!(
inner.get_node(target).is_some(),
"the DOM keeps detached nodes alive for JavaScript wrappers"
);
assert!(!dom_chain_is_attached(&inner, target, node_limit));
}
#[test]
fn semantic_selection_includes_native_and_aria_states() {
let document = ScriptDocument::from_html(
r#"
<button id="pressed" aria-pressed="true">Pressed</button>
<div id="checked" role="radio" aria-checked="true">Checked</div>
<div id="selected" role="option" aria-selected="true">Selected</div>
<button id="current-page" aria-current="page">Current page</button>
<input id="native" type="checkbox" checked>
<button id="plain">Plain</button>
<!--
A framework rendering a controlled value writes the value out
rather than omitting the attribute. Solid emits `checked="false"`
for `checked={false}`, and reading presence alone called that
selected: every Switch, Radio and Checkbox in the QA harness
reported `selected: true` before anything was pressed, and could
never change, which read as three components ignoring a click.
-->
<input id="native-unchecked" type="checkbox" checked="false">
<div id="aria-false" role="option" aria-selected="false">Not selected</div>
<button id="current-false" aria-current="false">Not current</button>
<div id="selected-false" role="option" selected="false">Not selected</div>
"#,
DocumentConfig::default(),
);
let inner = document.inner();
let selected = |selector: &str| {
let id = inner.query_selector(selector).unwrap().unwrap();
semantic_selected(
inner.get_node(id).unwrap().element_data().unwrap(),
&inner,
id,
)
};
assert!(selected("#pressed"));
assert!(selected("#checked"));
assert!(selected("#selected"));
assert!(selected("#current-page"));
assert!(selected("#native"));
assert!(!selected("#plain"));
assert!(!selected("#native-unchecked"));
assert!(!selected("#aria-false"));
assert!(!selected("#current-false"));
assert!(!selected("#selected-false"));
}
#[test]
fn node_activation_reaches_an_offscreen_mousedown_handler() {
let mut document = ScriptDocument::from_html(
r#"
<button id="target" style="position:absolute;left:-900px;width:80px;height:30px">Run</button>
<output id="result"></output>
<script>
const target = document.getElementById("target");
const result = document.getElementById("result");
target.addEventListener("mousedown", () => result.textContent += "down ");
target.addEventListener("click", () => result.textContent += "click");
</script>
"#,
DocumentConfig::default(),
);
document.execute_scripts();
document.inner_mut().resolve(0.0);
let (target, result) = {
let inner = document.inner();
(
inner.query_selector("#target").unwrap().unwrap(),
inner.query_selector("#result").unwrap().unwrap(),
)
};
assert!(
document
.inner()
.get_client_bounding_rect(target)
.is_some_and(|rect| rect.x < 0.0),
"the fixture must be outside the viewport"
);
activate_agent_node(&mut document, target.as_u64(), 1).unwrap();
assert_eq!(
document.inner().get_node(result).unwrap().text_content(),
"down click"
);
}
#[test]
fn node_activation_bubbles_to_delegated_handlers() {
let mut document = ScriptDocument::from_html(
r#"
<main id="root">
<button id="target" style="width:80px;height:30px">Run</button>
<output id="result"></output>
</main>
<script>
const root = document.getElementById("root");
const result = document.getElementById("result");
root.addEventListener("mousedown", event => {
if (event.target.id === "target") result.textContent += "down ";
});
root.addEventListener("click", event => {
if (event.target.id === "target") result.textContent += "click";
});
</script>
"#,
DocumentConfig::default(),
);
document.execute_scripts();
document.inner_mut().resolve(0.0);
let (target, result) = {
let inner = document.inner();
(
inner.query_selector("#target").unwrap().unwrap(),
inner.query_selector("#result").unwrap().unwrap(),
)
};
activate_agent_node(&mut document, target.as_u64(), 1).unwrap();
assert_eq!(
document.inner().get_node(result).unwrap().text_content(),
"down click"
);
}
#[test]
fn node_activation_reaches_solid_style_document_delegation() {
let mut document = ScriptDocument::from_html(
r#"
<main id="root">
<button id="target" style="width:80px;height:30px">Run</button>
<output id="result"></output>
</main>
<script>
const target = document.getElementById("target");
const result = document.getElementById("result");
target.$$click = () => result.textContent = "delegated";
document.addEventListener("click", event => {
let node = event.target;
while (node) {
if (node.$$click) node.$$click(event);
node = node.parentNode;
}
});
</script>
"#,
DocumentConfig::default(),
);
document.execute_scripts();
document.inner_mut().resolve(0.0);
let (target, result) = {
let inner = document.inner();
(
inner.query_selector("#target").unwrap().unwrap(),
inner.query_selector("#result").unwrap().unwrap(),
)
};
activate_agent_node(&mut document, target.as_u64(), 1).unwrap();
assert_eq!(
document.inner().get_node(result).unwrap().text_content(),
"delegated"
);
}
#[test]
fn node_activation_applies_the_native_focus_default() {
let mut document = ScriptDocument::from_html(
r#"<main><div id="slider" role="slider" tabindex="0" style="width:80px;height:30px">Value</div></main>"#,
DocumentConfig::default(),
);
document.inner_mut().resolve(0.0);
let slider = document.inner().query_selector("#slider").unwrap().unwrap();
activate_agent_node(&mut document, slider.as_u64(), 1).unwrap();
assert_eq!(document.inner().get_focussed_node_id(), Some(slider));
}
#[test]
fn semantic_focus_does_not_activate_the_target() {
let mut document = ScriptDocument::from_html(
r#"
<main>
<button id="target" style="width:80px;height:30px">Start fork</button>
<output id="result"></output>
</main>
<script>
document.getElementById("target").addEventListener("click", () => {
document.getElementById("result").textContent = "activated";
});
</script>
"#,
DocumentConfig::default(),
);
document.execute_scripts();
document.inner_mut().resolve(0.0);
let (target, result) = {
let inner = document.inner();
(
inner.query_selector("#target").unwrap().unwrap(),
inner.query_selector("#result").unwrap().unwrap(),
)
};
focus_agent_node(&mut document, target).unwrap();
assert_eq!(document.inner().get_focussed_node_id(), Some(target));
assert_eq!(
document.inner().get_node(result).unwrap().text_content(),
""
);
}
#[test]
fn setting_a_node_value_replaces_text_and_dispatches_input() {
let mut document = ScriptDocument::from_html(
r#"
<main>
<input id="field" value="old" style="width:80px;height:30px">
<output id="result"></output>
</main>
<script>
const field = document.getElementById("field");
const result = document.getElementById("result");
field.addEventListener("input", event => result.textContent = event.target.value);
</script>
"#,
DocumentConfig::default(),
);
document.execute_scripts();
document.inner_mut().resolve(0.0);
let (field, result) = {
let inner = document.inner();
(
inner.query_selector("#field").unwrap().unwrap(),
inner.query_selector("#result").unwrap().unwrap(),
)
};
let replacement = "https://example.test/org/repository/issues/40?view=full#comment-2";
crate::in_process::set_node_value(&mut document, field, replacement.into()).unwrap();
let inner = document.inner();
let text = inner
.get_node(field)
.unwrap()
.element_data()
.unwrap()
.text_input_data()
.unwrap()
.editor
.raw_text();
assert_eq!(text, replacement);
assert_eq!(inner.get_node(result).unwrap().text_content(), replacement);
}
#[test]
fn node_double_click_is_one_runtime_action() {
let mut document = ScriptDocument::from_html(
r#"
<button id="target" style="width:80px;height:30px">Open row</button>
<output id="result"></output>
<script>
document.getElementById("target").addEventListener("dblclick", () => {
document.getElementById("result").textContent = "double";
});
</script>
"#,
DocumentConfig::default(),
);
document.execute_scripts();
let (target, result) = {
let inner = document.inner();
(
inner.query_selector("#target").unwrap().unwrap(),
inner.query_selector("#result").unwrap().unwrap(),
)
};
activate_agent_node(&mut document, target.as_u64(), 2).unwrap();
assert_eq!(
document.inner().get_node(result).unwrap().text_content(),
"double"
);
}
#[cfg(feature = "capture")]
#[test]
fn repeated_live_captures_reuse_one_surface_and_keep_identical_pixels() {
use blitz_traits::shell::{ColorScheme, Viewport};
let mut document = ScriptDocument::from_html(
"<body style='margin:0;background:transparent'><main style='width:320px;height:200px;background:rgba(24,32,42,.55);color:#f4f5f7'>\
<h1>Capture cache</h1><button>Ready</button>\
</main></body>",
DocumentConfig::default(),
);
document
.inner_mut()
.set_viewport(Viewport::new(320, 200, 1.0, ColorScheme::Dark));
document.inner_mut().resolve(0.0);
let mut surface = None;
let request = crate::CaptureRequest::default();
let first = capture_document_with_surface(&mut document, request, &mut surface).unwrap();
let first_renderer = surface
.as_ref()
.map(|cached| std::ptr::from_ref(&cached.renderer))
.unwrap();
let second = capture_document_with_surface(&mut document, request, &mut surface).unwrap();
let second_renderer = surface
.as_ref()
.map(|cached| std::ptr::from_ref(&cached.renderer))
.unwrap();
assert_eq!(first_renderer, second_renderer);
assert_eq!(first.width, 320);
assert_eq!(first.height, 200);
assert_eq!(first.rgba_base64, second.rgba_base64);
}
#[cfg(feature = "capture")]
#[test]
fn node_region_matches_the_same_pixels_cut_from_a_full_document_capture() {
use base64::Engine as _;
use blitz_traits::shell::{ColorScheme, Viewport};
let mut document = ScriptDocument::from_html(
"<main style='width:320px;height:200px;background:#18202a;padding:24px'>\
<button id='target' style='width:96px;height:40px;background:#d24db8;color:#111'>Ready</button>\
</main>",
DocumentConfig::default(),
);
document
.inner_mut()
.set_viewport(Viewport::new(320, 200, 1.0, ColorScheme::Dark));
document.inner_mut().resolve(0.0);
let (target, left, top) = {
let inner = document.inner();
let target = inner.query_selector("#target").unwrap().unwrap();
let position = inner.get_node(target).unwrap().absolute_position(0.0, 0.0);
(
target,
position.x.round() as usize,
position.y.round() as usize,
)
};
let mut surface = None;
let full = capture_document_with_surface(
&mut document,
crate::CaptureRequest::default(),
&mut surface,
)
.unwrap();
let node = capture_document_with_surface(
&mut document,
crate::CaptureRequest {
node_id: Some(target.as_u64()),
scale: 1.0,
},
&mut surface,
)
.unwrap();
let full_rgba = base64::engine::general_purpose::STANDARD
.decode(full.rgba_base64)
.unwrap();
let node_rgba = base64::engine::general_purpose::STANDARD
.decode(node.rgba_base64)
.unwrap();
let mut expected = Vec::with_capacity(node_rgba.len());
for row in 0..node.height as usize {
let start = ((top + row) * full.width as usize + left) * 4;
expected.extend_from_slice(&full_rgba[start..start + node.width as usize * 4]);
}
assert!(node.width > 0);
assert!(node.height > 0);
assert_eq!(node_rgba, expected);
}
#[cfg(feature = "capture")]
#[test]
fn fixed_node_capture_uses_viewport_coordinates_after_document_scroll() {
use blitz_traits::shell::{ColorScheme, Viewport};
let mut document = ScriptDocument::from_html(
"<body style='margin:0;height:1600px'>\
<textarea id='target' style='position:fixed;left:24px;top:32px;width:240px;height:96px;background:#18202a'>theme css</textarea>\
</body>",
DocumentConfig::default(),
);
document
.inner_mut()
.set_viewport(Viewport::new(320, 200, 1.0, ColorScheme::Dark));
document.inner_mut().resolve(0.0);
document
.inner_mut()
.set_viewport_scroll(blitz_dom::Point { x: 0.0, y: 600.0 });
let target = document.inner().query_selector("#target").unwrap().unwrap();
let expected = document
.inner()
.get_client_bounding_rect(target)
.expect("the fixed textarea is laid out");
let image = capture_document(
&mut document,
crate::CaptureRequest {
node_id: Some(target.as_u64()),
scale: 1.0,
},
)
.unwrap();
assert!(expected.width > 0.0 && expected.height > 1.0);
assert_eq!(image.width, expected.width.round() as u32);
assert_eq!(image.height, expected.height.round() as u32);
}
#[cfg(feature = "capture")]
#[test]
fn diagnostic_layout_reports_scroll_state_without_script_evaluation() {
let mut document = ScriptDocument::from_html(
"<section id='scroller' style='height:100px;overflow-y:auto'><div style='height:400px'>tail</div></section>",
DocumentConfig::default(),
);
document.inner_mut().resolve(0.0);
let scroller = document
.inner()
.tree()
.iter()
.find_map(|(id, node)| {
node.element_data()
.is_some_and(|element| element_attr(element, "id") == Some("scroller"))
.then_some(id)
})
.unwrap();
document
.inner_mut()
.get_node_mut(scroller)
.unwrap()
.scroll_offset_mut()
.y = 60.0;
let inner = document.inner();
let row = diagnostic_layout_row(
&inner,
&SemanticNode {
dom_id: Some("scroller".into()),
id: scroller.as_u64(),
parent: None,
role: "generic".into(),
name: "Scrollable region".into(),
value: None,
enabled: true,
focusable: false,
viewport_fixed: false,
visible: true,
selected: false,
bounds: Some([0.0, 0.0, 100.0, 100.0]),
slot: None,
attributes: BTreeMap::new(),
},
)
.unwrap();
assert_eq!(row.scroll_offset.y, 60.0);
assert_eq!(row.client_size.height, 100.0);
assert!(row.scroll_size.height >= 100.0);
assert!(row.scroll_range.height >= 0.0);
}
#[cfg(feature = "capture")]
#[test]
fn diagnostic_style_reports_resolved_font_and_border() {
let mut document = ScriptDocument::from_html(
"<main id='target' style='font-size:1.4375rem;border:2px solid #123456'>Readable</main>",
DocumentConfig::default(),
);
document.inner_mut().resolve(0.0);
let target = document.inner().query_selector("#target").unwrap().unwrap();
let inner = document.inner();
let row = diagnostic_style_row(
&inner,
&SemanticNode {
dom_id: Some("target".into()),
id: target.as_u64(),
parent: None,
role: "main".into(),
name: "Readable".into(),
value: None,
enabled: true,
focusable: false,
viewport_fixed: false,
visible: true,
selected: false,
bounds: Some([0.0, 0.0, 100.0, 24.0]),
slot: None,
attributes: BTreeMap::new(),
},
)
.unwrap();
assert_eq!(row["fontSize"], "23px");
assert_eq!(row["borderColor"], "#123456ff");
assert_eq!(row["borderWidth"], "2px");
assert_eq!(row["hasTextContent"], true);
}
#[test]
fn native_key_event_preserves_physical_code_and_modifiers() {
let event = key_event(
KeyPhase::Down,
Key::Character("2".into()),
Code::Digit2,
KeyboardModifiers::META,
);
assert_eq!(event.code, Code::Digit2);
assert!(event.modifiers.meta());
assert!(event.text.is_none());
}
#[test]
fn agent_action_settlement_drains_until_the_document_is_idle() {
let mut document =
ScriptDocument::from_html("<main>Ready</main>", DocumentConfig::default());
let polls = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
let observed = std::sync::Arc::clone(&polls);
document.set_poll_hook(move |_, _| {
observed.fetch_add(1, std::sync::atomic::Ordering::Relaxed) < 3
});
crate::in_process::settle(&mut document).unwrap();
assert_eq!(polls.load(std::sync::atomic::Ordering::Relaxed), 4);
}
#[test]
fn agent_action_settlement_never_acks_a_still_runnable_document() {
let mut document =
ScriptDocument::from_html("<main>Busy</main>", DocumentConfig::default());
let polls = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
let observed = std::sync::Arc::clone(&polls);
document.set_poll_hook(move |_, _| {
observed.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
true
});
let error = crate::in_process::settle(&mut document).unwrap_err();
assert_eq!(error.code, "actionDidNotSettle");
assert_eq!(
polls.load(std::sync::atomic::Ordering::Relaxed),
crate::in_process::MAX_SETTLE_POLLS
);
}
}