Skip to content

Automate browser based workflows with AI

Recover blocked inline PDF downloads when no download event fires (#7774)

LawyZheng0bb84111606e
diff --git a/skyvern/webeye/actions/handler.py b/skyvern/webeye/actions/handler.py
index 6cc3a26ef..9e460647e 100644
--- a/skyvern/webeye/actions/handler.py
+++ b/skyvern/webeye/actions/handler.py
@@ -176,7 +176,7 @@ from skyvern.webeye.utils.dom import (
is_incompatible_text_input_error,
is_post_dispatch_click_timeout,
)
-from skyvern.webeye.utils.page import SkyvernFrame, take_element_screenshot
+from skyvern.webeye.utils.page import SkyvernFrame, _all_page_frames, take_element_screenshot
LOG = structlog.get_logger()
@@ -879,6 +879,140 @@ async def _finalize_download_artifacts(
return [os.path.basename(path) for path in paths], new_file_paths
+_INLINE_IFRAME_SRC_JS = "() => Array.from(document.querySelectorAll('iframe')).map((f) => f.src || '')"
+
+# Whole-operation cap for blocked-inline-PDF recovery (all candidate same-origin fetches share it,
+# so up to _collect's cap of candidates can't multiply the budget). A ~3 MB same-origin PDF fetches
+# in well under a second; 30s is generous headroom for a slow-but-alive server while a hung one can
+# no longer out-wait the download loop this recovery backstops.
+_BLOCKED_INLINE_PDF_RECOVERY_TIMEOUT_SECONDS = 30.0
+
+
+def _looks_like_pdf(data: bytes) -> bool:
+ # A real PDF starts with %PDF-, optionally after a single exact UTF-8 BOM. Match the whole
+ # 3-byte BOM sequence (not individual BOM bytes) and anchor at the start so HTML/JSON error
+ # pages that merely mention the marker further down are rejected.
+ header = data[3:] if data[:3] == b"\xef\xbb\xbf" else data
+ return header[:5] == b"%PDF-"
+
+
+async def _collect_inline_iframe_src_candidates(page: Page) -> list[str]:
+ """Every http(s) <iframe> src on the page, deduped, order-preserving.
+
+ Uncapped on purpose: this feeds the before/after action-window comparison, so an arbitrary cap
+ (e.g. the first N in DOM order) could drop a newly-appended target that sits past many pre-existing
+ ad/tracker iframes, silently no-opping recovery. Enumeration is cheap (one evaluate per frame);
+ the fetch work it gates is bounded by the whole-operation budget in handle_action instead.
+ """
+ candidates: list[str] = []
+ seen: set[str] = set()
+ main_frame = page.main_frame
+ for frame in _all_page_frames(page):
+ # Route the main frame through the Page so SkyvernFrame.evaluate can attach any
+ # context-level main-world prefix; child frames evaluate in-frame (prefixes are page-scoped).
+ target: Page | Frame = page if frame is main_frame else frame
+ try:
+ srcs = await SkyvernFrame.evaluate(frame=target, expression=_INLINE_IFRAME_SRC_JS)
+ except Exception:
+ continue
+ if not isinstance(srcs, list):
+ continue
+ for src in srcs:
+ if not isinstance(src, str) or not src.startswith(("http://", "https://")) or src in seen:
+ continue
+ seen.add(src)
+ candidates.append(src)
+ return candidates
+
+
+async def _recover_blocked_inline_pdf_download(
+ page: Page,
+ download_dir: Path,
+ workflow_run_id: str | None,
+ *,
+ iframe_srcs_before: list[str],
+) -> Path | None:
+ """Recover a PDF whose inline iframe render was refused by a browser frame-embedding policy.
+
+ A download-intent click can leave the statement in an <iframe> the browser refuses to display
+ (its bytes still download fine, they just can't be framed). To tie the recovery to *this* click
+ rather than any PDF on the page, only iframes that appeared in the action window are candidates:
+ an iframe whose src is absent from ``iframe_srcs_before`` (the pre-action snapshot, required) is
+ either newly attached or an existing iframe navigated to a new src. Pre-existing frames (adverts,
+ a reCAPTCHA anchor, a previously opened statement) are excluded because their src is already in
+ the baseline. Recovery only fires when exactly one candidate src is a PDF; zero or several
+ equally-plausible candidate srcs fail closed (return None) so we never save an unrelated file —
+ two distinct candidate URLs are ambiguous even when their bytes happen to match. The recovered
+ bytes are written to ``download_dir`` to rejoin the normal finalize / dedupe / filename / upload
+ lifecycle.
+ """
+ after = await _collect_inline_iframe_src_candidates(page)
+ if not after:
+ return None
+ baseline = set(iframe_srcs_before)
+ action_window_candidates = [src for src in after if src not in baseline]
+ if not action_window_candidates:
+ return None
+
+ pdf_candidate: tuple[str, bytes] | None = None
+ for src in action_window_candidates:
+ try:
+ data = await SkyvernFrame.read_http_url_bytes(
+ page,
+ src,
+ workflow_run_id=workflow_run_id,
+ max_size_bytes=MAX_FILE_SIZE_BYTES,
+ timeout_ms=_BLOCKED_INLINE_PDF_RECOVERY_TIMEOUT_SECONDS * 1000,
+ )
+ except asyncio.CancelledError:
+ raise
+ except Exception:
+ LOG.debug(
+ "Blocked-iframe recovery fetch raised; trying next candidate",
+ workflow_run_id=workflow_run_id,
+ exc_info=True,
+ )
+ continue
+ if not data or not _looks_like_pdf(data):
+ continue
+ if pdf_candidate is not None:
+ # A second distinct candidate src is a PDF: the action window is ambiguous, fail closed.
+ LOG.warning(
+ "Multiple inline PDF candidates appeared in the action window; not recovering any",
+ workflow_run_id=workflow_run_id,
+ )
+ return None
+ pdf_candidate = (src, data)
+
+ if pdf_candidate is None:
+ return None
+
+ src, data = pdf_candidate
+ base_name = normalize_download_filename(os.path.basename(urllib.parse.urlparse(src).path), "application/pdf")
+ if not base_name:
+ # A URL with no path basename (e.g. ".../?token=...") yields no name; the bytes are a
+ # confirmed PDF, so give the persisted file a .pdf extension instead of an extension-less one.
+ base_name = "statement.pdf"
+ target = _download_target_path(download_dir, base_name)
+ try:
+ download_dir.mkdir(parents=True, exist_ok=True)
+ target.write_bytes(data)
+ except OSError:
+ LOG.warning(
+ "Failed to persist recovered blocked-iframe PDF",
+ workflow_run_id=workflow_run_id,
+ exc_info=True,
+ )
+ return None
+ LOG.info(
+ "Recovered a browser-blocked inline PDF via same-origin fetch",
+ workflow_run_id=workflow_run_id,
+ recovered_bytes=len(data),
+ download_target=str(target),
+ )
+ return target
+
+
async def _cleanup_captured_download_popup(
popup: Page, browser_state: BrowserState, page: Page, page_url_before_download: str
) -> None:
@@ -2598,6 +2732,9 @@ class ActionHandler:
num_downloaded_files_before=len(list_files_before),
download_dir=download_dir,
)
+ # Baseline of inline iframe srcs before the action, so a blocked-inline-PDF recovery can
+ # admit only frames that appeared in this action's window (see _recover_blocked_inline_pdf_download).
+ inline_iframe_srcs_before = await _collect_inline_iframe_src_candidates(page)
staging_dir = Path(make_temp_directory(prefix=f"{run_id}_xhr_staging_"))
xhr_capture = ScopedXhrDownloadCapture(
@@ -2886,6 +3023,32 @@ class ActionHandler:
elif await _drain_and_move_staged_xhr(xhr_fallback_moved_paths, _remaining_download_wait_seconds()):
download_triggered = True
+ # A download-intent click can render the target PDF inline in a frame the browser refuses
+ # to display, so no download event ever fires. If the bytes are still same-origin
+ # retrievable, recover them and rejoin the normal finalize path. Skipped when the workflow
+ # matched a user-defined terminal error, so configured stop conditions stay authoritative.
+ if not download_triggered and not download_wait_matched_errors:
+ recovered_path = None
+ try:
+ # One whole-operation budget over every candidate fetch: a hung same-origin
+ # server must not out-wait the download loop this backstops. On timeout, fall
+ # through to the normal download-not-triggered follow-up — never hang or hard-fail.
+ async with asyncio.timeout(_BLOCKED_INLINE_PDF_RECOVERY_TIMEOUT_SECONDS):
+ recovered_path = await _recover_blocked_inline_pdf_download(
+ page,
+ download_dir,
+ workflow_run_id=task.workflow_run_id,
+ iframe_srcs_before=inline_iframe_srcs_before,
+ )
+ except asyncio.TimeoutError:
+ LOG.warning(
+ "Blocked-inline PDF recovery exceeded its budget; treating as no recovery",
+ workflow_run_id=task.workflow_run_id,
+ recovery_budget_seconds=_BLOCKED_INLINE_PDF_RECOVERY_TIMEOUT_SECONDS,
+ )
+ if recovered_path is not None:
+ download_triggered = True
+
if not download_triggered:
if action.errors:
results[-1] = ActionFailure(
diff --git a/skyvern/webeye/utils/page.py b/skyvern/webeye/utils/page.py
index 2ee5664d4..e5188b4bd 100644
--- a/skyvern/webeye/utils/page.py
+++ b/skyvern/webeye/utils/page.py
@@ -431,11 +431,11 @@ def _merge_images_by_position(images: list[Image.Image], positions: list[int]) -
# FileReader keeps the payload binary-safe without arrayBuffer/Uint8Array
# transcoding back across CDP.
-_BLOB_FETCH_JS = """
+_SAME_ORIGIN_FETCH_JS = """
async (args) => {
try {
- const { blobUrl, maxSizeBytes } = args;
- const response = await fetch(blobUrl);
+ const { url, maxSizeBytes } = args;
+ const response = await fetch(url);
if (!response.ok) {
return { ok: false, status: response.status };
}
@@ -486,8 +486,8 @@ def _frame_origin(frame_url: str | None) -> str | None:
return f"{parsed.scheme}://{parsed.netloc}"
-def _frames_for_blob_origin(page: Page, blob_origin: str) -> list[Frame]:
- """Return frames whose origin matches the blob's origin, main frame first."""
+def _frames_for_origin(page: Page, origin: str) -> list[Frame]:
+ """Return frames whose origin matches the given origin, main frame first."""
seen: set[int] = set()
matches: list[Frame] = []
candidates: list[Frame] = [page.main_frame, *page.frames]
@@ -500,11 +500,16 @@ def _frames_for_blob_origin(page: Page, blob_origin: str) -> list[Frame]:
frame_url = frame.url
except Exception:
continue
- if _frame_origin(frame_url) == blob_origin:
+ if _frame_origin(frame_url) == origin:
matches.append(frame)
return matches
+def _frames_for_blob_origin(page: Page, blob_origin: str) -> list[Frame]:
+ """Return frames whose origin matches the blob's origin, main frame first."""
+ return _frames_for_origin(page, blob_origin)
+
+
def _all_page_frames(page: Page) -> list[Frame]:
"""All frames on the page, main frame first, deduped."""
seen: set[int] = set()
@@ -697,7 +702,7 @@ class SkyvernFrame:
return None
# blob.size is checked in-page against this before the payload is serialized.
- blob_arg = {"blobUrl": blob_url, "maxSizeBytes": max_size_bytes}
+ blob_arg = {"url": blob_url, "maxSizeBytes": max_size_bytes}
main_frame = page.main_frame
for frame in frames:
try:
@@ -705,9 +710,9 @@ class SkyvernFrame:
# context-level main-world prefix stays attached; sub-frames use
# frame.evaluate (main-world prefixes are page-scoped).
if frame is main_frame:
- result = await evaluate_in_main_world(page, _BLOB_FETCH_JS, blob_arg)
+ result = await evaluate_in_main_world(page, _SAME_ORIGIN_FETCH_JS, blob_arg)
else:
- result = await frame.evaluate(_BLOB_FETCH_JS, blob_arg)
+ result = await frame.evaluate(_SAME_ORIGIN_FETCH_JS, blob_arg)
except Exception:
retry_log(
"blob URL in-frame fetch raised; trying next frame if any",
@@ -753,6 +758,72 @@ class SkyvernFrame:
)
return None
+ @staticmethod
+ async def read_http_url_bytes(
+ page: Page,
+ url: str,
+ workflow_run_id: str | None = None,
+ max_size_bytes: int | None = None,
+ timeout_ms: float = SettingsManager.get_settings().BROWSER_ACTION_TIMEOUT_MS,
+ ) -> bytes | None:
+ """Fetch an http(s) URL's bytes via an in-page fetch() inside a same-origin frame.
+
+ Recovers a resource whose inline iframe render was refused by a frame-embedding policy
+ while its bytes stay retrievable same-origin (session cookies + connect-src apply to a
+ same-origin fetch). Returns None for non-http(s) URLs, when no same-origin frame exists,
+ or when every candidate frame's fetch fails.
+
+ ``timeout_ms`` is the per-fetch evaluate timeout (default matches SkyvernFrame.evaluate);
+ a caller with a larger whole-operation budget can widen it so a slow-but-alive server
+ isn't rejected by the generic action timeout.
+ """
+ parsed = urllib.parse.urlparse(url)
+ if parsed.scheme not in ("http", "https") or not parsed.netloc:
+ return None
+ frames = _frames_for_origin(page, f"{parsed.scheme}://{parsed.netloc}")
+ if not frames:
+ LOG.debug("same-origin URL read found no matching frame", workflow_run_id=workflow_run_id)
+ return None
+
+ # _SAME_ORIGIN_FETCH_JS is a plain fetch(); reused here for http(s) recovery.
+ fetch_arg = {"url": url, "maxSizeBytes": max_size_bytes}
+ main_frame = page.main_frame
+ for frame in frames:
+ # Route the main frame through the Page so SkyvernFrame.evaluate can attach any
+ # context-level main-world prefix; sub-frames evaluate in-frame (prefixes are
+ # page-scoped). SkyvernFrame.evaluate centralizes the main-world dispatch, timeout,
+ # and navigation-context recovery.
+ target: Page | Frame = page if frame is main_frame else frame
+ try:
+ result = await SkyvernFrame.evaluate(
+ frame=target, expression=_SAME_ORIGIN_FETCH_JS, arg=fetch_arg, timeout_ms=timeout_ms
+ )
+ except Exception:
+ LOG.debug(
+ "same-origin URL in-frame fetch raised; trying next frame if any",
+ workflow_run_id=workflow_run_id,
+ exc_info=True,
+ )
+ continue
+ if isinstance(result, dict) and result.get("error") == "too_large":
+ LOG.warning(
+ "same-origin URL exceeds max size; not reading",
+ workflow_run_id=workflow_run_id,
+ size=result.get("size"),
+ max_size_bytes=max_size_bytes,
+ )
+ return None
+ if not isinstance(result, dict) or not result.get("ok"):
+ continue
+ b64_payload = result.get("base64")
+ if not isinstance(b64_payload, str):
+ continue
+ try:
+ return base64.b64decode(b64_payload, validate=True)
+ except Exception:
+ continue
+ return None
+
# -- cursor overlay helpers ------------------------------------------------
@staticmethod
diff --git a/tests/unit/test_download_file_action_handler.py b/tests/unit/test_download_file_action_handler.py
index 81f3accf3..9e3e502be 100644
--- a/tests/unit/test_download_file_action_handler.py
+++ b/tests/unit/test_download_file_action_handler.py
@@ -15,11 +15,16 @@ from skyvern.errors.errors import UserDefinedError
from skyvern.forge.sdk.models import StepStatus
from skyvern.webeye.actions.actions import ClickAction, DownloadFileAction
from skyvern.webeye.actions.handler import (
+ _BLOCKED_INLINE_PDF_RECOVERY_TIMEOUT_SECONDS,
+ _INLINE_IFRAME_SRC_JS,
DOWNLOAD_NOT_TRIGGERED_FOLLOWUP_MESSAGE,
ActionHandler,
ScopedXhrDownloadCapture,
_cleanup_captured_download_popup,
+ _collect_inline_iframe_src_candidates,
+ _looks_like_pdf,
_persist_captured_download,
+ _recover_blocked_inline_pdf_download,
_remove_download_listener,
handle_download_file_action,
)
@@ -4139,3 +4144,512 @@ async def test_handle_action_fast_native_success_cleanup_uses_zero_xhr_budget()
assert results[-1].download_triggered is True
mock_xhr.drain.assert_awaited_once_with(timeout_seconds=0)
+
+
+_RECOVER_READ = "skyvern.webeye.actions.handler.SkyvernFrame.read_http_url_bytes"
+
+
+class _RecoveryFrame:
+ def __init__(self, iframe_srcs: list) -> None:
+ self._srcs = iframe_srcs
+ self.evaluate_calls = 0
+
+ async def evaluate(self, expression: str | None = None, arg: object = None) -> list:
+ self.evaluate_calls += 1
+ return self._srcs
+
+
+class _RecoveryPage:
+ def __init__(self, main_srcs: list, child_frames: list | None = None, frames_include_main: bool = False) -> None:
+ self.main_frame = _RecoveryFrame(main_srcs)
+ extra = child_frames or []
+ # Real Playwright's page.frames already includes the main frame; frames_include_main mirrors that.
+ self.frames = [self.main_frame, *extra] if frames_include_main else extra
+ # Page-like surface: the main frame is evaluated by passing the Page itself (is_page_like),
+ # so the Page delegates evaluate to its main frame. context=None keeps SkyvernFrame.evaluate
+ # off the main-world prefix path (no prefix configured in tests).
+ self.context = None
+
+ def bring_to_front(self) -> None:
+ return None
+
+ async def evaluate(self, expression: str | None = None, arg: object = None) -> list:
+ return await self.main_frame.evaluate(expression, arg)
+
+
+def test_looks_like_pdf_accepts_pdf_and_rejects_others() -> None:
+ assert _looks_like_pdf(b"%PDF-1.7\n...statement...")
+ assert _looks_like_pdf(b"\xef\xbb\xbf%PDF-1.4 with a preamble") # exact UTF-8 BOM tolerated
+ assert not _looks_like_pdf(b"<!doctype html><html>login</html>")
+ assert not _looks_like_pdf(b"<html>your %PDF-1.4 is attached</html>") # marker not at the start
+ assert not _looks_like_pdf(b"")
+ # only the exact 3-byte BOM is stripped, not arbitrary members of {0xef,0xbb,0xbf}
+ assert not _looks_like_pdf(b"\xef%PDF-1.4") # a lone 0xef is not a BOM
+ assert not _looks_like_pdf(b"\xbb\xbf%PDF-1.4") # a partial BOM is not a BOM
+ assert not _looks_like_pdf(b"\xef\xbb\xbf\xef\xbb\xbf%PDF-") # only one BOM is stripped
+
+
+async def test_collect_inline_iframe_src_candidates_filters_and_dedupes() -> None:
+ page = _RecoveryPage(
+ main_srcs=[
+ "https://host.example/api/StatementPdf?access_token=x",
+ "https://host.example/api/StatementPdf?access_token=x", # duplicate dropped
+ "about:blank",
+ "blob:https://host.example/abc",
+ "http://host.example/other.pdf",
+ "",
+ ]
+ )
+ result = await _collect_inline_iframe_src_candidates(page)
+ assert result == [
+ "https://host.example/api/StatementPdf?access_token=x",
+ "http://host.example/other.pdf",
+ ]
+
+
+async def test_collect_inline_iframe_src_candidates_routes_main_frame_as_page_and_child_as_frame() -> None:
+ # Enumeration must go through the unified SkyvernFrame.evaluate seam (which centralizes
+ # main-world routing, timeout handling, and navigation-context recovery), not a raw
+ # Playwright frame.evaluate. The main frame is routed as the Page so any context-level
+ # main-world prefix stays attached; child frames evaluate in-frame (prefixes are page-scoped).
+ child = _RecoveryFrame(["https://host.example/b.pdf"])
+ page = _RecoveryPage(main_srcs=["https://host.example/a.pdf"], child_frames=[child])
+ eval_mock = AsyncMock(return_value=[])
+ with patch("skyvern.webeye.actions.handler.SkyvernFrame.evaluate", eval_mock):
+ await _collect_inline_iframe_src_candidates(page)
+
+ targets = [c.kwargs["frame"] for c in eval_mock.await_args_list]
+ assert targets == [page, child] # main frame as Page, child as Frame
+ assert all(c.kwargs["expression"] == _INLINE_IFRAME_SRC_JS for c in eval_mock.await_args_list)
+
+
+async def test_collect_inline_iframe_src_candidates_is_uncapped() -> None:
+ # No arbitrary cap: every http(s) iframe src is enumerated so the before/after action-window
+ # comparison can't lose a target that sits past many pre-existing iframes.
+ srcs = [f"https://host.example/{i}.pdf" for i in range(30)]
+ page = _RecoveryPage(main_srcs=srcs)
+ result = await _collect_inline_iframe_src_candidates(page)
+ assert result == srcs
+
+
+async def test_collect_inline_iframe_src_candidates_dedupes_frames_by_identity() -> None:
+ # Playwright's page.frames already includes the main frame, so iterating
+ # [main_frame, *frames] would evaluate the main frame twice. Frame-identity dedup
+ # (via _all_page_frames) evaluates each distinct frame exactly once.
+ page = _RecoveryPage(main_srcs=["https://host.example/api/StatementPdf?access_token=x"], frames_include_main=True)
+ result = await _collect_inline_iframe_src_candidates(page)
+ assert result == ["https://host.example/api/StatementPdf?access_token=x"]
+ assert page.main_frame.evaluate_calls == 1
+
+
+async def test_recover_blocked_inline_pdf_writes_file(tmp_path: Path) -> None:
+ page = _RecoveryPage(main_srcs=["https://host.example/api/StatementPdf?access_token=secret"])
+ pdf_bytes = b"%PDF-1.7\n...statement bytes..."
+ with patch(_RECOVER_READ, AsyncMock(return_value=pdf_bytes)):
+ result = await _recover_blocked_inline_pdf_download(
+ page, tmp_path, workflow_run_id="wr_test", iframe_srcs_before=[]
+ )
+
+ assert result is not None
+ assert result.parent == tmp_path
+ assert result.suffix == ".pdf"
+ assert result.read_bytes() == pdf_bytes
+
+
+async def test_recover_passes_recovery_timeout_to_read_http_url_bytes(tmp_path: Path) -> None:
+ # The whole-operation 30s budget (authoritative outer asyncio cap) must not be undercut by the
+ # generic ~5s evaluate timeout: recovery reads each candidate with the 30s timeout forwarded
+ # into SkyvernFrame.evaluate so a slow-but-alive statement isn't rejected early.
+ page = _RecoveryPage(main_srcs=["https://host.example/api/StatementPdf?access_token=x"])
+ read_mock = AsyncMock(return_value=b"%PDF-1.7 statement")
+ with patch(_RECOVER_READ, read_mock):
+ result = await _recover_blocked_inline_pdf_download(
+ page, tmp_path, workflow_run_id="wr_test", iframe_srcs_before=[]
+ )
+
+ assert result is not None
+ assert read_mock.await_args.kwargs["timeout_ms"] == _BLOCKED_INLINE_PDF_RECOVERY_TIMEOUT_SECONDS * 1000
+
+
+async def test_recover_honors_download_suffix_naming(tmp_path: Path) -> None:
+ """The recovered file rejoins the block-configured download_suffix naming path (the common
+ real-world shape, since statement endpoints rarely end in .pdf)."""
+ page = _RecoveryPage(main_srcs=["https://host.example/api/StatementPdf?access_token=x"])
+ pdf_bytes = b"%PDF-1.7 statement"
+ ctx = MagicMock(download_suffix="mystatement", task_id="tsk_x")
+ with (
+ patch(_RECOVER_READ, AsyncMock(return_value=pdf_bytes)),
+ patch("skyvern.webeye.actions.handler.skyvern_context.current", return_value=ctx),
+ ):
+ result = await _recover_blocked_inline_pdf_download(
+ page, tmp_path, workflow_run_id="wr_test", iframe_srcs_before=[]
+ )
+
+ assert result is not None
+ assert result.name == "mystatement.pdf"
+ assert result.read_bytes() == pdf_bytes
+
+
+async def test_recover_returns_none_without_http_candidate(tmp_path: Path) -> None:
+ page = _RecoveryPage(main_srcs=["about:blank", "blob:https://host.example/x"])
+ fetch = AsyncMock()
+ with patch(_RECOVER_READ, fetch):
+ result = await _recover_blocked_inline_pdf_download(page, tmp_path, workflow_run_id=None, iframe_srcs_before=[])
+
+ assert result is None
+ fetch.assert_not_awaited() # nothing http(s) to fetch
+ assert list(tmp_path.iterdir()) == []
+
+
+async def test_recover_rejects_non_pdf_bytes(tmp_path: Path) -> None:
+ page = _RecoveryPage(main_srcs=["https://host.example/framed"])
+ with patch(_RECOVER_READ, AsyncMock(return_value=b"<html>content is blocked</html>")):
+ result = await _recover_blocked_inline_pdf_download(page, tmp_path, workflow_run_id=None, iframe_srcs_before=[])
+
+ assert result is None
+ assert list(tmp_path.iterdir()) == []
+
+
[email protected]("value", [b"", None])
+async def test_recover_rejects_empty_and_unrecoverable(tmp_path: Path, value: bytes | None) -> None:
+ page = _RecoveryPage(main_srcs=["https://host.example/x.pdf"])
+ with patch(_RECOVER_READ, AsyncMock(return_value=value)):
+ result = await _recover_blocked_inline_pdf_download(page, tmp_path, workflow_run_id=None, iframe_srcs_before=[])
+
+ assert result is None
+ assert list(tmp_path.iterdir()) == []
+
+
+async def test_recover_fails_closed_on_multiple_distinct_new_pdfs(tmp_path: Path) -> None:
+ # Two equally-plausible NEW inline PDFs appeared in the action window. Nothing
+ # ties either to the click, so recovery must fail closed rather than guess the
+ # first one (the #13898 first-PDF-wins bug reproduced in Phase 1's real browser).
+ page = _RecoveryPage(
+ main_srcs=[
+ "https://host.example/api/StatementPdf?access_token=a",
+ "https://host.example/api/StatementPdf?access_token=b",
+ ]
+ )
+
+ async def fake_read(_page: object, url: str, **_kwargs: object) -> bytes:
+ return b"%PDF-1.5 statement A" if url.endswith("=a") else b"%PDF-1.5 statement B"
+
+ with patch(_RECOVER_READ, side_effect=fake_read):
+ result = await _recover_blocked_inline_pdf_download(page, tmp_path, workflow_run_id=None, iframe_srcs_before=[])
+
+ assert result is None
+ assert list(tmp_path.iterdir()) == []
+
+
+async def test_recover_propagates_cancellation(tmp_path: Path) -> None:
+ page = _RecoveryPage(main_srcs=["https://host.example/x.pdf"])
+ with patch(_RECOVER_READ, AsyncMock(side_effect=asyncio.CancelledError())):
+ with pytest.raises(asyncio.CancelledError):
+ await _recover_blocked_inline_pdf_download(page, tmp_path, workflow_run_id=None, iframe_srcs_before=[])
+
+ assert list(tmp_path.iterdir()) == []
+
+
+async def test_recover_shares_one_budget_across_all_candidates(tmp_path: Path) -> None:
+ # Several slow candidate fetches share a single external budget (the shape handle_action wraps
+ # the call in): the whole operation is cancelled at that one deadline — the budget is not spent
+ # per-candidate — and it unwinds cleanly, writing nothing.
+ page = _RecoveryPage(main_srcs=[f"https://host.example/api/StatementPdf?doc={i}" for i in range(3)])
+
+ async def slow_read(*_args: object, **_kwargs: object) -> bytes:
+ await asyncio.sleep(0.2)
+ return b"%PDF-1.5 slow"
+
+ started = time.monotonic()
+ with patch(_RECOVER_READ, side_effect=slow_read):
+ with pytest.raises(asyncio.TimeoutError):
+ async with asyncio.timeout(0.05):
+ await _recover_blocked_inline_pdf_download(page, tmp_path, workflow_run_id=None, iframe_srcs_before=[])
+
+ assert time.monotonic() - started < 0.15 # one 0.05s budget, not 3 x 0.2s per candidate
+ assert list(tmp_path.iterdir()) == []
+
+
+async def test_recover_excludes_preexisting_pdf_and_recovers_newly_attached(tmp_path: Path) -> None:
+ # A benign decoy PDF iframe was already on the page before the click; the click
+ # attached the intended statement iframe. Only the newly-attached src is a
+ # candidate, so the decoy is never fetched or saved.
+ decoy = "https://host.example/api/decoy?doc=advert"
+ statement = "https://host.example/api/StatementPdf?access_token=fresh"
+ page = _RecoveryPage(main_srcs=[decoy, statement])
+ statement_bytes = b"%PDF-1.5 intended statement"
+ fetched: list[str] = []
+
+ async def fake_read(_page: object, url: str, **_kwargs: object) -> bytes:
+ fetched.append(url)
+ return statement_bytes if url == statement else b"%PDF-1.5 DECOY should never be read"
+
+ with patch(_RECOVER_READ, side_effect=fake_read):
+ result = await _recover_blocked_inline_pdf_download(
+ page, tmp_path, workflow_run_id="wr_test", iframe_srcs_before=[decoy]
+ )
+
+ assert result is not None
+ assert result.read_bytes() == statement_bytes
+ assert fetched == [statement] # decoy in the baseline was never fetched
+ assert len(list(tmp_path.iterdir())) == 1
+
+
+async def test_recover_finds_target_appended_past_many_preexisting_iframes(tmp_path: Path) -> None:
+ # A heavy portal with many pre-existing iframes (ads/trackers, plus a decoy PDF) and the intended
+ # statement appended LAST, past any arbitrary DOM-order cap. Uncapped enumeration must still see
+ # it: the target is recovered and the pre-existing decoy is excluded by the baseline.
+ decoy = "https://host.example/ads/decoy.pdf?doc=advert"
+ preexisting = [decoy] + [f"https://host.example/tracker/{i}.html" for i in range(12)]
+ statement = "https://host.example/api/StatementPdf?access_token=fresh"
+ page = _RecoveryPage(main_srcs=[*preexisting, statement])
+ statement_bytes = b"%PDF-1.5 intended statement past the cap"
+ fetched: list[str] = []
+
+ async def fake_read(_page: object, url: str, **_kwargs: object) -> bytes:
+ fetched.append(url)
+ return statement_bytes if url == statement else b"%PDF-1.5 decoy" if url == decoy else b"<html>tracker</html>"
+
+ with patch(_RECOVER_READ, side_effect=fake_read):
+ result = await _recover_blocked_inline_pdf_download(
+ page, tmp_path, workflow_run_id="wr_test", iframe_srcs_before=preexisting
+ )
+
+ assert result is not None
+ assert result.read_bytes() == statement_bytes
+ assert fetched == [statement] # only the newly-appended src is fetched; decoy/trackers excluded
+ assert len(list(tmp_path.iterdir())) == 1
+
+
+async def test_recover_names_extensionless_url_with_pdf_suffix(tmp_path: Path) -> None:
+ # A confirmed-PDF candidate whose URL has no path basename (".../?token=...") must still be
+ # persisted with a .pdf extension rather than an extension-less generic name.
+ src = "https://host.example/?token=abc"
+ page = _RecoveryPage(main_srcs=[src])
+
+ with patch(_RECOVER_READ, AsyncMock(return_value=b"%PDF-1.7 statement")):
+ result = await _recover_blocked_inline_pdf_download(
+ page, tmp_path, workflow_run_id="wr_test", iframe_srcs_before=[]
+ )
+
+ assert result is not None
+ assert result.suffix == ".pdf"
+ assert result.name.endswith(".pdf")
+
+
+async def test_recover_fails_closed_when_only_preexisting_pdf_remains(tmp_path: Path) -> None:
+ # Same-URL reload: the statement iframe was already present with this exact src
+ # before the click and the src is unchanged after. Nothing new appeared in the
+ # action window, so recovery fails closed rather than re-saving a stale frame.
+ statement = "https://host.example/api/StatementPdf?access_token=stale"
+ page = _RecoveryPage(main_srcs=[statement])
+
+ with patch(_RECOVER_READ, AsyncMock(return_value=b"%PDF-1.5 stale")) as fetch:
+ result = await _recover_blocked_inline_pdf_download(
+ page, tmp_path, workflow_run_id=None, iframe_srcs_before=[statement]
+ )
+
+ assert result is None
+ fetch.assert_not_awaited()
+ assert list(tmp_path.iterdir()) == []
+
+
+async def test_recover_recovers_reused_iframe_navigated_to_new_src(tmp_path: Path) -> None:
+ # An existing iframe navigated from an old src to a new statement src during the
+ # action window. The new src is not in the baseline, so it is recovered.
+ old_src = "https://host.example/api/StatementPdf?access_token=old"
+ new_src = "https://host.example/api/StatementPdf?access_token=new"
+ page = _RecoveryPage(main_srcs=[new_src])
+ new_bytes = b"%PDF-1.7 freshly navigated statement"
+
+ with patch(_RECOVER_READ, AsyncMock(return_value=new_bytes)):
+ result = await _recover_blocked_inline_pdf_download(
+ page, tmp_path, workflow_run_id="wr_test", iframe_srcs_before=[old_src]
+ )
+
+ assert result is not None
+ assert result.read_bytes() == new_bytes
+
+
+async def test_recover_fails_closed_on_two_urls_with_identical_bytes(tmp_path: Path) -> None:
+ # Two DISTINCT new candidate URLs both return byte-identical PDFs. They are still
+ # two equally-plausible candidates with nothing tying either to the click, so
+ # recovery must fail closed — identical bytes are not a license to pick one. (Exact
+ # duplicate srcs never reach here; _collect_inline_iframe_src_candidates dedupes by src.)
+ a = "https://host.example/api/StatementPdf?doc=1"
+ b = "https://host.example/api/StatementPdf?doc=2"
+ page = _RecoveryPage(main_srcs=[a, b])
+ same_bytes = b"%PDF-1.5 identical document bytes"
+
+ with patch(_RECOVER_READ, AsyncMock(return_value=same_bytes)):
+ result = await _recover_blocked_inline_pdf_download(page, tmp_path, workflow_run_id=None, iframe_srcs_before=[])
+
+ assert result is None
+ assert list(tmp_path.iterdir()) == []
+
+
+async def test_recover_requires_explicit_baseline(tmp_path: Path) -> None:
+ # The pre-click baseline is mandatory: without it, recovery would fall back to
+ # scanning every PDF on the page (the #13898 bug). Omitting it must be a hard error,
+ # never a silent global scan.
+ page = _RecoveryPage(main_srcs=["https://host.example/api/StatementPdf?access_token=x"])
+ with pytest.raises(TypeError):
+ await _recover_blocked_inline_pdf_download(page, tmp_path, workflow_run_id=None)
+
+
+async def test_handle_action_threads_preclick_iframe_baseline_into_recovery(tmp_path: Path) -> None:
+ # Recovery can only exclude pre-existing frames if it receives the iframe srcs
+ # captured BEFORE the click. Prove handle_action snapshots the baseline and threads
+ # it into _recover_blocked_inline_pdf_download.
+ now = datetime.now(UTC)
+ organization = make_organization(now)
+ task, step, page, browser_state, scraped_page, action = _make_download_click_context(
+ now=now, organization=organization, page_url="https://example.com/download"
+ )
+ task.download_timeout = 0.01
+ baseline = ["https://host.example/preexisting.pdf"]
+ seen: dict = {}
+
+ async def fake_recover(_page: object, _dir: object, *, workflow_run_id: object, iframe_srcs_before: object) -> None:
+ seen["baseline"] = iframe_srcs_before
+ return None
+
+ mock_app = MagicMock()
+ mock_app.BROWSER_MANAGER.get_for_task.return_value = browser_state
+ mock_app.DATABASE.workflow_params.create_action = AsyncMock(return_value=action)
+ mock_app.STORAGE = MagicMock()
+
+ with (
+ patch.object(ActionHandler, "_handle_action", new=AsyncMock(return_value=[ActionSuccess()])),
+ patch(
+ "skyvern.webeye.actions.handler._collect_inline_iframe_src_candidates",
+ new=AsyncMock(return_value=baseline),
+ ),
+ patch("skyvern.webeye.actions.handler._recover_blocked_inline_pdf_download", side_effect=fake_recover),
+ patch("skyvern.webeye.actions.handler.get_download_dir", return_value=str(tmp_path)),
+ patch("skyvern.webeye.actions.handler.skyvern_context.current", return_value=None),
+ patch(
+ "skyvern.webeye.actions.handler.check_downloading_files_and_wait_for_download_to_complete",
+ new=AsyncMock(),
+ ),
+ patch("skyvern.webeye.actions.handler.app", mock_app),
+ ):
+ results = await asyncio.wait_for(
+ ActionHandler.handle_action(scraped_page=scraped_page, task=task, step=step, page=page, action=action),
+ timeout=0.5,
+ )
+
+ assert seen["baseline"] == baseline
+ assert results[-1].download_triggered is False
+
+
+async def test_handle_action_skips_recovery_when_native_download_fires(tmp_path: Path) -> None:
+ # The blocked-inline recovery is a fallback for when NO download event fired. A
+ # normal native download must leave it untouched.
+ now = datetime.now(UTC)
+ organization = make_organization(now)
+ task, step, page, browser_state, scraped_page, action = _make_download_click_context(
+ now=now, organization=organization, page_url="https://example.com/download"
+ )
+ task.download_timeout = None
+
+ async def mock_inner_handle_action(*_args: object, **_kwargs: object) -> list[ActionSuccess]:
+ (tmp_path / "report.pdf").write_bytes(b"%PDF-1.7 native")
+ return [ActionSuccess()]
+
+ mock_app = MagicMock()
+ mock_app.BROWSER_MANAGER.get_for_task.return_value = browser_state
+ mock_app.DATABASE.workflow_params.create_action = AsyncMock(return_value=action)
+ mock_app.STORAGE = MagicMock()
+
+ with (
+ patch.object(ActionHandler, "_handle_action", side_effect=mock_inner_handle_action),
+ patch("skyvern.webeye.actions.handler._recover_blocked_inline_pdf_download") as recover,
+ patch("skyvern.webeye.actions.handler.get_download_dir", return_value=str(tmp_path)),
+ patch("skyvern.webeye.actions.handler.skyvern_context.current", return_value=None),
+ patch(
+ "skyvern.webeye.actions.handler.check_downloading_files_and_wait_for_download_to_complete",
+ new=AsyncMock(),
+ ),
+ patch("skyvern.webeye.actions.handler.app", mock_app),
+ ):
+ results = await asyncio.wait_for(
+ ActionHandler.handle_action(scraped_page=scraped_page, task=task, step=step, page=page, action=action),
+ timeout=0.5,
+ )
+
+ recover.assert_not_called()
+ assert results[-1].download_triggered is True
+ assert results[-1].downloaded_files == ["report.pdf"]
+
+
+async def test_handle_action_blocked_inline_recovery_is_time_bounded(tmp_path: Path) -> None:
+ # A hung same-origin fetch inside recovery must not out-wait the download loop it backstops.
+ # The whole recovery is bounded by one budget; on timeout handle_action falls through to the
+ # normal download-not-triggered follow-up rather than hanging or hard-failing.
+ now = datetime.now(UTC)
+ organization = make_organization(now)
+ task, step, page, browser_state, scraped_page, action = _make_download_click_context(
+ now=now, organization=organization, page_url="https://example.com/download"
+ )
+ task.download_timeout = 0.01
+ entered = asyncio.Event()
+
+ async def hung_recovery(*_args: object, **_kwargs: object) -> None:
+ entered.set()
+ await asyncio.Event().wait() # never returns
+
+ mock_app = MagicMock()
+ mock_app.BROWSER_MANAGER.get_for_task.return_value = browser_state
+ mock_app.DATABASE.workflow_params.create_action = AsyncMock(return_value=action)
+ mock_app.STORAGE = MagicMock()
+
+ with (
+ patch.object(ActionHandler, "_handle_action", new=AsyncMock(return_value=[ActionSuccess()])),
+ patch(
+ "skyvern.webeye.actions.handler._collect_inline_iframe_src_candidates",
+ new=AsyncMock(return_value=[]),
+ ),
+ patch("skyvern.webeye.actions.handler._recover_blocked_inline_pdf_download", side_effect=hung_recovery),
+ patch("skyvern.webeye.actions.handler._BLOCKED_INLINE_PDF_RECOVERY_TIMEOUT_SECONDS", 0.05),
+ patch("skyvern.webeye.actions.handler.get_download_dir", return_value=str(tmp_path)),
+ patch("skyvern.webeye.actions.handler.skyvern_context.current", return_value=None),
+ patch(
+ "skyvern.webeye.actions.handler.check_downloading_files_and_wait_for_download_to_complete",
+ new=AsyncMock(),
+ ),
+ patch("skyvern.webeye.actions.handler.app", mock_app),
+ ):
+ # A bound well under the outer wait_for proves handle_action self-bounds the hung recovery.
+ results = await asyncio.wait_for(
+ ActionHandler.handle_action(scraped_page=scraped_page, task=task, step=step, page=page, action=action),
+ timeout=1.0,
+ )
+
+ assert entered.is_set()
+ assert results[-1].download_triggered is False
+ assert results[-1].needs_followup is True
+ assert results[-1].followup_message == DOWNLOAD_NOT_TRIGGERED_FOLLOWUP_MESSAGE
diff --git a/tests/unit/test_read_blob_url_bytes.py b/tests/unit/test_read_blob_url_bytes.py
index 5987ba24c..9fabf1a4b 100644
--- a/tests/unit/test_read_blob_url_bytes.py
+++ b/tests/unit/test_read_blob_url_bytes.py
@@ -3,7 +3,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
-from skyvern.webeye.utils.page import SkyvernFrame
+from skyvern.webeye.utils.page import _SAME_ORIGIN_FETCH_JS, SkyvernFrame
_MOD = "skyvern.webeye.utils.page"
@@ -27,7 +27,7 @@ async def test_read_blob_url_bytes_rejects_oversized_blob() -> None:
assert result is None
# max size is threaded into the in-page arg so the guard runs before serialization
_page, _js, arg = eval_mock.await_args.args
- assert arg == {"blobUrl": "blob:https://example.com/big", "maxSizeBytes": 1024}
+ assert arg == {"url": "blob:https://example.com/big", "maxSizeBytes": 1024}
@pytest.mark.asyncio
@@ -164,3 +164,151 @@ async def test_read_blob_url_bytes_non_probe_logs_error_on_miss() -> None:
assert result is None
log_mock.error.assert_called()
+
+
+async def test_read_http_url_bytes_routes_main_frame_through_skyvern_frame_evaluate() -> None:
+ """The main-frame fetch goes through the unified SkyvernFrame.evaluate seam, targeting the
+ Page so the context-level main-world prefix stays attached (not a raw evaluate bypass)."""
+ page = MagicMock()
+ main_frame = MagicMock()
+ page.main_frame = main_frame
+ payload = b"%PDF-1.7 statement bytes"
+ eval_mock = AsyncMock(return_value={"ok": True, "base64": base64.b64encode(payload).decode()})
+
+ with (
+ patch(f"{_MOD}._frames_for_origin", return_value=[main_frame]),
+ patch.object(SkyvernFrame, "evaluate", eval_mock),
+ ):
+ result = await SkyvernFrame.read_http_url_bytes(
+ page=page, url="https://host.example/api/StatementPdf?access_token=x", max_size_bytes=1024
+ )
+
+ assert result == payload
+ eval_mock.assert_awaited_once()
+ kwargs = eval_mock.await_args.kwargs
+ assert kwargs["frame"] is page # main-frame targets the Page for main-world routing
+ assert kwargs["expression"] == _SAME_ORIGIN_FETCH_JS
+ assert kwargs["arg"] == {"url": "https://host.example/api/StatementPdf?access_token=x", "maxSizeBytes": 1024}
+
+
+async def test_read_http_url_bytes_forwards_timeout_ms_to_skyvern_frame_evaluate() -> None:
+ """The optional timeout_ms is forwarded to SkyvernFrame.evaluate so a caller (blocked-inline
+ PDF recovery) can widen past the generic ~5s action timeout without a per-candidate budget."""
+ page = MagicMock()
+ main_frame = MagicMock()
+ page.main_frame = main_frame
+ payload = b"%PDF-1.7 slow-but-alive statement"
+ eval_mock = AsyncMock(return_value={"ok": True, "base64": base64.b64encode(payload).decode()})
+
+ with (
+ patch(f"{_MOD}._frames_for_origin", return_value=[main_frame]),
+ patch.object(SkyvernFrame, "evaluate", eval_mock),
+ ):
+ result = await SkyvernFrame.read_http_url_bytes(page=page, url="https://host.example/x.pdf", timeout_ms=30_000)
+
+ assert result == payload
+ assert eval_mock.await_args.kwargs["timeout_ms"] == 30_000
+
+
+async def test_read_http_url_bytes_routes_sub_frame_through_skyvern_frame_evaluate() -> None:
+ """A same-origin sub-frame is routed through SkyvernFrame.evaluate targeting the Frame itself
+ (main-world prefix is page-scoped, so sub-frames evaluate in-frame)."""
+ page = MagicMock()
+ page.main_frame = MagicMock()
+ sub_frame = MagicMock()
+ payload = b"%PDF sub-frame bytes"
+ eval_mock = AsyncMock(return_value={"ok": True, "base64": base64.b64encode(payload).decode()})
+
+ with (
+ patch(f"{_MOD}._frames_for_origin", return_value=[sub_frame]),
+ patch.object(SkyvernFrame, "evaluate", eval_mock),
+ ):
+ result = await SkyvernFrame.read_http_url_bytes(page=page, url="https://host.example/x.pdf")
+
+ assert result == payload
+ kwargs = eval_mock.await_args.kwargs
+ assert kwargs["frame"] is sub_frame
+ assert kwargs["expression"] == _SAME_ORIGIN_FETCH_JS
+
+
+async def test_read_http_url_bytes_dispatches_sub_frame_to_frame_evaluate() -> None:
+ """End-to-end through the real SkyvernFrame.evaluate: a sub-frame target dispatches to
+ frame.evaluate (not the page main-world path)."""
+ page = MagicMock()
+ page.main_frame = MagicMock()
+ sub_frame = MagicMock()
+ payload = b"%PDF sub-frame bytes"
+ sub_frame.evaluate = AsyncMock(return_value={"ok": True, "base64": base64.b64encode(payload).decode()})
+
+ with patch(f"{_MOD}._frames_for_origin", return_value=[sub_frame]):
+ result = await SkyvernFrame.read_http_url_bytes(page=page, url="https://host.example/x.pdf")
+
+ assert result == payload
+ sub_frame.evaluate.assert_awaited_once()
+
+
+ "url",
+ [
+ "blob:https://host.example/abc",
+ "data:application/pdf;base64,AAAA",
+ "about:blank",
+ "javascript:void(0)",
+ "file:///etc/passwd",
+ "chrome-error://chromewebdata/",
+ ],
+)
+async def test_read_http_url_bytes_rejects_non_http_urls(url: str) -> None:
+ page = MagicMock()
+ with patch(f"{_MOD}._frames_for_origin") as frames:
+ result = await SkyvernFrame.read_http_url_bytes(page=page, url=url)
+
+ assert result is None
+ frames.assert_not_called() # scheme rejected before any frame lookup
+
+
+async def test_read_http_url_bytes_returns_none_without_same_origin_frame() -> None:
+ page = MagicMock()
+ page.main_frame = MagicMock()
+ with patch(f"{_MOD}._frames_for_origin", return_value=[]):
+ result = await SkyvernFrame.read_http_url_bytes(page=page, url="https://host.example/x.pdf")
+
+ assert result is None
+
+
+async def test_read_http_url_bytes_returns_none_when_fetch_not_ok() -> None:
+ page = MagicMock()
+ main_frame = MagicMock()
+ page.main_frame = main_frame
+ eval_mock = AsyncMock(return_value={"ok": False, "status": 403})
+
+ with (
+ patch(f"{_MOD}._frames_for_origin", return_value=[main_frame]),
+ patch(f"{_MOD}.evaluate_in_main_world", new=eval_mock),
+ ):
+ result = await SkyvernFrame.read_http_url_bytes(page=page, url="https://host.example/x.pdf")
+
+ assert result is None
+
+
+async def test_read_http_url_bytes_rejects_oversized() -> None:
+ page = MagicMock()
+ main_frame = MagicMock()
+ page.main_frame = main_frame
+ eval_mock = AsyncMock(return_value={"ok": False, "error": "too_large", "size": 999_999_999})
+
+ with (
+ patch(f"{_MOD}._frames_for_origin", return_value=[main_frame]),
+ patch(f"{_MOD}.evaluate_in_main_world", new=eval_mock),
+ ):
+ result = await SkyvernFrame.read_http_url_bytes(page=page, url="https://host.example/x.pdf", max_size_bytes=10)
+
+ assert result is None