flowproof 0.2.4__tar.gz → 0.2.5__tar.gz

{flowproof-0.2.4 → flowproof-0.2.5}/Cargo.lock

@@ -722,7 +722,7 @@ dependencies = [
 
 [[package]]
 name = "flowproof-adapters"
-version = "0.2.4"
+version = "0.2.5"
 dependencies = [
  "anyhow",
  "flowproof-driver",
@@ -738,7 +738,7 @@ dependencies = [
 
 [[package]]
 name = "flowproof-agent"
-version = "0.2.4"
+version = "0.2.5"
 dependencies = [
  "chrono",
  "flowproof-driver",
@@ -753,7 +753,7 @@ dependencies = [
 
 [[package]]
 name = "flowproof-cli"
-version = "0.2.4"
+version = "0.2.5"
 dependencies = [
  "ab_glyph",
  "clap",
@@ -771,7 +771,7 @@ dependencies = [
 
 [[package]]
 name = "flowproof-driver"
-version = "0.2.4"
+version = "0.2.5"
 dependencies = [
  "image",
  "postgres",
@@ -785,7 +785,7 @@ dependencies = [
 
 [[package]]
 name = "flowproof-python"
-version = "0.2.4"
+version = "0.2.5"
 dependencies = [
  "flowproof-agent",
  "flowproof-cli",
@@ -797,7 +797,7 @@ dependencies = [
 
 [[package]]
 name = "flowproof-replay"
-version = "0.2.4"
+version = "0.2.5"
 dependencies = [
  "chrono",
  "flowproof-agent",
@@ -811,7 +811,7 @@ dependencies = [
 
 [[package]]
 name = "flowproof-trace"
-version = "0.2.4"
+version = "0.2.5"
 dependencies = [
  "jsonschema",
  "serde",

{flowproof-0.2.4 → flowproof-0.2.5}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/flowproof-driver", "crates/flowproof-trace", "crates/flowproof-replay", "crates/flowproof-agent", "crates/flowproof-adapters", "crates/flowproof-cli", "crates/flowproof-python"]
 
 [workspace.package]
-version = "0.2.4"
+version = "0.2.5"
 edition = "2021"
 license = "Apache-2.0"
 repository = "https://github.com/automators-com/flowproof"

{flowproof-0.2.4 → flowproof-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowproof
-Version: 0.2.4
+Version: 0.2.5
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3

{flowproof-0.2.4 → flowproof-0.2.5}/crates/flowproof-adapters/src/web.rs

@@ -33,12 +33,50 @@ fn web_err(context: &str, err: impl std::fmt::Display) -> DriverError {
     }
 }
 
+/// How long the CDP transport may sit without a BROWSER-level event before
+/// headless_chrome reaps its listener thread. Its default is 30 seconds,
+/// which is a live grenade for real test flows:
+///
+/// 1. a flow spends 30+ seconds doing page-level work (typing, polling an
+///    auto-waiting assertion) without producing a single browser-level
+///    event, so the listener thread times out and exits;
+/// 2. the next navigation fires `TargetInfoChanged` - a browser-level
+///    event - and the transport cannot deliver it to the receiver that
+///    just went away;
+/// 3. it treats that undeliverable event as fatal, shuts the whole message
+///    loop down, and every later call fails with "Unable to make method
+///    calls because underlying connection is closed", permanently.
+///
+/// That is the entire mechanism behind the round-3 field blocker: EVERY
+/// flow that logged in recorded fine and then failed to replay, because
+/// the login redirect is exactly a post-idle navigation. Silence is not
+/// evidence of a dead browser - a browser that actually dies closes the
+/// socket, which surfaces immediately and through a different path.
+///
+/// Choosing the value is a genuine trade-off, because headless_chrome
+/// OVERLOADS this one knob across three jobs with opposite needs:
+///
+/// - `Browser`'s event-listener reap and the transport's idle reap want it
+///   LONG (that is the bug above);
+/// - `Transport::call_method` uses it as the bound on waiting for a call's
+///   RESPONSE, which wants it SHORT: a response that never arrives blocks
+///   for exactly this long. Setting it to "effectively never" turned a
+///   failing CI job into one that hung for over three hours.
+///
+/// So: comfortably longer than any real gap between browser-level events
+/// (the field flows idled 30-90 s; `Wait until` defaults to a 60 s bound),
+/// and short enough that a lost response fails visibly instead of hanging.
+/// A flow that deliberately waits longer than this in one step without
+/// touching the browser is the case to revisit if it ever shows up.
+const BROWSER_IDLE_TIMEOUT: Duration = Duration::from_secs(300);
+
 /// Launch a fresh headless Chromium (`CHROME` env var overrides the
 /// binary), optionally with extra command-line flags.
 fn launch_browser(extra_args: &[String]) -> Result<Browser, AdapterError> {
     let os_args: Vec<std::ffi::OsString> = extra_args.iter().map(Into::into).collect();
     let mut options = LaunchOptions::default_builder();
     options.headless(true).sandbox(false);
+    options.idle_browser_timeout(BROWSER_IDLE_TIMEOUT);
     options.args(os_args.iter().map(AsRef::as_ref).collect());
     if let Ok(path) = std::env::var("CHROME") {
         options.path(Some(path.into()));
@@ -677,6 +715,17 @@ impl AppDriver for WebAppDriver {
         Ok(Some(flowproof_driver::DebugBundle { dom_html, console }))
     }
 
+    fn current_url(&mut self) -> Result<String, DriverError> {
+        let value = self
+            .tab()?
+            .evaluate("window.location.href", false)
+            .map_err(|e| web_err("reading page url", e))?;
+        Ok(value
+            .value
+            .and_then(|v| v.as_str().map(str::to_string))
+            .unwrap_or_default())
+    }
+
     fn surface_text(&mut self) -> Result<String, DriverError> {
         // Visible text PLUS the accessible names of visible elements:
         // icon-only buttons (a command palette, an account menu) exist on
@@ -774,6 +823,15 @@ impl AppDriver for WebAppDriver {
         let locator = Self::locator(selector)?;
         let value =
             self.with_element(&locator, &format!("hit-testing [{selector}]"), |element| {
+                // Scroll first, exactly as the click itself will: headless
+                // chrome's `Element::click` begins with `scroll_into_view`,
+                // so hit-testing before scrolling asks about a position the
+                // click will never use. An element below the fold then reads
+                // as "obscured" - `elementFromPoint` outside the viewport
+                // returns null - and the gate blocks a click that would have
+                // worked. A whole settings form under the fold was
+                // untestable this way (field report, round 3).
+                element.scroll_into_view()?;
                 // Playwright's obscured check: does elementFromPoint at the
                 // element's center resolve to it (or a relative)? A toast or
                 // modal backdrop on top makes the click land elsewhere.

{flowproof-0.2.4 → flowproof-0.2.5}/crates/flowproof-agent/src/recorder.rs

@@ -334,6 +334,8 @@ fn step_for(id: usize, intent: &str, app: &str, action: &ResolvedAction) -> Step
                 TextMatch::NumericEquals => {
                     serde_json::json!({ "value_equals": expected, "normalize": "numeric" })
                 }
+                TextMatch::UrlEquals => serde_json::json!({ "url_equals": expected }),
+                TextMatch::UrlContains => serde_json::json!({ "url_contains": expected }),
             };
             expect["timeout_ms"] = serde_json::json!(timeout_ms);
             let selectors = selectors_for(app, target, None);
@@ -922,6 +924,10 @@ fn assert_holds(actual: &str, expected: &str, matcher: TextMatch) -> bool {
             (flowproof_driver::numeric_value(actual), expected.parse::<f64>()),
             (Some(a), Ok(e)) if a == e
         ),
+        // Shared with replay so record and replay cannot drift: a URL
+        // assertion that holds while recording must hold when replayed.
+        TextMatch::UrlEquals => flowproof_driver::url_matches(expected, true, actual),
+        TextMatch::UrlContains => flowproof_driver::url_matches(expected, false, actual),
     }
 }
 
@@ -1254,13 +1260,18 @@ pub fn record_with_reuse<D: AppDriver, C: ModelClient>(
                     let wanted = flowproof_trace::secret::resolve_refs(expected)?;
                     let deadline = std::time::Instant::now() + Duration::from_millis(*timeout_ms);
                     loop {
-                        let actual = if selector.is_none() {
-                            Some(driver.surface_text()?)
-                        } else if driver.element_exists(targeted())? {
-                            Some(driver.read_text(targeted())?)
-                        } else {
-                            None
-                        };
+                        let actual =
+                            if matches!(matcher, TextMatch::UrlEquals | TextMatch::UrlContains) {
+                                // The URL is a different reading of the surface,
+                                // not a different target: same poll, same bound.
+                                Some(driver.current_url()?)
+                            } else if selector.is_none() {
+                                Some(driver.surface_text()?)
+                            } else if driver.element_exists(targeted())? {
+                                Some(driver.read_text(targeted())?)
+                            } else {
+                                None
+                            };
                         if let Some(actual) = &actual {
                             if assert_holds(actual, &wanted, *matcher) {
                                 break;

{flowproof-0.2.4 → flowproof-0.2.5}/crates/flowproof-agent/src/rules.rs

@@ -164,6 +164,12 @@ pub enum TextMatch {
     Equals,
     /// Compare the trailing numeric value instead of raw text.
     NumericEquals,
+    /// The surface's URL equals the expectation - `page url is /signin`.
+    /// See `url_matches` in flowproof-replay for what "equals" means for a
+    /// path, a path with a query, and a whole URL.
+    UrlEquals,
+    /// The surface's URL contains the expectation - `page url contains x`.
+    UrlContains,
 }
 
 /// Default auto-wait for assertions (Playwright's expect default).
@@ -451,6 +457,35 @@ mod assertions {
             .unwrap_or(std::borrow::Cow::Borrowed(trimmed));
         let trimmed = trimmed.as_ref();
 
+        // `page url is <expected>` / `page url contains <text>`. Checked
+        // BEFORE `page shows`, and both auto-wait like every other
+        // assertion: an SPA redirect lands asynchronously, so a
+        // non-waiting URL assert would be the grammar's only racy form.
+        if let Some(rest) = strip_prefix_ci(trimmed, "page url is ") {
+            let expected = rest.trim();
+            if expected.is_empty() {
+                return Err(unresolvable(trimmed, "no expected url"));
+            }
+            return Ok(vec![ResolvedAction::AssertText {
+                target: Target::Surface,
+                expected: expected.to_string(),
+                matcher: TextMatch::UrlEquals,
+                timeout_ms,
+            }]);
+        }
+        if let Some(rest) = strip_prefix_ci(trimmed, "page url contains ") {
+            let expected = rest.trim();
+            if expected.is_empty() {
+                return Err(unresolvable(trimmed, "no expected url"));
+            }
+            return Ok(vec![ResolvedAction::AssertText {
+                target: Target::Surface,
+                expected: expected.to_string(),
+                matcher: TextMatch::UrlContains,
+                timeout_ms,
+            }]);
+        }
+
         if let Some(rest) = strip_prefix_ci(trimmed, "page shows ") {
             let (expected, count) = split_count(rest.trim());
             if expected.is_empty() {
@@ -563,7 +598,8 @@ mod assertions {
 
         Err(unresolvable(
             trimmed,
-            "expected '[the ]page shows <text>[ N times]', '[the ]page does not show \
+            "expected '[the ]page shows <text>[ N times]', '[the ]page url is|contains \
+             <url>', '[the ]page does not show \
              <text>', 'the \"<label>\" field contains <text>', 'the \"<target>\" shows \
              <text>', 'the \"<target>\" is [not] visible', or 'the \"<target>\" is \
              enabled|disabled' (see docs/authoring.md for the full grammar)",

{flowproof-0.2.4 → flowproof-0.2.5}/crates/flowproof-cli/src/lib.rs

@@ -379,17 +379,45 @@ fn apply_env_from(manifest: &flowproof_agent::SuiteManifest, dir: &Path) -> Resu
     let Some(command) = &manifest.env_from else {
         return Ok(());
     };
-    let output = std::process::Command::new("sh")
-        .arg("-c")
-        .arg(command)
-        .current_dir(dir)
+    // The data command SEES the suite's `env:`. Minting test data almost
+    // always needs the suite's base URL and credentials, and before this
+    // the command ran with none of them: a mint script reading $API_BASE
+    // got an empty string and failed closed downstream, which cost real
+    // diagnosis time in the field.
+    //
+    // Two orderings are easy to conflate, and only the second changes:
+    //   1. which value wins for `${VAR}` at flow time - UNCHANGED, still
+    //      process env < env_from output < `env:`;
+    //   2. what the env_from CHILD PROCESS sees - now `env:` too.
+    // Entries are resolved against the ambient process environment only,
+    // and one that does not resolve yet is skipped rather than fatal: it
+    // may reference this very command's output, and it gets its turn when
+    // `env:` is applied afterwards.
+    let mut child = std::process::Command::new("sh");
+    child.arg("-c").arg(command).current_dir(dir);
+    for (key, value) in &manifest.env {
+        if let Ok(resolved) = flowproof_trace::secret::resolve_refs(value) {
+            child.env(key, resolved);
+        }
+    }
+    let output = child
         .output()
         .map_err(|e| format!("env_from command failed to start: {e}"))?;
+    // The command's stderr is TEED, not swallowed and not merely inherited:
+    // echoed so a mint script that explains itself is audible even when it
+    // succeeds (half the field diagnosis cost was a script with no voice),
+    // AND kept in the error below so a programmatic caller still gets the
+    // reason. Inheriting alone would have made the failure message say only
+    // "see above", which is useless to `--json`.
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    if !stderr.trim().is_empty() {
+        eprint!("{stderr}");
+    }
     if !output.status.success() {
         return Err(format!(
             "env_from command exited with {}: {}",
             output.status.code().unwrap_or(-1),
-            String::from_utf8_lossy(&output.stderr).trim()
+            stderr.trim()
         ));
     }
     for (name, value) in parse_env_lines(&String::from_utf8_lossy(&output.stdout))? {

{flowproof-0.2.4 → flowproof-0.2.5}/crates/flowproof-cli/tests/suite_env_from.rs

@@ -139,3 +139,99 @@ fn spec_without_a_manifest_is_a_noop() {
     flowproof_cli::apply_suite_context(&spec).expect("no manifest is fine");
     std::fs::remove_dir_all(&dir).ok();
 }
+
+/// Field regression (cypress-realworld-app, round 3): a mint script that
+/// logs in over HTTP to produce a session needs the suite's own base URL
+/// and password, and got neither - the data command ran with `env:` not yet
+/// applied, so `$RWA_API` was empty and the flow failed closed downstream
+/// with a 401. Minting test data almost always needs the suite's config,
+/// so this is the common case rather than an edge.
+#[test]
+fn env_from_command_sees_the_suites_own_env() {
+    let dir = suite_dir("sees-env");
+    std::fs::write(
+        dir.join("suite.yaml"),
+        "env:\n  EF_BASE: http://example.test\nenv_from: printf 'EF_MINTED=%s/minted\\n' \"$EF_BASE\"\n",
+    )
+    .expect("manifest");
+    std::fs::write(
+        dir.join("probe.flow.yaml"),
+        "name: Probe\napp: api\nsteps:\n  - assert_api:\n      request: GET ${EF_MINTED}\n      status: 200\n",
+    )
+    .expect("spec");
+
+    // Running the suite applies env_from; the command must have seen
+    // EF_BASE and composed the minted value from it.
+    flowproof_cli::run_cli(["run", dir.to_str().expect("utf8")]);
+    assert_eq!(
+        std::env::var("EF_MINTED").as_deref(),
+        Ok("http://example.test/minted"),
+        "the data command must see the suite's env: block"
+    );
+
+    std::env::remove_var("EF_MINTED");
+    std::env::remove_var("EF_BASE");
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// The OTHER ordering is unchanged, and the two are easy to conflate:
+/// what the command SEES changed, but which value WINS for `${VAR}` at flow
+/// time did not - `env:` still overrides the data command's output.
+#[test]
+fn env_precedence_is_unchanged_env_still_wins_over_env_from() {
+    let dir = suite_dir("precedence");
+    std::fs::write(
+        dir.join("suite.yaml"),
+        "env:\n  EP_SHARED: from-env-block\nenv_from: echo EP_SHARED=from-data-command\n",
+    )
+    .expect("manifest");
+    std::fs::write(
+        dir.join("probe.flow.yaml"),
+        "name: Probe\napp: api\nsteps:\n  - assert_api:\n      request: GET http://127.0.0.1:1/x\n      status: 200\n",
+    )
+    .expect("spec");
+
+    flowproof_cli::run_cli(["run", dir.to_str().expect("utf8")]);
+    assert_eq!(
+        std::env::var("EP_SHARED").as_deref(),
+        Ok("from-env-block"),
+        "env: must still win over env_from output"
+    );
+
+    std::env::remove_var("EP_SHARED");
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// An `env:` entry that cannot resolve YET must not break the data command:
+/// it may reference that very command's output, and it gets its turn when
+/// `env:` is applied afterwards.
+#[test]
+fn an_unresolvable_env_entry_does_not_break_the_data_command() {
+    let dir = suite_dir("forward-ref");
+    std::fs::write(
+        dir.join("suite.yaml"),
+        "env:\n  FR_DERIVED: ${FR_MINTED}/derived\nenv_from: echo FR_MINTED=http://minted.test\n",
+    )
+    .expect("manifest");
+    std::fs::write(
+        dir.join("probe.flow.yaml"),
+        "name: Probe\napp: api\nsteps:\n  - assert_api:\n      request: GET ${FR_DERIVED}\n      status: 200\n",
+    )
+    .expect("spec");
+
+    flowproof_cli::run_cli(["run", dir.to_str().expect("utf8")]);
+    assert_eq!(
+        std::env::var("FR_MINTED").as_deref(),
+        Ok("http://minted.test"),
+        "the data command still ran"
+    );
+    assert_eq!(
+        std::env::var("FR_DERIVED").as_deref(),
+        Ok("http://minted.test/derived"),
+        "an entry referencing the command's own output resolves afterwards"
+    );
+
+    std::env::remove_var("FR_MINTED");
+    std::env::remove_var("FR_DERIVED");
+    std::fs::remove_dir_all(&dir).ok();
+}

{flowproof-0.2.4 → flowproof-0.2.5}/crates/flowproof-cli/tests/web_e2e.rs

@@ -1166,3 +1166,176 @@ fn label_association_case_fold_and_aria_names_resolve() {
 
     std::fs::remove_dir_all(&dir).ok();
 }
+
+/// Field regression (cypress-realworld-app, round 3): EVERY flow that logged
+/// in recorded fine and then failed to replay with "Unable to make method
+/// calls because underlying connection is closed". The mechanism is a
+/// self-inflicted transport death, and it needs two ingredients this test
+/// reproduces in order:
+///
+/// 1. more than 30 seconds of page-level work with no BROWSER-level event,
+///    which lets headless_chrome's default `idle_browser_timeout` reap the
+///    browser-event listener thread;
+/// 2. a real navigation afterwards, which fires `TargetInfoChanged` - a
+///    browser-level event the transport can no longer deliver, so it treats
+///    it as fatal and shuts the whole connection down permanently.
+///
+/// A login redirect is exactly that shape, which is why the field suite hit
+/// it on every authenticated flow and never on the others. Slow by nature
+/// (it must out-wait the idle reaper); that is the bug.
+#[test]
+fn a_navigation_after_a_long_idle_does_not_kill_the_connection() {
+    if std::env::var("FLOWPROOF_E2E").as_deref() != Ok("1") {
+        eprintln!("skipping web idle-then-navigate E2E test: set FLOWPROOF_E2E=1 to run it");
+        return;
+    }
+
+    let dir = std::env::temp_dir().join("flowproof-web-idle-nav-e2e");
+    std::fs::remove_dir_all(&dir).ok();
+    std::fs::create_dir_all(&dir).expect("temp dir");
+    // Page two is a separate document, so reaching it is a real navigation
+    // rather than a same-document update.
+    std::fs::write(
+        dir.join("two.html"),
+        r#"<!doctype html><html><body><h1>Welcome back</h1></body></html>"#,
+    )
+    .expect("page two written");
+    let page = dir.join("one.html");
+    std::fs::write(
+        &page,
+        r#"<!doctype html><html><body>
+            <div id="out">waiting</div>
+            <button id="go" onclick="window.location.href = 'two.html'">Continue</button>
+            <script>
+              // Page-level churn only: no browser-level CDP events at all,
+              // so the idle reaper is free to fire while the flow works.
+              setTimeout(() => {
+                document.getElementById('out').textContent = 'ready to continue';
+              }, 35000);
+            </script>
+        </body></html>"#,
+    )
+    .expect("page one written");
+    let trace_path = dir.join("idle-nav.trace.jsonl");
+
+    let spec = flowproof_agent::FlowSpec {
+        name: "Navigate after a long idle".into(),
+        app: "web".into(),
+        url: Some(format!("file://{}", page.display())),
+        redact: vec![],
+        connection: None,
+        window: None,
+        session: None,
+        skip_unless_env: Vec::new(),
+        mock: Vec::new(),
+        browser: None,
+        steps: vec![
+            // Out-waits the 30s default idle timeout.
+            flowproof_agent::SpecStep::Plain(
+                "Wait until page shows ready to continue within 60s".into(),
+            ),
+            flowproof_agent::SpecStep::Plain("Press the \"Continue\" button".into()),
+            // The read that used to die: first page-level call after the
+            // navigation's TargetInfoChanged.
+            flowproof_agent::SpecStep::Plain(
+                "Wait until page shows Welcome back within 20s".into(),
+            ),
+        ],
+    };
+
+    let mut driver = flowproof_cli::driver_for("web").expect("browser launches");
+    flowproof_agent::record(&spec, &mut driver, &trace_path).expect("recording survives the idle");
+    drop(driver);
+
+    let mut driver = flowproof_cli::driver_for("web").expect("browser launches");
+    let (report, _run_dir) =
+        flowproof_replay::run_trace(&trace_path, &mut driver).expect("replay runs");
+    assert!(
+        report.passed,
+        "a navigation after an idle period must not kill the transport: {report:#?}"
+    );
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// Field regression (cypress-realworld-app, round 3): a settings form whose
+/// first field sat below the fold was untestable. The actionability gate
+/// hit-tests `elementFromPoint` at the element's centre, but ran BEFORE any
+/// scrolling - and outside the viewport that returns null, so the gate
+/// reported "obscured (another element would receive the click)" and
+/// blocked a click that would have worked. headless_chrome's own
+/// `Element::click` starts with `scroll_into_view`, so the gate was asking
+/// about a position the click never uses. Cypress and Playwright both
+/// scroll before acting; now so does the gate.
+#[test]
+fn an_element_below_the_fold_is_scrolled_to_rather_than_called_obscured() {
+    if std::env::var("FLOWPROOF_E2E").as_deref() != Ok("1") {
+        eprintln!("skipping web below-the-fold E2E test: set FLOWPROOF_E2E=1 to run it");
+        return;
+    }
+
+    let dir = std::env::temp_dir().join("flowproof-web-below-fold-e2e");
+    std::fs::remove_dir_all(&dir).ok();
+    std::fs::create_dir_all(&dir).expect("temp dir");
+    let page = dir.join("tall.html");
+    // A tall spacer puts the field far below a pinned 500x300 viewport, so
+    // "below the fold" is a property of the test, not of the runner.
+    std::fs::write(
+        &page,
+        r#"<!doctype html><html><body style="margin:0">
+            <div style="height:1200px">scroll down</div>
+            <input id="name" placeholder="Full name" />
+            <button id="save" onclick="
+              document.getElementById('out').textContent = 'Saved ' + document.getElementById('name').value;
+            ">Save</button>
+            <div id="out"></div>
+        </body></html>"#,
+    )
+    .expect("page written");
+    let trace_path = dir.join("tall.trace.jsonl");
+
+    let spec = flowproof_agent::FlowSpec {
+        name: "Field below the fold".into(),
+        app: "web".into(),
+        url: Some(format!("file://{}", page.display())),
+        redact: vec![],
+        connection: None,
+        window: None,
+        session: None,
+        skip_unless_env: Vec::new(),
+        mock: Vec::new(),
+        browser: Some(flowproof_trace::format::BrowserSetup {
+            viewport: Some(flowproof_trace::format::ViewportSetup {
+                width: 500,
+                height: 300,
+                device_scale_factor: None,
+                mobile: None,
+                touch: None,
+            }),
+            user_agent: None,
+            args: Vec::new(),
+        }),
+        steps: vec![
+            flowproof_agent::SpecStep::Plain("Type Ada into the name field".into()),
+            flowproof_agent::SpecStep::Plain("Press the \"Save\" button".into()),
+            flowproof_agent::SpecStep::Assert {
+                assert: "page shows Saved Ada".into(),
+            },
+        ],
+    };
+
+    let mut driver = flowproof_cli::driver_for("web").expect("browser launches");
+    flowproof_agent::record(&spec, &mut driver, &trace_path)
+        .expect("recording reaches a field below the fold");
+    drop(driver);
+
+    let mut driver = flowproof_cli::driver_for("web").expect("browser launches");
+    let (report, _run_dir) =
+        flowproof_replay::run_trace(&trace_path, &mut driver).expect("replay runs");
+    assert!(
+        report.passed,
+        "below-the-fold element must be scrolled to, not called obscured: {report:#?}"
+    );
+
+    std::fs::remove_dir_all(&dir).ok();
+}

{flowproof-0.2.4 → flowproof-0.2.5}/crates/flowproof-driver/src/app.rs

@@ -211,6 +211,16 @@ pub trait AppDriver {
         ))
     }
 
+    /// The surface's current location, for `page url is|contains`. Only a
+    /// browser has one: a UIA window, a SAP session and an OCR'd frame do
+    /// not, so the default refuses with a reason rather than inventing an
+    /// empty string that would make assertions quietly pass.
+    fn current_url(&mut self) -> Result<String, DriverError> {
+        Err(DriverError::Uia(
+            "this app has no URL: `page url` assertions are for web flows".into(),
+        ))
+    }
+
     /// Stage session state (cookies, localStorage) to be applied by the
     /// NEXT `launch` before the page loads.
     fn stage_session(&mut self, _session: WebSession) -> Result<(), DriverError> {
@@ -430,6 +440,70 @@ pub struct AppTarget {
 /// Extract the trailing numeric value from display text like
 /// `Display is 8` or `1,234.5`. Shared by record and replay so both phases
 /// judge display values identically.
+/// Does `actual` (a full URL) satisfy a `page url` expectation?
+///
+/// Shared by record and replay - like [`numeric_value`] - because a URL
+/// assertion that holds while recording must hold when replayed, and two
+/// copies of a matcher drift (that is exactly how the round-3 field
+/// migration produced traces that could not replay).
+///
+/// `exact = false` is `page url contains <text>`: a plain substring test
+/// over the whole href.
+///
+/// `exact = true` is `page url is <expected>`, which is deliberately
+/// path-shaped, because `cy.location("pathname").should("equal", "/signin")`
+/// is the assertion people actually write:
+///
+/// - `expected` containing `://` compares against the WHOLE url, exactly;
+/// - `expected` starting with `/` compares against the pathname, and
+///   includes the query only when `expected` carries a `?`, the fragment
+///   only when it carries a `#`. So `/orders` ignores `?page=2`, while
+///   `/orders?page=2` does not;
+/// - anything else compares against the whole url, exactly. There is no
+///   guessing: an expectation that is neither a path nor a full URL is
+///   most likely a mistake, and an exact comparison says so loudly.
+pub fn url_matches(expected: &str, exact: bool, actual: &str) -> bool {
+    if !exact {
+        return actual.contains(expected);
+    }
+    if expected.contains("://") || !expected.starts_with('/') {
+        return actual == expected;
+    }
+    let (want_query, want_hash) = (expected.contains('?'), expected.contains('#'));
+    // Split the live URL into path / query / fragment without pulling in a
+    // URL crate: after the scheme's `://`, the path starts at the first
+    // `/`, and `?` / `#` bound it from the right.
+    let after_scheme = match actual.find("://") {
+        Some(i) => &actual[i + 3..],
+        None => actual,
+    };
+    let from_path = match after_scheme.find('/') {
+        Some(i) => &after_scheme[i..],
+        // No path at all ("https://example.test") means the root.
+        None => "/",
+    };
+    let hash_at = from_path.find('#');
+    let without_hash = match hash_at {
+        Some(i) => &from_path[..i],
+        None => from_path,
+    };
+    let hash = hash_at.map(|i| &from_path[i..]).unwrap_or("");
+    let query_at = without_hash.find('?');
+    let path = match query_at {
+        Some(i) => &without_hash[..i],
+        None => without_hash,
+    };
+    let query = query_at.map(|i| &without_hash[i..]).unwrap_or("");
+    let mut candidate = String::from(path);
+    if want_query {
+        candidate.push_str(query);
+    }
+    if want_hash {
+        candidate.push_str(hash);
+    }
+    candidate == expected
+}
+
 pub fn numeric_value(text: &str) -> Option<f64> {
     text.split_whitespace()
         .rev()
@@ -547,6 +621,10 @@ impl AppDriver for Box<dyn AppDriver> {
         (**self).surface_text()
     }
 
+    fn current_url(&mut self) -> Result<String, DriverError> {
+        (**self).current_url()
+    }
+
     fn stage_session(&mut self, session: WebSession) -> Result<(), DriverError> {
         (**self).stage_session(session)
     }
@@ -1094,3 +1172,103 @@ mod tests {
         assert!(matches!(err, DriverError::UnsupportedPlatform));
     }
 }
+
+#[cfg(test)]
+mod url_matches_tests {
+    use super::url_matches;
+
+    /// `page url is /path` is path-shaped on purpose: it maps
+    /// `cy.location("pathname").should("equal", "/signin")` one to one.
+    #[test]
+    fn a_path_expectation_compares_the_pathname_only() {
+        assert!(url_matches("/signin", true, "http://localhost:3000/signin"));
+        assert!(url_matches("/signin", true, "https://app.test/signin#top"));
+        // The query is ignored unless the expectation asks for one.
+        assert!(url_matches(
+            "/orders",
+            true,
+            "https://app.test/orders?page=2"
+        ));
+        assert!(!url_matches("/signin", true, "https://app.test/signup"));
+        // A path expectation must not match a mere prefix.
+        assert!(!url_matches("/order", true, "https://app.test/orders"));
+    }
+
+    #[test]
+    fn a_query_or_fragment_in_the_expectation_makes_it_significant() {
+        assert!(url_matches(
+            "/orders?page=2",
+            true,
+            "https://app.test/orders?page=2"
+        ));
+        assert!(!url_matches(
+            "/orders?page=2",
+            true,
+            "https://app.test/orders?page=3"
+        ));
+        assert!(!url_matches(
+            "/orders?page=2",
+            true,
+            "https://app.test/orders"
+        ));
+        assert!(url_matches(
+            "/docs#install",
+            true,
+            "https://app.test/docs#install"
+        ));
+        assert!(!url_matches(
+            "/docs#install",
+            true,
+            "https://app.test/docs#usage"
+        ));
+    }
+
+    #[test]
+    fn a_full_url_expectation_compares_the_whole_url() {
+        assert!(url_matches(
+            "https://app.test/signin",
+            true,
+            "https://app.test/signin"
+        ));
+        // Different scheme or host is a different URL, even at the same path.
+        assert!(!url_matches(
+            "https://app.test/signin",
+            true,
+            "http://app.test/signin"
+        ));
+    }
+
+    #[test]
+    fn contains_is_a_plain_substring_of_the_whole_url() {
+        assert!(url_matches(
+            "checkout",
+            false,
+            "https://app.test/cart/checkout?step=1"
+        ));
+        assert!(url_matches("app.test", false, "https://app.test/cart"));
+        assert!(!url_matches("checkout", false, "https://app.test/cart"));
+    }
+
+    /// Edge shapes that must not panic or silently mis-compare: a bare
+    /// origin has the root path, and non-ASCII paths are byte-safe.
+    #[test]
+    fn origins_and_multibyte_paths_are_handled() {
+        assert!(url_matches("/", true, "https://app.test"));
+        assert!(url_matches("/", true, "https://app.test/"));
+        assert!(url_matches(
+            "/konto/überweisung",
+            true,
+            "https://app.test/konto/überweisung"
+        ));
+        assert!(url_matches(
+            "überweisung",
+            false,
+            "https://app.test/konto/überweisung"
+        ));
+        assert!(!url_matches(
+            "/konto/überweisung",
+            true,
+            "https://app.test/konto/uberweisung"
+        ));
+    }
+}

{flowproof-0.2.4 → flowproof-0.2.5}/crates/flowproof-driver/src/lib.rs

@@ -19,9 +19,9 @@ pub mod visual;
 pub mod window;
 
 pub use app::{
-    absolute_url, numeric_value, resolve_app, url_origin, AppDriver, AppTarget, DebugBundle,
-    KeyMod, NoOpDriver, PixelRect, UiaAppDriver, UiaSelector, WebBrowserConfig, WebMock,
-    WebSession, WebViewport,
+    absolute_url, numeric_value, resolve_app, url_matches, url_origin, AppDriver, AppTarget,
+    DebugBundle, KeyMod, NoOpDriver, PixelRect, UiaAppDriver, UiaSelector, WebBrowserConfig,
+    WebMock, WebSession, WebViewport,
 };
 pub use backend::PlatformBackend;
 pub use recording::{FrameRef, Recording, RunRecorder, StepTiming};

{flowproof-0.2.4 → flowproof-0.2.5}/crates/flowproof-driver/src/mock.rs

@@ -69,6 +69,8 @@ pub struct MockAppDriver {
     /// Browser config captured by `stage_browser` — the mock stands in
     /// for the web driver here, so tests can assert the staging happened.
     pub staged_browser: Option<crate::WebBrowserConfig>,
+    /// URL reported by `current_url`, for `page url is|contains` tests.
+    pub url: Option<String>,
     /// Leading `surface_text` calls that fail with a TRANSPORT fault before
     /// any real answer — a dead CDP socket during an auto-wait poll.
     /// `u32::MAX` never recovers, which is how the "budget expired without
@@ -98,6 +100,11 @@ impl MockAppDriver {
         self
     }
 
+    pub fn with_url(mut self, url: &str) -> Self {
+        self.url = Some(url.into());
+        self
+    }
+
     /// Fail the next `count` surface reads with a transport fault. Models
     /// the field case behind GAP-A: the socket dies mid-flow while the app
     /// itself is fine, so a poll learns nothing and must not fail the step.
@@ -189,6 +196,12 @@ impl AppDriver for MockAppDriver {
         Ok(())
     }
 
+    fn current_url(&mut self) -> Result<String, DriverError> {
+        self.url
+            .clone()
+            .ok_or_else(|| DriverError::Uia("mock has no url".into()))
+    }
+
     fn surface_text(&mut self) -> Result<String, DriverError> {
         if self.surface_faults > 0 {
             // u32::MAX means "never recovers": leave it saturated.

{flowproof-0.2.4 → flowproof-0.2.5}/crates/flowproof-replay/src/lib.rs

@@ -439,6 +439,65 @@ where
     }
 }
 
+/// The `page url` expectation carried by an `element_state`, if any:
+/// `(expected, exact)` where exact distinguishes `is` from `contains`.
+fn url_expectation(expect: &serde_json::Value) -> Option<(&str, bool)> {
+    expect
+        .get("url_equals")
+        .and_then(|v| v.as_str())
+        .map(|e| (e, true))
+        .or_else(|| {
+            expect
+                .get("url_contains")
+                .and_then(|v| v.as_str())
+                .map(|e| (e, false))
+        })
+}
+
+/// Poll the surface's URL until the expectation holds or `deadline` passes.
+/// Mirrors [`check_text_expectation`]: transport faults are misses, a
+/// budget that expires with no reading at all is a driver error, and the
+/// message keeps the RAW expectation so a `${VAR}` never leaks.
+fn check_url_expectation<F>(
+    expect: &serde_json::Value,
+    raw: &str,
+    exact: bool,
+    deadline: Instant,
+    mut read: F,
+) -> Result<(Result<(), String>, Option<usize>), ReplayError>
+where
+    F: FnMut() -> Result<String, flowproof_driver::DriverError>,
+{
+    let _ = expect;
+    let expected = match flowproof_trace::secret::resolve_refs(raw) {
+        Ok(expected) => expected,
+        Err(e) => return Ok((Err(e.to_string()), None)),
+    };
+    let mut fault: Option<flowproof_driver::DriverError> = None;
+    let mut last: Option<String> = None;
+    loop {
+        if let Some(url) = tolerate(read(), &mut fault)? {
+            if flowproof_driver::url_matches(&expected, exact, &url) {
+                return Ok((Ok(()), None));
+            }
+            last = Some(url);
+        }
+        if Instant::now() >= deadline {
+            let Some(url) = last else {
+                return Err(exhausted(fault));
+            };
+            let shown = if flowproof_trace::secret::has_refs(raw) {
+                "<masked>".to_string()
+            } else {
+                url
+            };
+            let verb = if exact { "url" } else { "url containing" };
+            return Ok((Err(format!("expected {verb} '{raw}', got '{shown}'")), None));
+        }
+        std::thread::sleep(POLL_INTERVAL);
+    }
+}
+
 /// One reading inside an auto-wait poll loop. A [`DriverError::Transport`]
 /// fault is a MISS (`Ok(None)`) rather than an error: the assertion's
 /// contract is "this holds within N seconds", and a dead socket on one
@@ -515,6 +574,15 @@ fn check_assertion<D: AppDriver>(
             // Surface-scoped: no selector to resolve — every adapter
             // answers `surface_text` its own way (page / window subtree /
             // OCR frame).
+            // `page url is|contains` reads the surface's LOCATION rather
+            // than its text. Same poll, same recorded bound: an SPA
+            // redirect lands asynchronously, so this must auto-wait like
+            // everything else.
+            if let Some((raw, exact)) = url_expectation(expect) {
+                return check_url_expectation(expect, raw, exact, deadline, || {
+                    driver.current_url()
+                });
+            }
             if expect.get("scope").and_then(|v| v.as_str()) == Some("surface") {
                 return check_text_expectation(expect, deadline, None, || driver.surface_text());
             }

{flowproof-0.2.4 → flowproof-0.2.5}/crates/flowproof-replay/tests/replay_calc.rs

@@ -1245,3 +1245,95 @@ fn transport_fault_tolerance_preserves_multibyte_surface_text() {
 
     std::fs::remove_dir_all(&dir).ok();
 }
+
+/// GAP-D (field: cypress-realworld-app). `cy.location("pathname")
+/// .should("equal","/signin")` is the most common assertion in that suite
+/// and had no equivalent - the workaround was asserting on visible text,
+/// which passes even when the route is wrong. Record and replay must agree
+/// on what the URL forms mean, so both run through the same matcher.
+#[test]
+fn url_assertions_record_and_replay_through_one_matcher() {
+    let dir = std::env::temp_dir().join("flowproof-replay-url");
+    std::fs::create_dir_all(&dir).expect("temp dir");
+    let spec = FlowSpec::parse(
+        "name: Redirect\napp: web\nurl: x\nsteps:\n  - assert: page url is /signin\n  - assert: page url contains signin\n",
+    )
+    .expect("spec parses");
+    let spec = FlowSpec {
+        url: Some("https://app.test/personal".into()),
+        ..spec
+    };
+    let trace = dir.join("url.trace.jsonl");
+
+    // Recording verifies against the live URL, exactly as replay will.
+    let mut rec = MockAppDriver::new(&[]).with_url("https://app.test/signin?next=%2Fpersonal");
+    record(&spec, &mut rec, &trace).expect("recording verifies the url");
+
+    // The trace carries the expectation, not the resolved location.
+    let persisted = std::fs::read_to_string(&trace).expect("trace readable");
+    assert!(
+        persisted.contains("\"url_equals\":\"/signin\""),
+        "{persisted}"
+    );
+    assert!(
+        persisted.contains("\"url_contains\":\"signin\""),
+        "{persisted}"
+    );
+
+    // Replay: same URL, passes. The query is ignored because the
+    // expectation carries no `?`.
+    let mut driver = MockAppDriver::new(&[]).with_url("https://app.test/signin?next=%2Fpersonal");
+    let (report, _run_dir) = run_trace(&trace, &mut driver).expect("replay runs");
+    assert!(report.passed, "report: {report:#?}");
+
+    // A different route fails, and the failure names what it saw - the
+    // whole point of the assertion over a text proxy.
+    let mut driver = MockAppDriver::new(&[]).with_url("https://app.test/signup");
+    let (report, _run_dir) = run_trace(&trace, &mut driver).expect("replay runs");
+    assert!(!report.passed);
+    let detail = report.steps[0].detail.clone().unwrap_or_default();
+    assert!(detail.contains("/signin"), "detail: {detail}");
+    assert!(
+        detail.contains("signup"),
+        "detail names the live url: {detail}"
+    );
+
+    std::fs::remove_dir_all(&dir).ok();
+}
+
+/// A URL expectation may carry a `${VAR}`, and then neither the trace nor a
+/// failure message may leak the resolved value.
+#[test]
+fn url_assertions_keep_secrets_out_of_the_trace_and_the_message() {
+    let dir = std::env::temp_dir().join("flowproof-replay-url-secret");
+    std::fs::create_dir_all(&dir).expect("temp dir");
+    std::env::set_var("FP_URL_TENANT", "acme-7f3c");
+    let spec = FlowSpec::parse(
+        "name: Tenant\napp: web\nurl: x\nsteps:\n  - assert: page url contains ${FP_URL_TENANT}\n",
+    )
+    .expect("spec parses");
+    let spec = FlowSpec {
+        url: Some("https://app.test/".into()),
+        ..spec
+    };
+    let trace = dir.join("secret.trace.jsonl");
+    let mut rec = MockAppDriver::new(&[]).with_url("https://app.test/t/acme-7f3c/home");
+    record(&spec, &mut rec, &trace).expect("recording resolves the ref");
+
+    let persisted = std::fs::read_to_string(&trace).expect("trace readable");
+    assert!(persisted.contains("${FP_URL_TENANT}"), "raw ref travels");
+    assert!(
+        !persisted.contains("acme-7f3c"),
+        "resolved value must not: {persisted}"
+    );
+
+    let mut driver = MockAppDriver::new(&[]).with_url("https://app.test/t/other/home");
+    let (report, _run_dir) = run_trace(&trace, &mut driver).expect("replay runs");
+    assert!(!report.passed);
+    let detail = report.steps[0].detail.clone().unwrap_or_default();
+    assert!(!detail.contains("acme-7f3c"), "failure must mask: {detail}");
+    assert!(detail.contains("<masked>"), "detail: {detail}");
+
+    std::env::remove_var("FP_URL_TENANT");
+    std::fs::remove_dir_all(&dir).ok();
+}

{flowproof-0.2.4 → flowproof-0.2.5}/flowproof/__init__.py

@@ -24,7 +24,7 @@ from flowproof.flow import (
     run,
 )
 
-__version__ = "0.2.4"
+__version__ = "0.2.5"
 
 __all__ = [
     "ClarificationNeeded",

{flowproof-0.2.4 → flowproof-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "flowproof"
-version = "0.2.4"
+version = "0.2.5"
 description = "Generic open-source automation framework for the AI-agent era: automated testing and agentic process automation across web, desktop, and Citrix."
 readme = "README.md"
 license = "Apache-2.0"