fix: skip broken cross-origin iframe hierarchy reads by schmayterling · Pull Request #3289 · mobile-dev-inc/Maestro

schmayterling · 2026-05-14T02:23:05Z

Proposed changes

fixes a Maestro web hierarchy crash when cross-origin iframe enrichment hits transient browser state or malformed JS/CDP results.

see:

"status" : "FAILED",
  "error" : {
    "stackTrace" : [ {
      "methodName" : "fetchCrossOriginIframeContent",
      "fileName" : "CdpWebDriver.kt",
      "lineNumber" : 696,
      "className" : "maestro.drivers.CdpWebDriver"
    }, {
      "methodName" : "injectCrossOriginIframes",
      "fileName" : "CdpWebDriver.kt",
      "lineNumber" : 655,
      "className" : "maestro.drivers.CdpWebDriver"
    }, {
      "methodName" : "contentDescriptor",
      "fileName" : "CdpWebDriver.kt",
      "lineNumber" : 276,
      "className" : "maestro.drivers.CdpWebDriver"
    }, {
      "methodName" : "from-8JJjmZI",
      "fileName" : "ViewHierarchy.kt",
      "lineNumber" : 29,
      "className" : "maestro.ViewHierarchy$Companion"
    } ],
    "message" : "null cannot be cast to non-null type kotlin.collections.Map<kotlin.String, kotlin.Any>"
  }

from my understanding this usually happens after navigation, popup return, or iframe reload. the parent page is still usable, but a third-party iframe can be stale/closed/still loading/detached, or return null/malformed hierarchy data.

previously, that path used unsafe casts into Map<String, Any> and numeric fields, so one broken iframe could crash the whole hierarchy build.

this patch tries keeps the hierarchy path best-effort, see flow below

parse js/cdp hierarchy payloads with checked maps/lists instead of unsafe casts
reset selenium to default content before hierarchy and iframe reads
preserve readable cross-origin iframe content
keep the parent iframe node with empty children when iframe content is bad
treat stale frame, missing frame, and closed window errors as transient during iframe enrichment
keep the parent page hierarchy usable when a third-party iframe is broken

Testing

unit tests should cover:

null iframe content does not crash hierarchy construction
malformed iframe content does not crash hierarchy construction
transient iframe/window errors are swallowed and traversal continues
readable iframe content is still preserved and injected
malformed child nodes are skipped while valid siblings are preserved
missing iframe viewport params skip iframe content fetch

ran the following:

./gradlew :maestro-client:test --tests maestro.drivers.WebHierarchyTest -x :maestro-ios-driver:buildIosDriver
./gradlew :maestro-client:check -x :maestro-ios-driver:buildIosDriver
./gradlew detektMain

idt e2e is needed because there already is one for iframes

Issues fixed

fixes Looped flow fails when "coming back" to the main window. #3271
potentially related to Web: headless on windows fails on assertions #3136

Fishbowler · 2026-05-14T12:18:43Z

keep the parent iframe node with empty children when iframe content is bad

I'm concerned that this would lead to flaky tests. If run an assertVisible and the DOM is the parent content, but skipping the iframes, isn't there a chance my step will fail, but if I rerun it'll succeed?

Should we be handling failures in iframes with retry logic and eventual errors rather than silently eliding parts of the DOM?

schmayterling · 2026-05-14T12:34:41Z

keep the parent iframe node with empty children when iframe content is bad

I'm concerned that this would lead to flaky tests. If run an assertVisible and the DOM is the parent content, but skipping the iframes, isn't there a chance my step will fail, but if I rerun it'll succeed?

yeah, I think that can still happen for iframe-targeted assertions if the iframe is temporarily unavailable during that hierarchy snapshot. but yea the goal of this patch is to avoid crashing the entire hierarchy build when a third-party iframe is stale/broken/loading, and keep the rest of the page usable instead of failing with null cannot be cast ... which is causing flaky tests directly

Should we be handling failures in iframes with retry logic and eventual errors rather than silently eliding parts of the DOM?

I think retry/wait behavior for iframe content would need to happen at the assertion/command layer rather than inside hierarchy parsing itself. would be happy to see your thoughts with this perspective

proksh

Thanks @schmayterling

When iframe content is bad we keep the parent node but drop its children. An assertVisible targeting iframe content could fail on one snapshot and pass on rerun → flaky. We have stopped accepting pull requests that results in flaky test, so that will stop us to approve this PR. Do you have a solution that can be consistent?
Rebase to main and revert the part either of #3314 or #3315 covers.
Suggest rebasing on top of #3314 + #3315 once they merge so the diff shrinks to just the parsing/enrichment fix.

proksh · 2026-05-26T10:49:06Z

        // ChromeDriver can execute scripts inside cross-origin iframes via switchTo().frame()
