Hybrid sessions lose webview DOM capture: native detection is fixed at session start

isNativeAppSession answers from startup capabilities and is never revisited, so a session's answer is fixed for its whole lifetime. A hybrid app switched into a webview context does have a document, and every page-side guard keyed on that predicate keeps skipping.

Raised by review on #375 (thread). Filed rather than fixed there: the fix is outside that PR's scope and cannot be verified without a hybrid app on a real device.

Not new, but newly load-bearing

The residual is declared in the predicate's own docstring, and has been since the service's version landed in #371:

Residual: a hybrid app switched into a webview context does have a document, and no capability can say so — only getContext() knows that.

What #375 changes is how much rides on it. Before it, selenium-devtools, nightwatch-devtools and selenium-devtools-py gated nothing — every page-side call was attempted unconditionally, so a hybrid session's webview portion was captured by accident. After it, those adapters gate collector injection, the DOM drain, the performance read and the per-action snapshot on a predicate that answers "native" for the whole session. The webview portion of the trace therefore carries no DOM evidence.

None of the three claims native support today, so this is an unimplemented case rather than a promise broken — but it is a real behaviour change for anyone driving a hybrid app through them.

Why the obvious fix is wrong

Ungating is not the answer. Treating a document-less session as web is the expensive direction: the service's post-action settle reads a page tag, treats the failure as a navigation, then polls a probe that can only fail for its full 8 s timeout, per action. That is #351 (40-60 s per run in per-action probes), and it is what #350/#372 exist to remove. Protecting hybrid by ungating would restore that cost for every pure-native user.

The shape of a fix

Document availability has to follow the current runtime context, not the startup bag:

• Appium exposes getContext() / getContexts(); the active context is NATIVE_APP or a WEBVIEW_* string.
• It cannot be read per guard — that is a round trip on the hot path, which reintroduces the cost above in a different form. It has to be cached and invalidated when the context changes.
• The invalidation point is the context-switch command itself, which every adapter already sees in its command hook.

There is no runtime-context awareness anywhere in the repo today. Grepping getContext|currentContext|NATIVE_APP|WEBVIEW|setContext|switchContext across packages/*/src returns only:

• core/element-snapshot.ts — an android.webkit.WebView entry in the class-name → role map, and 'webview' in a role list.
• core/locators/xml-parsing.ts — a comment about WebView content in page source.
• nightwatch-devtools/src/constants.ts — currentContext as an entry in INTERNAL_COMMANDS_TO_IGNORE, i.e. Nightwatch's own command filtered out of the action list, not detection.

Scope

• A context-aware document-availability answer, cached and invalidated on context switch, sitting beside isNativeAppSession rather than replacing it — the capability answer is still the right one at bringup, before any context exists.
• service, selenium-devtools, nightwatch-devtools, selenium-devtools-py consume it at the sites #372 gated.
• Verified on a real hybrid app: a trace whose webview portion carries DOM, mutations and element snapshots, and whose native portion still costs no failed round trips.
• Decide what a webview→native switch does to an already-injected collector.

Verification needs a hybrid app on a real device or a device cloud; CI cannot cover it, so the PR should state what was run and on what.

Related

• #372 — the cross-adapter gating this follows from.
• #371, #350 — the WDIO-side work, where the residual was first documented.
• #351 — the per-action probe cost that makes ungating the wrong fix.

Start by locating isNativeAppSession and the gating sites introduced by #372 across service, selenium-devtools, nightwatch-devtools, and selenium-devtools-py; then inspect each adapter's context-switch command hook. Done means cached context-aware availability preserves native fast paths, captures DOM, mutations, and snapshots in webviews, handles webview-to-native transitions, and is verified on a real hybrid app or device cloud.