Skip to content

The design language that makes your AI harness better at design.

JavaScript

URL scans refuse challenge and error pages and name the flagged element

Paul Bakaus5bb677b1e2dd
diff --git a/crates/browser/src/cdp.rs b/crates/browser/src/cdp.rs
index 377d1bd9e..31fe34fd7 100644
--- a/crates/browser/src/cdp.rs
+++ b/crates/browser/src/cdp.rs
@@ -307,6 +307,7 @@ impl Browser {
swapped: false,
same_document_navigation: false,
iframe_sessions: HashSet::new(),
+ main_document_response: None,
};
page.initialize()?;
Ok(page)
@@ -579,6 +580,9 @@ pub struct Page<'a> {
same_document_navigation: bool,
/// Auto-attached OOPIF sessions whose Page events feed the frame map.
iframe_sessions: HashSet<String>,
+ /// The CDP `Network.Response` of the main frame's latest document load
+ /// (the last one wins, so after redirects this is the final response).
+ main_document_response: Option<Value>,
}
/// A raw `Runtime.evaluate` outcome.
@@ -818,6 +822,15 @@ impl<'a> Page<'a> {
self.swapped = true;
}
}
+ "Network.responseReceived" => {
+ if session == self.session_id
+ && params.get("type").and_then(Value::as_str) == Some("Document")
+ && params.get("frameId").and_then(Value::as_str)
+ == Some(self.main_frame_id.as_str())
+ {
+ self.main_document_response = params.get("response").cloned();
+ }
+ }
"Page.navigatedWithinDocument" => {
if params.get("frameId").and_then(Value::as_str)
== Some(self.main_frame_id.as_str())
@@ -966,6 +979,7 @@ impl<'a> Page<'a> {
.unwrap_or_default();
self.swapped = false;
self.same_document_navigation = false;
+ self.main_document_response = None;
let deadline = Instant::now() + timeout;
let timeout_msg = format!("Navigation timeout of {} ms exceeded", timeout.as_millis());
@@ -1128,6 +1142,40 @@ impl<'a> Page<'a> {
.to_string())
}
+ /// The main document's latest CDP `Network.Response` since the last
+ /// [`Page::goto`], or `None` when no document response was seen (a
+ /// `file://` load can have none).
+ pub fn main_document_response(&mut self) -> Option<Value> {
+ self.pump_events();
+ self.main_document_response.clone()
+ }
+
+ /// A JPEG of the given document region (`captureBeyondViewport`), base64.
+ pub fn screenshot_jpeg(
+ &mut self,
+ x: f64,
+ y: f64,
+ width: f64,
+ height: f64,
+ quality: u32,
+ ) -> CdpResult<String> {
+ let res = self.send(
+ "Page.captureScreenshot",
+ json!({
+ "format": "jpeg",
+ "quality": quality.min(100),
+ "fromSurface": true,
+ "clip": { "x": x, "y": y, "width": width.round(), "height": height.round(), "scale": 1 },
+ "captureBeyondViewport": true,
+ }),
+ )?;
+ Ok(res
+ .get("data")
+ .and_then(Value::as_str)
+ .unwrap_or("")
+ .to_string())
+ }
+
/// The deduped `pageerror` messages so far.
pub fn page_errors(&mut self) -> Vec<String> {
self.pump_events();
diff --git a/crates/browser/src/lib.rs b/crates/browser/src/lib.rs
index 98d44b34b..ea3d8009a 100644
--- a/crates/browser/src/lib.rs
+++ b/crates/browser/src/lib.rs
@@ -14,11 +14,23 @@
//! a single URL uses `detect_url` (`waitUntil: 'networkidle0'`, `settleMs:
//! 0`); several URLs share one browser through [`SharedBrowser`]
//! (`createBrowserDetector()`: `waitUntil: 'load'`, `settleMs: 100`).
+//!
+//! Before any rule runs, the loaded page is classified ([`validity`]): a bot
+//! challenge or an HTTP error page is refused with an error instead of being
+//! scanned and reported clean.
+//!
+//! Two entry points serve measurement work rather than the CLI.
+//! [`detect_url_evidence`] runs the same scan and also returns what a
+//! reviewer needs to check the findings (the captures and hit-test answers,
+//! element rects, a screenshot). [`replay_url_scan`] re-runs the deterministic
+//! passes over a recorded capture with no browser, so a rule change can be
+//! measured against saved pages.
pub mod cdp;
pub mod discovery;
pub mod screenshot_contrast;
pub mod snapshot_engine;
+pub mod validity;
use std::cell::RefCell;
use std::collections::HashMap;
@@ -26,14 +38,16 @@ use std::time::{Duration, Instant};
use impeccable_core::browser::driver::{collect_browser_findings, serialize_findings};
use impeccable_core::browser::page_checks::measure_hidden_text_dom;
+use impeccable_core::browser::snapshot::Facts;
use impeccable_core::checks::measures::{check_content_hidden_at_rest, ContentHiddenInput};
use impeccable_core::findings::{try_finding, Finding};
use impeccable_detect::design_system::DesignSystem;
use impeccable_detect::engines::{EngineError, ScanOptions, SharedBrowser, UrlEngine};
use impeccable_detect::profiler::{DetectorProfile, ProfileMeta};
-use serde_json::{json, Value};
+use serde_json::{json, Map, Value};
use cdp::{Browser, CdpError, Page, Viewport};
+use validity::{DocumentResponse, PageProbe, PageValidity};
/// puppeteer's default `page.goto` timeout the JS passes explicitly.
const NAVIGATION_TIMEOUT: Duration = Duration::from_millis(30000);
@@ -75,7 +89,7 @@ impl BrowserEngine {
}
/// `launchBrowser()`: discover, then launch headless.
- fn launch(&self) -> Result<Browser, EngineError> {
+ pub fn launch(&self) -> Result<Browser, EngineError> {
let exe = discovery::find_browser(&self.env).map_err(EngineError::new)?;
Browser::launch(&exe, &self.launch_args(), self.dangerous_no_sandbox())
.map_err(|e| EngineError::new(e.message))
@@ -227,12 +241,101 @@ pub fn serialize_design_system_for_browser(ds: Option<&DesignSystem>) -> Value {
})
}
+/// The pass that produced a finding, as [`Evidence::origins`] names it.
+pub mod origin {
+ /// The deterministic rule pass over the first capture. Replayable.
+ pub const SCAN: &str = "scan";
+ /// `content-hidden-at-rest`, over the post-reveal capture. Replayable.
+ pub const CONTENT_HIDDEN: &str = "content-hidden";
+ /// Uncaught page errors. Recorded, not replayable.
+ pub const SCRIPT_ERROR: &str = "script-error";
+ /// The visual-contrast pass (image and pixel reads). Recorded, not
+ /// replayable.
+ pub const VISUAL_CONTRAST: &str = "visual-contrast";
+}
+
/// A pre-registry finding as `detectUrl` accumulates them.
struct RawResult {
id: String,
snippet: String,
ignore_value: String,
severity: String,
+ /// The flagged element's selector, when the pass names an element.
+ selector: Option<String>,
+ origin: &'static str,
+}
+
+impl RawResult {
+ fn new(origin: &'static str, id: String, snippet: String) -> RawResult {
+ RawResult {
+ id,
+ snippet,
+ ignore_value: String::new(),
+ severity: String::new(),
+ selector: None,
+ origin,
+ }
+ }
+}
+
+/// What [`detect_url_evidence`] records next to the findings.
+#[derive(Debug, Default)]
+pub struct Evidence {
+ /// The main document's final HTTP response, when one was seen.
+ pub response: Option<DocumentResponse>,
+ /// The in-page probe the validity gate ran.
+ pub probe: Option<PageProbe>,
+ /// The validity verdict. A blocked page has no captures and no findings.
+ pub validity: Option<PageValidity>,
+ /// The first capture's JSON, which the rule pass ran over.
+ pub scan_snapshot: Option<String>,
+ /// Every hit test answered for the first capture.
+ pub scan_facts: Facts,
+ /// The post-reveal capture's JSON (`content-hidden-at-rest`).
+ pub reveal_snapshot: Option<String>,
+ /// Every hit test answered for the post-reveal capture's hidden-text measure.
+ pub reveal_facts: Facts,
+ /// Parallel to the findings: which pass produced each (see [`origin`]).
+ pub origins: Vec<&'static str>,
+ /// Document-coordinate `[x, y, width, height]` of each flagged selector,
+ /// measured after the scan, so they match [`Evidence::screenshot`].
+ pub element_rects: Map<String, Value>,
+ /// Per flagged selector, measured after the scan: `{ tag, text, html,
+ /// styles }` (text and html truncated; a fixed set of computed styles).
+ pub element_details: Map<String, Value>,
+ pub screenshot: Option<Screenshot>,
+ /// Why no screenshot was taken, when one was requested and failed.
+ pub screenshot_error: Option<String>,
+}
+
+/// A full-page screenshot taken after the scan.
+#[derive(Debug, Clone)]
+pub struct Screenshot {
+ pub jpeg_base64: String,
+ /// CSS pixels (the scan uses a device scale factor of 1).
+ pub width: f64,
+ pub height: f64,
+ /// The document's height; larger than `height` when the capture was cut.
+ pub document_height: f64,
+}
+
+/// What [`detect_url_evidence`] should capture beyond the findings.
+#[derive(Debug, Clone)]
+pub struct EvidenceRequest {
+ pub screenshot: bool,
+ /// Cut the screenshot at this height (CSS pixels).
+ pub max_screenshot_height: f64,
+ pub jpeg_quality: u32,
+}
+
+impl Default for EvidenceRequest {
+ fn default() -> Self {
+ EvidenceRequest {
+ screenshot: true,
+ max_screenshot_height: 12000.0,
+ jpeg_quality: 82,
+ }
+ }
}
fn cdp_err(e: CdpError) -> EngineError {
@@ -315,6 +418,14 @@ fn js_str_or_empty(v: Option<&Value>) -> String {
}
}
+/// A non-empty `selector` field.
+fn selector_of(v: &Value) -> Option<String> {
+ v.get("selector")
+ .and_then(Value::as_str)
+ .filter(|s| !s.is_empty())
+ .map(String::from)
+}
+
/// `detectUrl(url, options)` with the wait/settle defaults the caller picks
/// and an optional shared browser (`options.browser`).
fn detect_url_impl(
@@ -332,11 +443,6 @@ fn detect_url_impl(
let url = url.as_str();
let credentials = credentials.as_ref();
let profile = options.profile.as_deref();
- let (vw, vh) = options.viewport.unwrap_or((1280, 800));
- let viewport = Viewport {
- width: vw,
- height: vh,
- };
let owns_browser = external.is_none();
let mut owned: Option<Browser> = None;
let browser: &mut Browser = match external {
@@ -357,22 +463,107 @@ fn detect_url_impl(
}
};
- let page = step(profile, "load", "new-page", url, || browser.new_page()).map_err(cdp_err);
- let scanned = match page {
- Ok(page) => scan_page(
- page, url, credentials, options, wait_until, settle_ms, viewport, profile,
- ),
- Err(e) => Err(e),
- };
+ let scanned = scan_on_browser(
+ browser, url, credentials, options, wait_until, settle_ms, profile, None,
+ );
// finally: close page (inside scan_page) and the browser when owned.
if owns_browser {
if let Some(b) = owned.take() {
step(profile, "load", "close-browser", url, || b.close());
}
}
- let results = scanned?;
+ let (findings, _) = results_to_findings(url, scanned?)?;
+ Ok(findings)
+}
+
+/// Run the URL engine's scan on a browser the caller owns and also return
+/// the [`Evidence`] a reviewer needs to check each finding. The findings are
+/// the ones `impeccable detect --json <url>` prints for the same page and
+/// wait strategy. A blocked page returns no findings and an `Ok` with
+/// [`Evidence::validity`] set, instead of the CLI's error.
+pub fn detect_url_evidence(
+ browser: &mut Browser,
+ url: &str,
+ options: &ScanOptions,
+ wait_until: &str,
+ settle_ms: u64,
+ request: &EvidenceRequest,
+) -> Result<(Vec<Finding>, Evidence), EngineError> {
+ let (url, credentials) = split_scan_url(url);
+ let mut evidence = Evidence::default();
+ let results = scan_on_browser(
+ browser,
+ &url,
+ credentials.as_ref(),
+ options,
+ wait_until,
+ settle_ms,
+ options.profile.as_deref(),
+ Some((&mut evidence, request)),
+ )?;
+ let (findings, origins) = results_to_findings(&url, results)?;
+ evidence.origins = origins;
+ Ok((findings, evidence))
+}
+
+/// The outcome of [`replay_url_scan`].
+#[derive(Debug)]
+pub struct ReplayOutcome {
+ /// Findings from the replayable passes ([`origin::SCAN`],
+ /// [`origin::CONTENT_HIDDEN`]), in the order a live scan emits them.
+ pub findings: Vec<Finding>,
+ /// Hit tests the rules asked for that the recording cannot answer. Zero
+ /// for an unchanged engine; a rule change that probes new points reports
+ /// them here, and its findings for those points are an undercount.
+ pub unanswered_hit_tests: usize,
+}
+
+/// Re-run the deterministic passes over a recorded capture, with no browser.
+/// `scan_snapshot` and `scan_facts` come from [`Evidence::scan_snapshot`] and
+/// [`Evidence::scan_facts`]; the post-reveal pair is optional.
+pub fn replay_url_scan(
+ url: &str,
+ scan_snapshot: &str,
+ scan_facts: &Facts,
+ reveal: Option<(&str, &Facts)>,
+ options: &ScanOptions,
+) -> Result<ReplayOutcome, EngineError> {
+ let config = snapshot_engine::browser_config(
+ serialize_design_system_for_browser(options.design_system.as_deref()),
+ options.rule_pack,
+ );
+ let dom = snapshot_engine::parse_snapshot(scan_snapshot).map_err(cdp_err)?;
+ dom.add_facts(scan_facts);
+ let collected = collect_browser_findings(&dom, &config);
+ let mut unanswered = dom.take_needs().hit_tests.len();
+ let groups = serialize_findings(&dom, &collected.groups);
+ let mut results = results_from_groups(groups.as_array().map(Vec::as_slice).unwrap_or(&[]));
+ if let Some((json, facts)) = reveal {
+ let base = snapshot_engine::parse_snapshot(json).map_err(cdp_err)?;
+ base.add_facts(facts);
+ let measured = measure_hidden_text_dom(&base);
+ unanswered += base.take_needs().hit_tests.len();
+ results.extend(content_hidden_results(
+ measured.total_chars,
+ measured.hidden_chars,
+ measured.hidden_samples,
+ ));
+ }
+ let (findings, _) = results_to_findings(url, results)?;
+ Ok(ReplayOutcome {
+ findings,
+ unanswered_hit_tests: unanswered,
+ })
+}
+/// Map raw results onto registry findings, returning each one's origin
+/// alongside.
+fn results_to_findings(
+ url: &str,
+ results: Vec<RawResult>,
+) -> Result<(Vec<Finding>, Vec<&'static str>), EngineError> {
let mut findings = Vec::with_capacity(results.len());
+ let mut origins = Vec::with_capacity(results.len());
for r in results {
let Some(mut item) = try_finding(&r.id, url, &r.snippet, 0.0) else {
// JS: `finding()` dereferences an unknown registry entry.
@@ -384,13 +575,82 @@ fn detect_url_impl(
item.extras
.insert("ignoreValue".into(), Value::String(r.ignore_value));
}
+ if let Some(selector) = r.selector {
+ item.extras.insert("selector".into(), Value::String(selector));
+ }
if !r.severity.is_empty() && r.severity != item.severity {
item.severity = r.severity;
}
impeccable_core::findings::derive_advisory_flag(&mut item);
findings.push(item);
+ origins.push(r.origin);
+ }
+ Ok((findings, origins))
+}
+
+/// Flatten `serialize_findings` groups into raw results, each carrying its
+/// group's selector.
+fn results_from_groups(groups: &[Value]) -> Vec<RawResult> {
+ let mut out = Vec::new();
+ for group in groups {
+ let Some(findings) = group.get("findings").and_then(Value::as_array) else {
+ continue;
+ };
+ let selector = selector_of(group);
+ for f in findings {
+ out.push(RawResult {
+ id: js_str(f.get("type")),
+ snippet: js_str(f.get("detail")),
+ ignore_value: js_str_or_empty(f.get("ignoreValue")),
+ severity: js_str_or_empty(f.get("severity")),
+ selector: selector.clone(),
+ origin: origin::SCAN,
+ });
+ }
+ }
+ out
+}
+
+fn content_hidden_results(
+ total_chars: f64,
+ hidden_chars: f64,
+ hidden_samples: Vec<String>,
+) -> Vec<RawResult> {
+ let input = ContentHiddenInput {
+ total_chars,
+ hidden_chars,
+ hidden_samples,
+ };
+ check_content_hidden_at_rest(&input)
+ .into_iter()
+ .map(|f| RawResult::new(origin::CONTENT_HIDDEN, f.id, f.snippet))
+ .collect()
+}
+
+/// A new page on `browser`, scanned, then closed.
+#[allow(clippy::too_many_arguments)]
+fn scan_on_browser(
+ browser: &mut Browser,
+ url: &str,
+ credentials: Option<&ScanCredentials>,
+ options: &ScanOptions,
+ wait_until: &str,
+ settle_ms: u64,
+ profile: Option<&DetectorProfile>,
+ evidence: Option<(&mut Evidence, &EvidenceRequest)>,
+) -> Result<Vec<RawResult>, EngineError> {
+ let (vw, vh) = options.viewport.unwrap_or((1280, 800));
+ let viewport = Viewport {
+ width: vw,
+ height: vh,
+ };
+ let page = step(profile, "load", "new-page", url, || browser.new_page()).map_err(cdp_err);
+ match page {
+ Ok(page) => scan_page(
+ page, url, credentials, options, wait_until, settle_ms, viewport, profile, evidence,
+ ),
+ Err(e) => Err(e),
}
- Ok(findings)
}
/// Everything between `newPage` and the `finally` that closes the page.
@@ -404,6 +664,7 @@ fn scan_page(
settle_ms: u64,
viewport: Viewport,
profile: Option<&DetectorProfile>,
+ evidence: Option<(&mut Evidence, &EvidenceRequest)>,
) -> Result<Vec<RawResult>, EngineError> {
let outcome = scan_page_inner(
&mut page,
@@ -414,11 +675,32 @@ fn scan_page(
settle_ms,
viewport,
profile,
+ evidence,
);
step(profile, "load", "close-page", url, || page.close());
outcome
}
+/// Probe the loaded page and classify it. A probe that fails because the page
+/// navigated underneath it (a challenge redirecting on its own) is retried
+/// once after a short wait.
+fn check_validity(page: &mut Page<'_>) -> Result<(Option<DocumentResponse>, PageProbe, PageValidity), CdpError> {
+ let js = validity::probe_js();
+ let raw = match page.evaluate_value(&js) {
+ Ok(v) => v,
+ Err(_) => {
+ std::thread::sleep(Duration::from_millis(1000));
+ page.evaluate_value(&js)?
+ }
+ };
+ let probe = PageProbe::from_value(&raw);
+ let response = page
+ .main_document_response()
+ .and_then(|r| DocumentResponse::from_cdp(&r));
+ let verdict = validity::classify(response.as_ref(), &probe);
+ Ok((response, probe, verdict))
+}
+
#[allow(clippy::too_many_arguments)]
fn scan_page_inner(
page: &mut Page<'_>,
@@ -429,6 +711,7 @@ fn scan_page_inner(
settle_ms: u64,
viewport: Viewport,
profile: Option<&DetectorProfile>,
+ mut evidence: Option<(&mut Evidence, &EvidenceRequest)>,
) -> Result<Vec<RawResult>, EngineError> {
step(profile, "load", "set-viewport", url, || {
page.set_viewport(viewport)
@@ -450,6 +733,25 @@ fn scan_page_inner(
});
}
+ // A challenge or error page is not the site: refuse to report on it.
+ let (response, probe, verdict) =
+ step(profile, "load", "validity", url, || check_validity(page)).map_err(cdp_err)?;
+ let blocked = verdict.error_message();
+ if let Some((ev, _)) = evidence.as_mut() {
+ ev.response = response;
+ ev.probe = Some(probe);
+ ev.validity = Some(verdict);
+ }
+ if let Some(message) = blocked {
+ return match evidence {
+ None => Err(EngineError::new(message)),
+ Some((ev, request)) => {
+ capture_post_scan(page, ev, request, &[]);
+ Ok(Vec::new())
+ }
+ };
+ }
+
// Inject the plain-JS snapshot producer (no WebAssembly runs in the page).
step(profile, "scan", "inject-snapshot-script", url, || {
snapshot_engine::ensure_snapshot_js(page)
@@ -468,29 +770,24 @@ fn scan_page_inner(
// produced; the group selectors feed the visual pass below.
let mut serialized_groups: Vec<Value> = Vec::new();
let mut results = step_findings(profile, "scan", "browser-scan", url, || {
- let dom = snapshot_engine::capture_snapshot(page).map_err(cdp_err)?;
- let collected =
- snapshot_engine::resolve_needs(&dom, page, |d| collect_browser_findings(d, &config))
- .map_err(cdp_err)?;
+ let json = snapshot_engine::capture_snapshot_json(page).map_err(cdp_err)?;
+ let dom = snapshot_engine::parse_snapshot(&json).map_err(cdp_err)?;
+ let facts = evidence.as_mut().map(|(ev, _)| {
+ ev.scan_snapshot = Some(json);
+ &mut ev.scan_facts
+ });
+ let collected = snapshot_engine::resolve_needs_recording(
+ &dom,
+ page,
+ |d| collect_browser_findings(d, &config),
+ facts,
+ )
+ .map_err(cdp_err)?;
serialized_groups = serialize_findings(&dom, &collected.groups)
.as_array()
.cloned()
.unwrap_or_default();
- let mut out = Vec::new();
- for group in &serialized_groups {
- let Some(findings) = group.get("findings").and_then(Value::as_array) else {
- continue;
- };
- for f in findings {
- out.push(RawResult {
- id: js_str(f.get("type")),
- snippet: js_str(f.get("detail")),
- ignore_value: js_str_or_empty(f.get("ignoreValue")),
- severity: js_str_or_empty(f.get("severity")),
- });
- }
- }
- Ok::<_, EngineError>(out)
+ Ok::<_, EngineError>(results_from_groups(&serialized_groups))
})?;
// content-hidden-at-rest: reveal sweep, then one post-reveal capture the
@@ -498,37 +795,35 @@ fn scan_page_inner(
// page revealed and scrolled to the top — the scroll-0 snapshot the in-page
// path measured and analyzed).
step(profile, "scan", "reveal-sweep", url, || reveal_sweep(page)).map_err(cdp_err)?;
- let base = snapshot_engine::capture_snapshot(page).map_err(cdp_err)?;
+ let base_json = snapshot_engine::capture_snapshot_json(page).map_err(cdp_err)?;
+ let base = snapshot_engine::parse_snapshot(&base_json).map_err(cdp_err)?;
let hidden = step_findings(profile, "scan", "content-hidden-at-rest", url, || {
- let measured =
- snapshot_engine::resolve_needs(&base, page, |d| measure_hidden_text_dom(d)).map_err(cdp_err)?;
- let input = ContentHiddenInput {
- total_chars: measured.total_chars,
- hidden_chars: measured.hidden_chars,
- hidden_samples: measured.hidden_samples,
- };
- Ok::<_, EngineError>(
- check_content_hidden_at_rest(&input)
- .into_iter()
- .map(|f| RawResult {
- id: f.id,
- snippet: f.snippet,
- ignore_value: String::new(),
- severity: String::new(),
- })
- .collect(),
+ let facts = evidence.as_mut().map(|(ev, _)| {
+ ev.reveal_snapshot = Some(base_json);
+ &mut ev.reveal_facts
+ });
+ let measured = snapshot_engine::resolve_needs_recording(
+ &base,
+ page,
+ |d| measure_hidden_text_dom(d),
+ facts,
)
+ .map_err(cdp_err)?;
+ Ok::<_, EngineError>(content_hidden_results(
+ measured.total_chars,
+ measured.hidden_chars,
+ measured.hidden_samples,
+ ))
})?;
results.extend(hidden);
for message in page.page_errors().into_iter().take(3) {
- results.push(RawResult {
- id: "script-error".to_string(),
- snippet: message,
- ignore_value: String::new(),
- severity: String::new(),
- });
+ results.push(RawResult::new(
+ origin::SCRIPT_ERROR,
+ "script-error".to_string(),
+ message,
+ ));
}
let analyses = step(profile, "visual-contrast", "browser-analyze", url, || {
@@ -537,9 +832,95 @@ fn scan_page_inner(
.map_err(cdp_err)?;
let visual = run_visual_contrast_fallback(page, &analyses, &serialized_groups, viewport, profile, url)?;
results.extend(visual);
+
+ if let Some((ev, request)) = evidence {
+ let mut selectors: Vec<String> = Vec::new();
+ for r in &results {
+ if let Some(s) = &r.selector {
+ if !selectors.contains(s) {
+ selectors.push(s.clone());
+ }
+ }
+ }
+ capture_post_scan(page, ev, request, &selectors);
+ }
Ok(results)
}
+/// Element rects and the screenshot, after every pass has run, so a live
+/// scan and an evidence scan drive the page identically up to here. Failures
+/// are recorded on the evidence, never raised: the findings stand without them.
+fn capture_post_scan(
+ page: &mut Page<'_>,
+ ev: &mut Evidence,
+ request: &EvidenceRequest,
+ selectors: &[String],
+) {
+ if !selectors.is_empty() {
+ let expr = format!(
+ r#"(() => {{
+ const props = ['display', 'position', 'font-family', 'font-size', 'font-weight', 'font-style', 'line-height', 'letter-spacing', 'text-transform', 'text-align', 'color', 'background-color', 'background-image', 'border', 'border-radius', 'box-shadow', 'padding', 'margin', 'width', 'height', 'max-width', 'opacity'];
+ const rects = {{}};
+ const details = {{}};
+ for (const s of {sels}) {{
+ try {{
+ const el = document.querySelector(s);
+ if (!el) continue;
+ const r = el.getBoundingClientRect();
+ rects[s] = [r.x + window.scrollX, r.y + window.scrollY, r.width, r.height];
+ const cs = getComputedStyle(el);
+ const styles = {{}};
+ for (const p of props) styles[p] = cs.getPropertyValue(p);
+ details[s] = {{
+ tag: el.tagName.toLowerCase(),
+ text: (el.innerText || el.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 300),
+ html: (el.outerHTML || '').slice(0, 1500),
+ styles,
+ }};
+ }} catch (e) {{}}
+ }}
+ return {{ rects, details }};
+}})()"#,
+ sels = json!(selectors)
+ );
+ if let Ok(v) = page.evaluate_value(&expr) {
+ if let Some(Value::Object(m)) = v.get("rects") {
+ ev.element_rects = m.clone();
+ }
+ if let Some(Value::Object(m)) = v.get("details") {
+ ev.element_details = m.clone();
+ }
+ }
+ }
+ if !request.screenshot {
+ return;
+ }
+ let dims = page.evaluate_value(
+ "(() => ({ w: window.innerWidth, h: Math.max(document.documentElement ? document.documentElement.scrollHeight : 0, document.body ? document.body.scrollHeight : 0, window.innerHeight) }))()",
+ );
+ let dims = match dims {
+ Ok(d) => d,
+ Err(e) => {
+ ev.screenshot_error = Some(e.message);
+ return;
+ }
+ };
+ let width = dims.get("w").and_then(Value::as_f64).unwrap_or(1280.0).max(1.0);
+ let document_height = dims.get("h").and_then(Value::as_f64).unwrap_or(800.0).max(1.0);
+ let height = document_height.min(request.max_screenshot_height);
+ match page.screenshot_jpeg(0.0, 0.0, width, height, request.jpeg_quality) {
+ Ok(jpeg_base64) => {
+ ev.screenshot = Some(Screenshot {
+ jpeg_base64,
+ width,
+ height,
+ document_height,
+ })
+ }
+ Err(e) => ev.screenshot_error = Some(e.message),
+ }
+}
+
/// The `measureContentHiddenAfterReveal` reveal sweep: scroll the page top to
/// bottom (revealing lazy / on-scroll content), then back to the top and
/// settle. The hidden-text measure then runs natively over a fresh capture.
@@ -598,12 +979,10 @@ fn run_visual_contrast_fallback(
.iter()
.any(|s| Some(s.as_str()) == r.get("selector").and_then(Value::as_str))
})
- .filter_map(|r| r.get("finding"))
- .map(|f| RawResult {
- id: js_str(f.get("id")),
- snippet: js_str(f.get("snippet")),
- ignore_value: String::new(),
- severity: String::new(),
+ .filter_map(|r| r.get("finding").map(|f| (f, selector_of(r))))
+ .map(|(f, selector)| RawResult {
+ selector,
+ ..RawResult::new(origin::VISUAL_CONTRAST, js_str(f.get("id")), js_str(f.get("snippet")))
})
.collect();
@@ -645,10 +1024,8 @@ fn run_visual_contrast_fallback(
Ok::<_, EngineError>(
f.map(|f| {
vec![RawResult {
- id: f.id.to_string(),
- snippet: f.snippet,
- ignore_value: String::new(),
- severity: String::new(),
+ selector: selector_of(candidate),
+ ..RawResult::new(origin::VISUAL_CONTRAST, f.id.to_string(), f.snippet)
}]
})
.unwrap_or_default(),
@@ -680,6 +1057,23 @@ mod tests {
assert!(serialize_design_system_for_browser(Some(&ds)).is_null());
}
+ #[test]
+ fn group_findings_carry_the_group_selector() {
+ let groups = vec![json!({
+ "selector": "main > h1",
+ "findings": [
+ { "type": "tight-leading", "detail": "line-height 1.15x (need >=1.3)", "ignoreValue": "", "severity": "warning" },
+ ],
+ })];
+ let (findings, origins) =
+ results_to_findings("https://example.com/", results_from_groups(&groups)).unwrap();
+ assert_eq!(findings.len(), 1);
+ assert_eq!(findings[0].extras.get("selector"), Some(&json!("main > h1")));
+ assert_eq!(origins, vec![origin::SCAN]);
+ let text = serde_json::to_string(&findings[0]).unwrap();
+ assert!(text.ends_with(r#""line":0,"snippet":"line-height 1.15x (need >=1.3)","selector":"main > h1"}"#));
+ }
+
// Expected values come from tests/detect-url-launch.test.mjs (issue #657).
#[test]
fn split_scan_url_matches_js() {
diff --git a/crates/browser/src/snapshot_engine.rs b/crates/browser/src/snapshot_engine.rs
index cdd115d3e..c5d90261f 100644
--- a/crates/browser/src/snapshot_engine.rs
+++ b/crates/browser/src/snapshot_engine.rs
@@ -55,15 +55,25 @@ pub fn ensure_snapshot_js(page: &mut Page<'_>) -> CdpResult<()> {
/// stable across scrolls (the DOM is unchanged), which is why an earlier
/// snapshot's ids keep matching the page's current `__impCap`.
pub fn capture_snapshot(page: &mut Page<'_>) -> CdpResult<SnapshotDom> {
+ parse_snapshot(&capture_snapshot_json(page)?)
+}
+
+/// [`capture_snapshot`] without the parse: the capture's JSON exactly as the
+/// page produced it, which is what a replay loads.
+pub fn capture_snapshot_json(page: &mut Page<'_>) -> CdpResult<String> {
let expr = "(function(){ const s = window.__impeccableSnapshot; const c = s.capture(); if (c.error) return { error: c.error }; window.__impCap = c; window.__impIO = s.visualIO(c); return { json: c.json }; })()";
let out = page.evaluate_value(expr)?;
if let Some(err) = out.get("error").and_then(Value::as_str) {
return Err(CdpError::new(format!("snapshot capture failed: {err}")));
}
- let json = out
- .get("json")
+ out.get("json")
.and_then(Value::as_str)
- .ok_or_else(|| CdpError::new("snapshot capture returned no json"))?;
+ .map(String::from)
+ .ok_or_else(|| CdpError::new("snapshot capture returned no json"))
+}
+
+/// Parse a capture's JSON into a [`SnapshotDom`].
+pub fn parse_snapshot(json: &str) -> CdpResult<SnapshotDom> {
SnapshotDom::from_json(json).map_err(|e| CdpError::new(format!("snapshot parse: {e}")))
}
@@ -164,6 +174,17 @@ pub fn resolve_needs<T>(
dom: &SnapshotDom,
page: &mut Page<'_>,
f: impl Fn(&SnapshotDom) -> T,
+) -> CdpResult<T> {
+ resolve_needs_recording(dom, page, f, None)
+}
+
+/// [`resolve_needs`], appending every answered hit test to `record` so the
+/// run can be replayed over the same capture without the page.
+pub fn resolve_needs_recording<T>(
+ dom: &SnapshotDom,
+ page: &mut Page<'_>,
+ f: impl Fn(&SnapshotDom) -> T,
+ mut record: Option<&mut Facts>,
) -> CdpResult<T> {
let mut out = f(dom);
let mut rounds = 0;
@@ -171,6 +192,9 @@ pub fn resolve_needs<T>(
let needs = dom.take_needs();
let facts = answer_needs(page, &needs.hit_tests)?;
dom.add_facts(&facts);
+ if let Some(record) = record.as_deref_mut() {
+ record.hits.extend(facts.hits.iter().cloned());
+ }
out = f(dom);
rounds += 1;
}
diff --git a/crates/browser/src/validity.rs b/crates/browser/src/validity.rs
new file mode 100644
index 000000000..1e8d8a8e9
--- /dev/null
+++ b/crates/browser/src/validity.rs
@@ -0,0 +1,424 @@
+//! Whether a loaded page is the site, or something standing in front of it.
+//!
+//! A bot challenge, a WAF block page, or an HTTP error page is a real page the
+//! rules can run over, and a challenge page is small enough to come back
+//! clean. A scan of it reports on the wrong page and exits 0, which reads as
+//! "this site is fine". The URL engine classifies the page right after
+//! navigation and refuses to report on a blocked one, so a clean result
+//! always describes the site that was asked about.
+//!
+//! The decision is pure ([`classify`]) over two inputs: the main document's
+//! HTTP response as CDP saw it, and a small in-page probe ([`PROBE_JS`]).
+//! Header and HTTP-status signals stand alone. Titles and DOM markers only
+//! count on a small page, because a real page can carry a captcha widget on a
+//! form or be titled "Access denied" in a CMS without being a block page.
+
+use serde_json::{json, Value};
+
+/// Challenge pages are short. A page with more visible text than this is
+/// treated as content even when its title or a marker looks like a challenge.
+pub const SMALL_PAGE_CHARS: u64 = 3000;
+
+/// Titles challenge and block pages use, lowercased and trimmed. Matched by
+/// prefix, so "Access Denied" also covers "Access Denied - Reference #18...".
+const CHALLENGE_TITLE_PREFIXES: &[&str] = &[
+ "just a moment",
+ "attention required! | cloudflare",
+ "checking your browser",
+ "human verification",
+ "access denied",
+ "access to this page has been denied",
+ "pardon our interruption",
+ "are you a robot",
+ "robot or human",
+ "please verify you are a human",
+ "verify you are human",
+ "bot verification",
+ "security check",
+ "you have been blocked",
+ "request rejected",
+ "ddos-guard",
+ "one more step",
+ "403 forbidden",
+ "radware bot manager",
+ "captcha",
+];
+
+/// Hosts that only serve challenges. A page that ends up on one of them after
+/// redirects is a challenge whatever its title says.
+const CHALLENGE_HOSTS: &[&str] = &["perfdrive.com", "captcha-delivery.com"];
+
+/// DOM markers of challenge widgets that fill a page (not inline form
+/// captchas). Each entry is `(selector, label)`; the probe reports the labels
+/// of the selectors that match.
+pub const CHALLENGE_MARKERS: &[(&str, &str)] = &[
+ ("#challenge-form, #challenge-running, #cf-challenge-running", "cloudflare-challenge"),
+ ("#px-captcha", "perimeterx-captcha"),
+ ("iframe[src*='captcha-delivery.com']", "datadome-captcha"),
+ ("iframe[src*='_Incapsula_Resource']", "imperva-incapsula"),
+ ("#sec-if-cpt-container, #sec-cpt-if", "akamai-challenge"),
+ ("#captcha-container[class*='amzn'], awswaf-captcha", "aws-waf-captcha"),
+ (".geetest_holder, #nc_1_wrapper, #aliyunCaptcha-sliding-wrapper", "slider-captcha"),
+];
+
+/// The in-page probe: title, visible text length, final URL, and which
+/// challenge markers are present. Read-only; returns a plain object.
+pub fn probe_js() -> String {
+ let markers: Vec<Value> = CHALLENGE_MARKERS
+ .iter()
+ .map(|(selector, label)| json!([selector, label]))
+ .collect();
+ format!(
+ r#"(() => {{
+ const markers = {markers};
+ const found = [];
+ for (const [selector, label] of markers) {{
+ try {{ if (document.querySelector(selector)) found.push(label); }} catch (e) {{}}
+ }}
+ const text = (document.body && document.body.innerText) || '';
+ return {{
+ title: String(document.title || ''),
+ textChars: text.replace(/\s+/g, ' ').trim().length,
+ href: String(location.href || ''),
+ markers: found,
+ }};
+}})()"#,
+ markers = Value::Array(markers)
+ )
+}
+
+/// What the probe saw in the page.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct PageProbe {
+ pub title: String,
+ pub text_chars: u64,
+ pub href: String,
+ pub markers: Vec<String>,
+}
+
+impl PageProbe {
+ pub fn from_value(v: &Value) -> PageProbe {
+ PageProbe {
+ title: v.get("title").and_then(Value::as_str).unwrap_or("").to_string(),
+ text_chars: v.get("textChars").and_then(Value::as_f64).unwrap_or(0.0).max(0.0) as u64,
+ href: v.get("href").and_then(Value::as_str).unwrap_or("").to_string(),
+ markers: v
+ .get("markers")
+ .and_then(Value::as_array)
+ .map(|a| a.iter().filter_map(Value::as_str).map(String::from).collect())
+ .unwrap_or_default(),
+ }
+ }
+
+ pub fn to_value(&self) -> Value {
+ json!({
+ "title": self.title,
+ "textChars": self.text_chars,
+ "href": self.href,
+ "markers": self.markers,
+ })
+ }
+}
+
+/// The main document's HTTP response (the last one for the main frame, so
+/// after redirects). `headers` names are lowercased.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct DocumentResponse {
+ pub url: String,
+ pub status: u16,
+ pub headers: Vec<(String, String)>,
+}
+
+impl DocumentResponse {
+ /// From a CDP `Network.Response` object.
+ pub fn from_cdp(response: &Value) -> Option<DocumentResponse> {
+ let status = response.get("status").and_then(Value::as_f64)?;
+ let headers = response
+ .get("headers")
+ .and_then(Value::as_object)
+ .map(|m| {
+ m.iter()
+ .map(|(k, v)| {
+ (
+ k.to_ascii_lowercase(),
+ v.as_str().map(String::from).unwrap_or_else(|| v.to_string()),
+ )
+ })
+ .collect()
+ })
+ .unwrap_or_default();
+ Some(DocumentResponse {
+ url: response.get("url").and_then(Value::as_str).unwrap_or("").to_string(),
+ status: status.max(0.0) as u16,
+ headers,
+ })
+ }
+
+ pub fn header(&self, name: &str) -> Option<&str> {
+ self.headers
+ .iter()
+ .find(|(k, _)| k == name)
+ .map(|(_, v)| v.as_str())
+ }
+
+ pub fn to_value(&self) -> Value {
+ let headers: serde_json::Map<String, Value> = self
+ .headers
+ .iter()
+ .map(|(k, v)| (k.clone(), Value::String(v.clone())))
+ .collect();
+ json!({ "url": self.url, "status": self.status, "headers": headers })
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BlockKind {
+ /// A bot challenge, captcha, or WAF block page.
+ Challenge,
+ /// The server answered with a 4xx/5xx status.
+ HttpError,
+}
+
+impl BlockKind {
+ pub fn as_str(self) -> &'static str {
+ match self {
+ BlockKind::Challenge => "challenge",
+ BlockKind::HttpError => "http-error",
+ }
+ }
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum PageValidity {
+ Ok,
+ Blocked {
+ kind: BlockKind,
+ /// Human-readable signals, in the order they were checked.
+ evidence: Vec<String>,
+ },
+}
+
+impl PageValidity {
+ pub fn is_blocked(&self) -> bool {
+ matches!(self, PageValidity::Blocked { .. })
+ }
+
+ pub fn to_value(&self) -> Value {
+ match self {
+ PageValidity::Ok => json!({ "status": "ok" }),
+ PageValidity::Blocked { kind, evidence } => {
+ json!({ "status": kind.as_str(), "evidence": evidence })
+ }
+ }
+ }
+
+ /// The error the CLI prints for a blocked page, or `None` when it is fine.
+ pub fn error_message(&self) -> Option<String> {
+ let PageValidity::Blocked { kind, evidence } = self else {
+ return None;
+ };
+ let signals = evidence.join(", ");
+ Some(match kind {
+ BlockKind::Challenge => format!(
+ "the page is a bot challenge, not the site ({signals}). Findings would describe the challenge page, so none are reported."
+ ),
+ BlockKind::HttpError => format!(
+ "the page returned an error ({signals}). Findings would describe the error page, so none are reported."
+ ),
+ })
+ }
+}
+
+/// Classify a loaded page. `response` is `None` when no main-document
+/// response was seen (a `file://` URL, or a same-document navigation).
+pub fn classify(response: Option<&DocumentResponse>, probe: &PageProbe) -> PageValidity {
+ let mut challenge: Vec<String> = Vec::new();
+ if let Some(r) = response {
+ if let Some(action) = r.header("x-amzn-waf-action") {
+ challenge.push(format!("x-amzn-waf-action: {action}"));
+ }
+ if let Some(v) = r.header("cf-mitigated") {
+ if v.eq_ignore_ascii_case("challenge") {
+ challenge.push("cf-mitigated: challenge".to_string());
+ }
+ }
+ }
+ if let Ok(final_url) = url::Url::parse(&probe.href) {
+ if let Some(host) = final_url.host_str() {
+ let host = host.to_ascii_lowercase();
+ if CHALLENGE_HOSTS
+ .iter()
+ .any(|h| host == *h || host.ends_with(&format!(".{h}")))
+ {
+ challenge.push(format!("challenge host {host}"));
+ }
+ }
+ }
+ let small = probe.text_chars <= SMALL_PAGE_CHARS;
+ if small {
+ let title = probe.title.trim().to_lowercase();
+ if !title.is_empty() && CHALLENGE_TITLE_PREFIXES.iter().any(|p| title.starts_with(p)) {
+ challenge.push(format!("title \"{}\"", probe.title.trim()));
+ }
+ for m in &probe.markers {
+ challenge.push(format!("marker {m}"));
+ }
+ }
+ let status = response.map(|r| r.status).unwrap_or(0);
+ if !challenge.is_empty() {
+ if status >= 400 {
+ challenge.insert(0, format!("HTTP {status}"));
+ }
+ return PageValidity::Blocked {
+ kind: BlockKind::Challenge,
+ evidence: challenge,
+ };
+ }
+ if status >= 400 {
+ return PageValidity::Blocked {
+ kind: BlockKind::HttpError,
+ evidence: vec![format!("HTTP {status}")],
+ };
+ }
+ PageValidity::Ok
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn resp(status: u16, headers: &[(&str, &str)]) -> DocumentResponse {
+ DocumentResponse {
+ url: "https://example.com/".into(),
+ status,
+ headers: headers.iter().map(|(k, v)| (k.to_string(), v.to_string())).collect(),
+ }
+ }
+
+ fn probe(title: &str, text_chars: u64, markers: &[&str]) -> PageProbe {
+ PageProbe {
+ title: title.into(),
+ text_chars,
+ href: "https://example.com/".into(),
+ markers: markers.iter().map(|m| m.to_string()).collect(),
+ }
+ }
+
+ #[test]
+ fn aws_waf_captcha_is_a_challenge() {
+ // siemens.com, 2026-09-11: CloudFront answered 405 with a captcha page.
+ let v = classify(
+ Some(&resp(405, &[("x-amzn-waf-action", "captcha")])),
+ &probe("Human Verification", 120, &[]),
+ );
+ assert_eq!(
+ v,
+ PageValidity::Blocked {
+ kind: BlockKind::Challenge,
+ evidence: vec![
+ "HTTP 405".into(),
+ "x-amzn-waf-action: captcha".into(),
+ "title \"Human Verification\"".into(),
+ ],
+ }
+ );
+ assert!(v.error_message().unwrap().starts_with("the page is a bot challenge"));
+ }
+
+ #[test]
+ fn cloudflare_interstitial_title_on_a_small_page() {
+ let v = classify(Some(&resp(403, &[])), &probe("Just a moment...", 80, &[]));
+ assert!(matches!(v, PageValidity::Blocked { kind: BlockKind::Challenge, .. }));
+ }
+
+ #[test]
+ fn cf_mitigated_header_alone_is_enough() {
+ let v = classify(
+ Some(&resp(200, &[("cf-mitigated", "challenge")])),
+ &probe("Example", 20000, &[]),
+ );
+ assert!(matches!(v, PageValidity::Blocked { kind: BlockKind::Challenge, .. }));
+ }
+
+ #[test]
+ fn challenge_title_on_a_content_page_is_content() {
+ let v = classify(Some(&resp(200, &[])), &probe("Access denied: a novel", 40000, &[]));
+ assert_eq!(v, PageValidity::Ok);
+ }
+
+ #[test]
+ fn captcha_marker_on_a_content_page_is_content() {
+ let v = classify(Some(&resp(200, &[])), &probe("Sign up", 9000, &["slider-captcha"]));
+ assert_eq!(v, PageValidity::Ok);
+ }
+
+ #[test]
+ fn marker_on_a_small_page_is_a_challenge() {
+ let v = classify(Some(&resp(200, &[])), &probe("", 40, &["datadome-captcha"]));
+ assert_eq!(
+ v,
+ PageValidity::Blocked {
+ kind: BlockKind::Challenge,
+ evidence: vec!["marker datadome-captcha".into()],
+ }
+ );
+ }
+
+ #[test]
+ fn radware_redirect_host_is_a_challenge() {
+ // yad2.co.il, 2026-09-11: a 302 to validate.perfdrive.com, which answers 200.
+ let mut p = probe("Radware Bot Manager Block", 300, &[]);
+ p.href = "https://validate.perfdrive.com/ccb4768f/?ssa=1".into();
+ let v = classify(Some(&resp(200, &[])), &p);
+ assert_eq!(
+ v,
+ PageValidity::Blocked {
+ kind: BlockKind::Challenge,
+ evidence: vec![
+ "challenge host validate.perfdrive.com".into(),
+ "title \"Radware Bot Manager Block\"".into(),
+ ],
+ }
+ );
+ }
+
+ #[test]
+ fn http_error_without_challenge_signals() {
+ let v = classify(Some(&resp(404, &[])), &probe("Page not found", 400, &[]));
+ assert_eq!(
+ v,
+ PageValidity::Blocked {
+ kind: BlockKind::HttpError,
+ evidence: vec!["HTTP 404".into()],
+ }
+ );
+ assert!(v.error_message().unwrap().contains("HTTP 404"));
+ }
+
+ #[test]
+ fn ordinary_pages_and_file_urls_pass() {
+ assert_eq!(classify(Some(&resp(200, &[])), &probe("Stripe", 12000, &[])), PageValidity::Ok);
+ assert_eq!(classify(None, &probe("fixture", 10, &[])), PageValidity::Ok);
+ }
+
+ #[test]
+ fn response_from_cdp_lowercases_headers() {
+ let r = DocumentResponse::from_cdp(&json!({
+ "url": "https://example.com/",
+ "status": 405,
+ "headers": { "X-Amzn-Waf-Action": "captcha", "Server": "CloudFront" },
+ }))
+ .unwrap();
+ assert_eq!(r.status, 405);
+ assert_eq!(r.header("x-amzn-waf-action"), Some("captcha"));
+ }
+
+ #[test]
+ fn probe_js_embeds_every_marker() {
+ let js = probe_js();
+ for (selector, label) in CHALLENGE_MARKERS {
+ assert!(js.contains(label));
+ assert!(js.contains(&selector.replace('\'', "'")));
+ }
+ }
+}
diff --git a/crates/browser/tests/evidence.rs b/crates/browser/tests/evidence.rs
new file mode 100644
index 000000000..08ba2d9cb
--- /dev/null
+++ b/crates/browser/tests/evidence.rs
@@ -0,0 +1,204 @@
+//! The validity gate, evidence scans, and replay, against an installed
+//! browser. Skips cleanly when there is none.
+//!
+//! - A bot challenge or an HTTP error page is refused with an error by the
+//! CLI path and recorded (no findings, a screenshot) by the evidence path.
+//! - An evidence scan reports the same findings as the CLI path, each named
+//! by its element.
+//! - Replaying the recorded captures with no browser reproduces the
+//! deterministic passes' findings exactly, with no unanswered hit tests.
+
+use std::collections::HashMap;
+use std::io::{Read, Write};
+use std::net::{TcpListener, TcpStream};
+use std::path::{Path, PathBuf};
+
+use impeccable_browser::{
+ detect_url_evidence, origin, replay_url_scan, BrowserEngine, EvidenceRequest,
+};
+use impeccable_detect::engines::{ScanOptions, UrlEngine};
+
+const CHALLENGE: &str = "<!doctype html><html><head><title>Human Verification</title></head><body><div id=\"captcha-container\">Please verify you are human.</div></body></html>";
+const NOT_FOUND: &str = "<!doctype html><html><head><title>Not found</title></head><body><h1>Nothing here</h1></body></html>";
+
+/// Fixtures that exercise the scan pass, hit tests (text-occlusion), and the
+/// post-reveal content-hidden measure.
+const REPLAY_FIXTURES: &[&str] = &[
+ "should-flag.html",
+ "text-occlusion.html",
+ "reveal-working.html",
+ "typography-should-flag.html",
+ "quality.html",
+ "layout.html",
+];
+
+fn fixtures_dir() -> PathBuf {
+ Path::new(env!("CARGO_MANIFEST_DIR")).join("../../tests/fixtures/antipatterns")
+}
+
+fn serve() -> u16 {
+ let listener = TcpListener::bind("127.0.0.1:0").expect("bind");
+ let port = listener.local_addr().unwrap().port();
+ std::thread::spawn(move || {
+ for stream in listener.incoming().flatten() {
+ std::thread::spawn(move || handle(stream));
+ }
+ });
+ port
+}
+
+fn respond(stream: &mut TcpStream, status: &str, extra_headers: &str, content_type: &str, body: &[u8]) {
+ let head = format!(
+ "HTTP/1.0 {status}\r\nContent-Type: {content_type}\r\nContent-Length: {}\r\n{extra_headers}Connection: close\r\n\r\n",
+ body.len()
+ );
+ let _ = stream.write_all(head.as_bytes());
+ let _ = stream.write_all(body);
+ let _ = stream.flush();
+}
+
+fn handle(mut stream: TcpStream) {
+ let mut buf = [0u8; 8192];
+ let n = stream.read(&mut buf).unwrap_or(0);
+ let request = String::from_utf8_lossy(&buf[..n]);
+ let path = request
+ .lines()
+ .next()
+ .and_then(|l| l.split_whitespace().nth(1))
+ .unwrap_or("/")
+ .split('?')
+ .next()
+ .unwrap_or("/")
+ .to_string();
+ match path.as_str() {
+ "/blocked" => respond(
+ &mut stream,
+ "405 Method Not Allowed",
+ "x-amzn-waf-action: captcha\r\n",
+ "text/html; charset=utf-8",
+ CHALLENGE.as_bytes(),
+ ),
+ "/missing" => respond(&mut stream, "404 Not Found", "", "text/html; charset=utf-8", NOT_FOUND.as_bytes()),
+ _ => {
+ let rel = path.trim_start_matches('/');
+ let file = fixtures_dir().join(rel);
+ match std::fs::read(&file) {
+ Ok(body) => {
+ let ct = if rel.ends_with(".css") { "text/css" } else { "text/html; charset=utf-8" };
+ respond(&mut stream, "200 OK", "", ct, &body)
+ }
+ Err(_) => respond(&mut stream, "404 Not Found", "", "text/plain", b"missing"),
+ }
+ }
+ }
+}
+
+fn engine() -> Option<BrowserEngine> {
+ let env: HashMap<String, String> = std::env::vars().collect();
+ if impeccable_browser::discovery::find_browser(&env).is_err() {
+ eprintln!("skip: no installed browser found");
+ return None;
+ }
+ Some(BrowserEngine::new(env))
+}
+
+#[test]
+fn blocked_pages_are_refused_by_the_cli_path_and_recorded_by_evidence() {
+ let Some(engine) = engine() else { return };
+ let port = serve();
+ let options = ScanOptions::default();
+
+ let blocked = format!("http://127.0.0.1:{port}/blocked");
+ let err = engine.detect_url(&blocked, &options).expect_err("challenge page must not scan");
+ assert!(err.message.contains("bot challenge"), "{}", err.message);
+ assert!(err.message.contains("HTTP 405"), "{}", err.message);
+ assert!(err.message.contains("x-amzn-waf-action: captcha"), "{}", err.message);
+
+ let missing = format!("http://127.0.0.1:{port}/missing");
+ let err = engine.detect_url(&missing, &options).expect_err("error page must not scan");
+ assert!(err.message.contains("HTTP 404"), "{}", err.message);
+
+ let mut browser = engine.launch().expect("launch");
+ let (findings, evidence) =
+ detect_url_evidence(&mut browser, &blocked, &options, "load", 100, &EvidenceRequest::default())
+ .expect("evidence scan of a blocked page is Ok");
+ browser.close();
+ assert!(findings.is_empty());
+ assert!(evidence.validity.as_ref().unwrap().is_blocked());
+ assert_eq!(evidence.response.as_ref().unwrap().status, 405);
+ assert!(evidence.scan_snapshot.is_none());
+ assert!(evidence.screenshot.is_some(), "{:?}", evidence.screenshot_error);
+}
+
+#[test]
+fn evidence_matches_the_cli_path_and_replay_matches_live() {
+ let Some(engine) = engine() else { return };
+ let port = serve();
+ let options = ScanOptions::default();
+ let mut browser = engine.launch().expect("launch");
+
+ for name in REPLAY_FIXTURES {
+ if !fixtures_dir().join(name).exists() {
+ eprintln!("skip fixture {name}: not present");
+ continue;
+ }
+ let url = format!("http://127.0.0.1:{port}/{name}");
+ let cli = engine.detect_url(&url, &options).expect("cli scan");
+ let (live, evidence) =
+ detect_url_evidence(&mut browser, &url, &options, "networkidle0", 0, &EvidenceRequest::default())
+ .expect("evidence scan");
+
+ let strip = |f: &impeccable_core::findings::Finding| {
+ (f.antipattern.clone(), f.snippet.clone())
+ };
+ // The visual-contrast pass samples pixels, so compare the passes that
+ // do not: everything but visual-contrast must match the CLI path.
+ let non_visual = |fs: &[impeccable_core::findings::Finding], origins: Option<&[&str]>| -> Vec<(String, String)> {
+ fs.iter()
+ .enumerate()
+ .filter(|(i, f)| match origins {
+ Some(o) => o[*i] != origin::VISUAL_CONTRAST,
+ None => f.antipattern != "low-contrast" || f.extras.get("selector").is_some(),
+ })
+ .map(|(_, f)| strip(f))
+ .collect()
+ };
+ assert_eq!(evidence.origins.len(), live.len());
+ let live_scan: Vec<(String, String)> = non_visual(&live, Some(&evidence.origins));
+ let cli_all: Vec<(String, String)> = cli.iter().map(strip).collect();
+ for item in &live_scan {
+ assert!(cli_all.contains(item), "{name}: evidence finding {item:?} missing from the CLI path");
+ }
+
+ let scan_findings = live.iter().zip(&evidence.origins).filter(|(_, o)| **o == origin::SCAN);
+ for (f, _) in scan_findings {
+ assert!(f.extras.get("selector").is_some(), "{name}: {} has no selector", f.antipattern);
+ }
+ assert!(evidence.screenshot.is_some(), "{name}: {:?}", evidence.screenshot_error);
+ if live.iter().any(|f| f.extras.get("selector").is_some()) {
+ assert!(!evidence.element_rects.is_empty(), "{name}: no element rects");
+ }
+
+ let replay = replay_url_scan(
+ &url,
+ evidence.scan_snapshot.as_deref().expect("scan snapshot"),
+ &evidence.scan_facts,
+ evidence
+ .reveal_snapshot
+ .as_deref()
+ .map(|s| (s, &evidence.reveal_facts)),
+ &options,
+ )
+ .expect("replay");
+ let replayable: Vec<&impeccable_core::findings::Finding> = live
+ .iter()
+ .zip(&evidence.origins)
+ .filter(|(_, o)| **o == origin::SCAN || **o == origin::CONTENT_HIDDEN)
+ .map(|(f, _)| f)
+ .collect();
+ let replayed: Vec<&impeccable_core::findings::Finding> = replay.findings.iter().collect();
+ assert_eq!(replayed, replayable, "{name}: replay differs from the live scan");
+ assert_eq!(replay.unanswered_hit_tests, 0, "{name}: unanswered hit tests");
+ }
+ browser.close();
+}
diff --git a/docs/CLI-CONTRACT.md b/docs/CLI-CONTRACT.md
index 7d1f89d76..68bd4f25c 100644
--- a/docs/CLI-CONTRACT.md
+++ b/docs/CLI-CONTRACT.md
@@ -193,7 +193,9 @@ whose browser setup or scan throws, a path `statSync` cannot reach
in a dir walk, and a per-file scan that throws
(`stderr> Error: cannot scan <target>: <message>`). A multi-URL scan whose
shared browser fails to launch prints its `Error:` once and skips every URL
-target.
+target. A URL whose loaded page is a bot challenge or an HTTP error page is
+also a failure to scan (see **Page validity gate** under URL scans): it
+reports no findings and prints `stderr> Error: the page is ...`.
**Output and exit codes**:
- `allFindings.length > 0`:
@@ -326,6 +328,9 @@ Optional keys added later by engines (appended after the above): `ignoreValue` (
- Visual contrast fallback (`runVisualContrastFallback`): browser-side `impeccableAnalyzeVisualContrast({maxCandidates, scrollOffscreen})` findings not already low-contrast on that selector; then candidates (from analyses or `impeccableCollectVisualContrastCandidates`) not resolved pass/fail → per candidate `captureVisualContrastCandidate(page, candidate, viewport)`.
- **Screenshot flow** (`screenshot-contrast.mjs`): clip sanitized (`x,y` floored ≥0; `width` ≤ viewport width (default 1600), `height` ≤ 320, both ≥1); `page.screenshot({encoding:'base64', clip, captureBeyondViewport:true})` before; inject `<style id="impeccable-visual-contrast-hide-style">[data-impeccable-visual-contrast-target]{color:transparent!important;-webkit-text-fill-color:transparent!important;text-shadow:none!important}[data-impeccable-visual-contrast-target][data-impeccable-bgclip-text="true"]{background-image:none!important}` and set attribute `data-impeccable-visual-contrast-target=impeccable-contrast-${Date.now()}-${rand}` (+ `data-impeccable-bgclip-text="true"` if `candidate.backgroundClipText`); screenshot after; remove attributes; in-page canvas diff: pixels with channel delta sum ≥10 are glyph pixels; ratio uses WCAG luminance of CSS text color (unless `preferRenderedForeground`) vs after-pixel; needs ≥8 ratios; p10 = `ratios[floor(0.10*n)]`; finding when `p10 < candidate.threshold`: `{id:'low-contrast', snippet:`pixel contrast ${p10.toFixed(1)}:1 median ${median.toFixed(1)}:1 (need ${threshold}:1) on ${reasons.slice(0,3).join(', ') || 'visual background'} "${text}"`}`. No screenshot files are written.
- Results mapped via `finding(id, url, snippet)` (file = the URL, line 0); `ignoreValue` set if present; `severity` overridden if the browser supplied one.
+- **Rust engine additions (not in the JS):**
+ - **Element identity.** A finding from the rule pass or the visual-contrast pass carries `selector` (after `ignoreValue`): the flagged group's generated selector (`body` / `html` for page-level groups), or the visual-contrast candidate's selector. `content-hidden-at-rest` and `script-error` findings have none.
+ - **Page validity gate.** After `goto` (and settle), before injecting anything, the engine classifies the page (`crates/browser/src/validity.rs`) from the main document's final CDP response and an in-page probe (title, visible text length, final URL, challenge-widget markers). Challenge: an `x-amzn-waf-action` header, `cf-mitigated: challenge`, a final URL on a challenge-only host (`perfdrive.com`, `captcha-delivery.com`), or, on a page with at most 3000 characters of visible text, a challenge title prefix ("Just a moment", "Attention Required! | Cloudflare", "Human Verification", "Access Denied", "Radware Bot Manager", "Captcha", ...) or a full-page widget marker (Cloudflare challenge form, PerimeterX, DataDome, Imperva, Akamai, AWS WAF, slider captchas). HTTP error: a final status >= 400 with no challenge signal. A blocked page throws `the page is a bot challenge, not the site (<signals>). Findings would describe the challenge page, so none are reported.` or `the page returned an error (HTTP <status>). Findings would describe the error page, so none are reported.`, which the CLI prints as `Error: ...` and counts as an operational failure (exit 1). A `file://` load has no response, so only the probe signals apply.
- `createBrowserDetector(options)`: shared browser, defaults `waitUntil:'load'`, `settleMs:100`, `viewport 1280x800`; `close()` closes only an owned browser.
- Tests: `tests/detect-url-launch.test.mjs`, `tests/detect-antipatterns-browser.test.mjs`.