-        driver.switchTo().frame(iframeElement)
        return try {
+            driver.switchTo().frame(iframeElement)


This reordering - moving switchTo().frame() inside the try so a StaleElementReferenceException degrades to null - is exactly #3314. Let's revert it here and rebase on main to avoid two copies of the same fix.

proksh · 2026-05-26T10:51:28Z

+        val params = WebHierarchy.parseIframeViewportParams(paramsJson, iframeSrc) ?: return null

        // ChromeDriver can execute scripts inside cross-origin iframes via switchTo().frame()
-        driver.switchTo().frame(iframeElement)


Same as above. This reordering - moving switchTo().frame() inside the try so a StaleElementReferenceException degrades to null - is exactly #3314. Let's revert it here and rebase on main to avoid two copies of the same fix.

proksh · 2026-05-26T10:52:55Z

+        return TreeNode(attributes = attributes, children = children)
+    }
+
+    fun isTransientBrowserContextError(e: Throwable): Boolean {


This classifies Selenium exceptions as transient - which is what #3315's SeleniumExceptionTranslator is for, at the Driver boundary. Once #3315 lands, callers won't see raw org.openqa.selenium.* here. Suggest removing this and the logWebHierarchyFailure / logIframeFetchFailure helpers that depend on it, and letting #3315 own the classification.

proksh · 2026-05-26T10:54:17Z

+        }
+    }
+
+    private fun logWebHierarchyFailure(message: String, e: Exception) {


Tied to the classification in WebHierarchy - drop with isTransientBrowserContextError. After #3315, transient/infra failures don't reach this logging path.

proksh · 2026-05-26T10:55:43Z

-        val rawMap = contentDesc as Map<String, Any>
-        val enrichedMap = injectCrossOriginIframes(rawMap)
-        val root = parseDomAsTreeNodes(enrichedMap)
+        val rawMap = WebHierarchy.normalizeDomNode(contentDesc, "web content description")


This is the part to keep. Replacing contentDesc as Map<String, Any> (and the casts inside the old parseDomAsTreeNodes) with checked parsing is what stops the null cannot be cast to non-null type Map crash. Neither #3314 nor #3315 touches this.

proksh · 2026-05-26T10:57:05Z


-        val options = driver.capabilities.getCapability("goog:chromeOptions") as Map<String, Any>
-        val debuggerAddress = options["debuggerAddress"] as String
+        val options = driver.capabilities.getCapability("goog:chromeOptions") as? Map<*, *>


Nice defensive cast - keep. Independent of the iframe work.

proksh · 2026-05-26T11:01:29Z

                webScreenRecorder?.onWindowChange()
            }
        }
+        if (windowHandles.isNotEmpty()) {


This window-handle fallback in detectWindowChange is a meaningful behavior change beyond the iframe-crash fix. Is it required for #3271, or is it scope that could be its own PR? Easier to review/revert if split out. (Also overlaps conceptually with #3315's NoSuchSessionException / unreachable handling — worth checking they don't fight.)

proksh · 2026-05-27T06:34:42Z

-        return when (query) {
-            is OnDeviceElementQuery.Css -> queryCss(query)
-            else -> super.queryOnDeviceElements(query)
+        if (query is OnDeviceElementQuery.Css) {


Why were these changes needed?

proksh · 2026-05-27T06:39:09Z

+                }
+            }
+
+            return mapOf(


This is the silent-elision behavior @Fishbowler flagged: when iframe content is bad we keep the parent node but drop its children. An assertVisible targeting iframe content could fail on one snapshot and pass on rerun → flaky.

You already noted retry/wait belongs at the command/assertion layer - agree, but we will prefer a solution that is consistent. We have stopped merging things that results in flaky results.

schmayterling added 7 commits May 14, 2026 09:15

fix cross-origin iframe hierarchy parsing

5f835f9

clean up web hierarchy failure handling

7047f3e

tighten web hierarchy iframe fallback behavior

c490304

remove web driver semicolon churn

ed42b2b

remove redundant web hierarchy wrappers

7053454

narrow web hierarchy normalization scope

ff0fbac

trim iframe hierarchy logging

4b5d510

schmayterling changed the title ~~May/fix cdp crash~~ fix: skip broken cross-origin iframe hierarchy reads May 14, 2026

Fishbowler mentioned this pull request May 22, 2026

fix(web): handle stale iframe in fetchCrossOriginIframeContent #3314

Merged

proksh reviewed May 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: skip broken cross-origin iframe hierarchy reads#3289

fix: skip broken cross-origin iframe hierarchy reads#3289
schmayterling wants to merge 7 commits into
mobile-dev-inc:mainfrom
schmayterling:may/fix-cdp-crash

schmayterling commented May 14, 2026

Uh oh!

Fishbowler commented May 14, 2026

Uh oh!

schmayterling commented May 14, 2026

Uh oh!

proksh left a comment

Uh oh!

proksh May 26, 2026

Uh oh!

proksh May 26, 2026

Uh oh!

proksh May 26, 2026

Uh oh!

proksh May 26, 2026

Uh oh!

proksh May 26, 2026

Uh oh!

proksh May 26, 2026

Uh oh!

proksh May 26, 2026

Uh oh!

proksh May 27, 2026

Uh oh!

proksh May 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

schmayterling commented May 14, 2026

Proposed changes

Testing

Issues fixed

Uh oh!

Fishbowler commented May 14, 2026

Uh oh!

schmayterling commented May 14, 2026

Uh oh!

proksh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants