use std::time::Duration;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use super::{
DebuggerCapture, DebuggerManager, DebuggerRecordingPhase, DebuggerSnapshot, now_ms, pixel_diff,
};
const FLOW_BINDING: &str = "__apoc_flow__";
const FLOW_POLL_MS: u64 = 50;
const FLOW_LISTENER_SOURCE: &str = r#"(() => {
if (window.__apoc_flow_installed__) return;
window.__apoc_flow_installed__ = true;
const esc = value => window.CSS && CSS.escape ? CSS.escape(value) : String(value).replace(/[^a-zA-Z0-9_-]/g, '\\$&');
const unique = selector => { try { return document.querySelectorAll(selector).length === 1; } catch (_) { return false; } };
const nth = el => {
const parts=[]; let cur=el;
while(cur && cur.nodeType===1 && cur!==document.documentElement) {
const tag=cur.tagName.toLowerCase();
if(cur===document.body){parts.unshift('body');break;}
let n=1,sib=cur; while((sib=sib.previousElementSibling)) if(sib.tagName===cur.tagName)n++;
parts.unshift(tag+':nth-of-type('+n+')'); cur=cur.parentElement;
}
return parts.join(' > ');
};
const locate = target => {
const el=target && target.nodeType===1 ? target : target && target.parentElement;
if(!el || !el.tagName) return {selector:null,fallbackPath:null};
const fallbackPath=nth(el);
if(el.id){const selector='#'+esc(el.id);if(unique(selector))return {selector,fallbackPath};}
const testId=el.getAttribute && el.getAttribute('data-testid');
if(testId){const selector='[data-testid="'+String(testId).replace(/"/g,'\\"')+'"]';if(unique(selector))return {selector,fallbackPath};}
if(el.classList && el.classList.length){const selector=el.tagName.toLowerCase()+Array.from(el.classList).map(value=>'.'+esc(value)).join('');if(unique(selector))return {selector,fallbackPath};}
return {selector:fallbackPath,fallbackPath};
};
const send = action => { try { window.__apoc_flow__(JSON.stringify(action)); } catch (_) {} };
addEventListener('click', event => { const found=locate(event.target); send({kind:'click',selector:found.selector,fallbackPath:found.fallbackPath}); }, true);
addEventListener('change', event => { const found=locate(event.target); send({kind:'input',selector:found.selector,fallbackPath:found.fallbackPath,value:event.target && 'value' in event.target ? String(event.target.value) : ''}); }, true);
addEventListener('keydown', event => { if(!['Enter','Tab','Escape','ArrowUp','ArrowDown','ArrowLeft','ArrowRight'].includes(event.key))return; const found=locate(event.target); send({kind:'keypress',selector:found.selector,fallbackPath:found.fallbackPath,value:event.key}); }, true);
let timer=null; addEventListener('scroll', () => { if(timer!==null)clearTimeout(timer); timer=setTimeout(()=>{timer=null;send({kind:'scroll',value:String(window.scrollY||0)});},250); }, true);
})()"#;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum DebuggerFlowPhase {
Recording,
Stopped,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct DebuggerFlow {
pub id: String,
pub session_id: String,
pub recording_id: String,
pub name: String,
pub url: String,
pub phase: DebuggerFlowPhase,
pub next_sequence: u64,
pub last_action_sequence: u64,
pub last_page_sequence: u64,
pub started_at: u64,
pub stopped_at: Option<u64>,
pub updated_at: u64,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct DebuggerFlowStep {
pub id: String,
pub flow_id: String,
pub sequence: u64,
pub at: u64,
pub kind: String,
pub selector: Option<String>,
pub fallback_path: Option<String>,
pub value: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct DebuggerFlowRunStep {
pub sequence: u64,
pub kind: String,
pub selector: Option<String>,
pub status: String,
pub capture: Option<DebuggerCapture>,
pub error: Option<String>,
pub console_errors: Vec<String>,
pub diff_percent: Option<f64>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct DebuggerFlowRun {
pub id: String,
pub flow_id: String,
pub session_id: String,
pub status: String,
pub steps_total: usize,
pub steps_passed: usize,
pub steps_failed: usize,
pub steps: Vec<DebuggerFlowRunStep>,
pub started_at: u64,
pub completed_at: u64,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct DebuggerFlowView {
pub flow: DebuggerFlow,
pub steps: Vec<DebuggerFlowStep>,
pub runs: Vec<DebuggerFlowRun>,
}
impl DebuggerManager {
pub async fn flow_record(
&self,
session_id: &str,
name: String,
url: Option<String>,
) -> Result<DebuggerFlow, String> {
if name.trim().is_empty() {
return Err("Flow name cannot be empty".to_string());
}
if self.store.active_debugger_flow(session_id)?.is_some() {
return Err(format!(
"Debugger session \"{session_id}\" already records a flow"
));
}
let recording = self
.store
.active_debugger_recording(session_id)?
.ok_or_else(|| format!("Debugger session \"{session_id}\" is not recording"))?;
self.install_flow_hooks(session_id).await?;
if let Some(url) = url.as_deref() {
self.browser_navigate(session_id, "url", Some(url), Duration::from_secs(30))
.await?;
}
let browser = self.browser_state(session_id).await?;
let url = browser
.url
.or(url)
.ok_or_else(|| "Browser flow has no start URL".to_string())?;
let at = now_ms();
let flow = DebuggerFlow {
id: uuid::Uuid::now_v7().to_string(),
session_id: session_id.to_string(),
recording_id: recording.id,
name,
url,
phase: DebuggerFlowPhase::Recording,
next_sequence: 0,
last_action_sequence: browser
.flow_actions
.last()
.map_or(0, |action| action.sequence),
last_page_sequence: browser.page_events.last().map_or(0, |event| event.id),
started_at: at,
stopped_at: None,
updated_at: at,
};
self.store.put_debugger_flow(&flow)?;
self.spawn_flow_worker(session_id).await;
Ok(flow)
}
pub async fn flow_stop(&self, session_id: &str) -> Result<DebuggerFlow, String> {
self.store
.active_debugger_flow(session_id)?
.ok_or_else(|| format!("Debugger session \"{session_id}\" has no active flow"))?;
self.stop_flow_worker(session_id).await;
self.drain_flow_actions(session_id).await?;
let mut flow = self
.store
.active_debugger_flow(session_id)?
.ok_or_else(|| "Active flow disappeared during stop".to_string())?;
let at = now_ms();
flow.phase = DebuggerFlowPhase::Stopped;
flow.stopped_at = Some(at);
flow.updated_at = at;
self.store.put_debugger_flow(&flow)?;
Ok(flow)
}
pub fn flow_list(&self) -> Result<Vec<DebuggerFlow>, String> {
self.store.debugger_flows()
}
pub fn flow_show(&self, session_id: &str, name: &str) -> Result<DebuggerFlowView, String> {
let flow = self
.store
.debugger_flow_by_name(session_id, name)?
.ok_or_else(|| format!("Debugger flow \"{name}\" not found"))?;
Ok(DebuggerFlowView {
steps: self.store.debugger_flow_steps(&flow.id)?,
runs: self.store.debugger_flow_runs(&flow.id)?,
flow,
})
}
pub async fn flow_run(
&self,
session_id: &str,
name: &str,
step_timeout: Duration,
) -> Result<DebuggerFlowRun, String> {
if self.store.active_debugger_flow(session_id)?.is_some() {
return Err("Stop the active flow recording before replay".to_string());
}
let recording = self
.store
.active_debugger_recording(session_id)?
.ok_or_else(|| format!("Debugger session \"{session_id}\" is not recording"))?;
if recording.phase != DebuggerRecordingPhase::Running {
return Err("Browser recording is not running".to_string());
}
let flow = self
.store
.debugger_flow_by_name(session_id, name)?
.ok_or_else(|| format!("Debugger flow \"{name}\" not found"))?;
let steps = self.store.debugger_flow_steps(&flow.id)?;
if steps.is_empty() {
return Err(format!("Debugger flow \"{name}\" has no steps"));
}
self.browser_navigate(session_id, "url", Some(&flow.url), Duration::from_secs(30))
.await?;
let previous = self.store.debugger_flow_runs(&flow.id)?.pop();
let started_at = now_ms();
let mut results = Vec::with_capacity(steps.len());
let mut failed = false;
for step in &steps {
if failed {
results.push(DebuggerFlowRunStep {
sequence: step.sequence,
kind: step.kind.clone(),
selector: step.selector.clone(),
status: "skipped".to_string(),
capture: None,
error: None,
console_errors: Vec::new(),
diff_percent: None,
});
continue;
}
let before = self.session(session_id).await?.state.borrow().clone();
let action = self.execute_flow_step(session_id, step, step_timeout).await;
tokio::time::sleep(Duration::from_millis(100)).await;
let capture = self
.recording_capture(session_id, format!("flow:{}:{}", flow.name, step.sequence))
.await
.ok();
let console_errors = capture
.as_ref()
.map(|capture| new_console_errors(&before, capture))
.unwrap_or_default();
let mut error = action.err();
if error.is_none() && !console_errors.is_empty() {
error = Some(format!(
"Step produced {} new console error(s)",
console_errors.len()
));
}
let status = if error.is_some() { "failed" } else { "passed" };
failed = error.is_some();
let diff_percent = previous
.as_ref()
.and_then(|run| {
run.steps
.iter()
.find(|prior| prior.sequence == step.sequence)
})
.and_then(|prior| prior.capture.as_ref())
.zip(capture.as_ref())
.and_then(|(prior, current)| {
pixel_diff(
&prior.screenshot.artifact.path,
¤t.screenshot.artifact.path,
)
.ok()
.map(|(pixels, total, _)| {
if total == 0 {
0.0
} else {
pixels as f64 / total as f64 * 100.0
}
})
});
results.push(DebuggerFlowRunStep {
sequence: step.sequence,
kind: step.kind.clone(),
selector: step.selector.clone(),
status: status.to_string(),
capture,
error,
console_errors,
diff_percent,
});
}
let completed_at = now_ms();
let steps_passed = results
.iter()
.filter(|step| step.status == "passed")
.count();
let steps_failed = results
.iter()
.filter(|step| step.status == "failed")
.count();
let run = DebuggerFlowRun {
id: uuid::Uuid::now_v7().to_string(),
flow_id: flow.id,
session_id: session_id.to_string(),
status: if steps_failed == 0 {
"passed"
} else {
"failed"
}
.to_string(),
steps_total: results.len(),
steps_passed,
steps_failed,
steps: results,
started_at,
completed_at,
};
self.store.put_debugger_flow_run(&run)?;
Ok(run)
}
pub(super) async fn resume_flow_worker(&self, session_id: &str) {
let Ok(Some(mut flow)) = self.store.active_debugger_flow(session_id) else {
return;
};
if self.install_flow_hooks(session_id).await.is_err() {
return;
}
if let Ok(browser) = self.browser_state(session_id).await {
flow.last_action_sequence = 0;
flow.last_page_sequence = browser.page_events.last().map_or(0, |event| event.id);
flow.updated_at = now_ms();
let _ = self.store.put_debugger_flow(&flow);
}
self.spawn_flow_worker(session_id).await;
}
async fn install_flow_hooks(&self, session_id: &str) -> Result<(), String> {
let session = self.session(session_id).await?;
let _ = session
.send("Runtime.addBinding", json!({"name":FLOW_BINDING}))
.await;
session
.send(
"Page.addScriptToEvaluateOnNewDocument",
json!({"source":FLOW_LISTENER_SOURCE}),
)
.await?;
session
.send(
"Runtime.evaluate",
json!({"expression":FLOW_LISTENER_SOURCE,"returnByValue":true}),
)
.await?;
Ok(())
}
async fn spawn_flow_worker(&self, session_id: &str) {
self.stop_flow_worker(session_id).await;
let manager = self.clone();
let session_id = session_id.to_string();
let task_session = session_id.clone();
let task = tokio::spawn(async move {
loop {
if manager
.store
.active_debugger_flow(&task_session)
.ok()
.flatten()
.is_none()
{
break;
}
let _ = manager.drain_flow_actions(&task_session).await;
tokio::time::sleep(Duration::from_millis(FLOW_POLL_MS)).await;
}
});
self.flow_tasks.lock().await.insert(session_id, task);
}
async fn stop_flow_worker(&self, session_id: &str) {
if let Some(task) = self.flow_tasks.lock().await.remove(session_id) {
task.abort();
}
}
async fn drain_flow_actions(&self, session_id: &str) -> Result<(), String> {
let Some(mut flow) = self.store.active_debugger_flow(session_id)? else {
return Ok(());
};
let browser = self.browser_state(session_id).await?;
let mut pending = browser
.flow_actions
.iter()
.filter(|action| action.sequence > flow.last_action_sequence)
.map(|action| DebuggerFlowStep {
id: uuid::Uuid::now_v7().to_string(),
flow_id: flow.id.clone(),
sequence: 0,
at: action.at,
kind: action.kind.clone(),
selector: action.selector.clone(),
fallback_path: action.fallback_path.clone(),
value: action.value.clone(),
})
.collect::<Vec<_>>();
pending.extend(
browser
.page_events
.iter()
.filter(|event| {
event.id > flow.last_page_sequence && event.name == "frameNavigated"
})
.map(|event| DebuggerFlowStep {
id: uuid::Uuid::now_v7().to_string(),
flow_id: flow.id.clone(),
sequence: 0,
at: if event.at > 0.0 {
event.at as u64
} else {
now_ms()
},
kind: "nav".to_string(),
selector: None,
fallback_path: None,
value: event.url.clone(),
}),
);
pending.sort_by(|left, right| left.at.cmp(&right.at).then_with(|| left.id.cmp(&right.id)));
for mut step in pending {
step.sequence = flow.next_sequence;
flow.next_sequence += 1;
self.store.put_debugger_flow_step(&step)?;
}
flow.last_action_sequence = browser
.flow_actions
.last()
.map_or(flow.last_action_sequence, |action| action.sequence);
flow.last_page_sequence = browser
.page_events
.last()
.map_or(flow.last_page_sequence, |event| event.id);
flow.updated_at = now_ms();
self.store.put_debugger_flow(&flow)
}
async fn execute_flow_step(
&self,
session_id: &str,
step: &DebuggerFlowStep,
timeout: Duration,
) -> Result<(), String> {
match step.kind.as_str() {
"click" | "input" | "keypress" => {
let selector = self
.wait_for_actionable(
session_id,
step.selector.as_deref(),
step.fallback_path.as_deref(),
timeout,
)
.await?;
match step.kind.as_str() {
"click" => {
self.browser_click(session_id, &selector).await?;
}
"input" => {
let session = self.session(session_id).await?;
session
.send(
"Runtime.evaluate",
json!({
"expression":format!("document.querySelector({}).value=''", serde_json::to_string(&selector).unwrap()),
"returnByValue":true
}),
)
.await?;
self.browser_type(
session_id,
&selector,
step.value.as_deref().unwrap_or_default(),
)
.await?;
}
"keypress" => {
let session = self.session(session_id).await?;
session
.send(
"Runtime.evaluate",
json!({"expression":format!("document.querySelector({}).focus()", serde_json::to_string(&selector).unwrap())}),
)
.await?;
let value = step.value.as_deref().unwrap_or_default();
session
.send(
"Input.dispatchKeyEvent",
json!({"type":"keyDown","key":value,"code":value,"text":key_text(value)}),
)
.await?;
session
.send(
"Input.dispatchKeyEvent",
json!({"type":"keyUp","key":value,"code":value}),
)
.await?;
}
_ => unreachable!(),
}
Ok(())
}
"scroll" => {
let y = step
.value
.as_deref()
.and_then(|value| value.parse::<f64>().ok())
.unwrap_or(0.0);
self.session(session_id)
.await?
.send(
"Runtime.evaluate",
json!({"expression":format!("window.scrollTo(0,{y})")}),
)
.await?;
Ok(())
}
"nav" => {
let url = step
.value
.as_deref()
.ok_or_else(|| "Navigation flow step has no URL".to_string())?;
self.browser_navigate(session_id, "url", Some(url), Duration::from_secs(30))
.await?;
Ok(())
}
other => Err(format!("Unknown flow step kind \"{other}\"")),
}
}
async fn wait_for_actionable(
&self,
session_id: &str,
selector: Option<&str>,
fallback: Option<&str>,
timeout: Duration,
) -> Result<String, String> {
let candidates = [selector, fallback]
.into_iter()
.flatten()
.filter(|value| !value.is_empty())
.collect::<Vec<_>>();
if candidates.is_empty() {
return Err("Flow step has no selector".to_string());
}
let session = self.session(session_id).await?;
let started = tokio::time::Instant::now();
loop {
let result = session
.send(
"Runtime.evaluate",
json!({
"expression":actionable_expression(&candidates),
"returnByValue":true
}),
)
.await?;
let value = result.pointer("/result/value").unwrap_or(&Value::Null);
if value.get("ready").and_then(Value::as_bool) == Some(true) {
return value
.get("selector")
.and_then(Value::as_str)
.map(ToString::to_string)
.ok_or_else(|| "Readiness returned no selector".to_string());
}
let last_reason = value
.get("reason")
.and_then(Value::as_str)
.unwrap_or("invalid readiness result")
.to_string();
if started.elapsed() >= timeout {
return Err(format!(
"Readiness timeout: {} not actionable ({last_reason})",
candidates.join(" or ")
));
}
tokio::time::sleep(Duration::from_millis(100)).await;
}
}
}
fn actionable_expression(candidates: &[&str]) -> String {
format!(
r#"(() => {{
for (const selector of {}) {{
let el=null; try {{ el=document.querySelector(selector); }} catch (_) {{}}
if(!el) continue;
const rect=el.getBoundingClientRect();
if(!rect.width||!rect.height) return {{ready:false,selector,reason:'zero-size'}};
const x=rect.left+rect.width/2,y=rect.top+rect.height/2,hit=document.elementFromPoint(x,y);
if(!hit) return {{ready:false,selector,reason:'not hit-testable'}};
if(!(hit===el||el.contains(hit)||hit.contains(el))) return {{ready:false,selector,reason:'covered'}};
return {{ready:true,selector,reason:'ready'}};
}}
return {{ready:false,selector:null,reason:'not found'}};
}})()"#,
serde_json::to_string(candidates).unwrap()
)
}
fn key_text(value: &str) -> Option<&str> {
match value {
"Enter" => Some("\r"),
"Tab" => Some("\t"),
"Escape" | "ArrowUp" | "ArrowDown" | "ArrowLeft" | "ArrowRight" => None,
value => Some(value),
}
}
fn new_console_errors(before: &DebuggerSnapshot, after: &DebuggerCapture) -> Vec<String> {
let before_console = before
.console
.iter()
.map(|entry| (entry.id, entry.text.as_str()))
.collect::<Vec<_>>();
let before_exceptions = before
.exceptions
.iter()
.map(|entry| (entry.id, entry.text.as_str()))
.collect::<Vec<_>>();
let mut errors = after
.state
.console
.iter()
.filter(|entry| entry.kind == "error" || entry.kind == "assert")
.filter(|entry| !before_console.contains(&(entry.id, entry.text.as_str())))
.map(|entry| entry.text.clone())
.collect::<Vec<_>>();
errors.extend(
after
.state
.exceptions
.iter()
.filter(|entry| !before_exceptions.contains(&(entry.id, entry.text.as_str())))
.map(|entry| entry.text.clone()),
);
errors
}