A lot of apps have at least one screen that isn't native: a login, a payment form, a help page, rendered in a WebView. The first time I pointed Appium at one, the inspector showed a box with a few unnamed fields, my usual locators found nothing, and every guide I opened started talking about "contexts".
It turns out there are two ways in. I'll call them Mode 1 and Mode 2:
-
Mode 1, through the native tree. You stay in the
NATIVE_APPcontext and find the web form in the accessibility tree the OS builds for it. This works on any build, because the OS makes web content accessible anyway. -
Mode 2, through the DOM. The app lets a debugger attach to its WebView. A
WEBVIEW_…context appears, you switch into it, and from there it's basically Selenium: CSS selectors,execute_script, the real DOM. This only works if the app allows it.
Below I go through both, on iOS and on Android, against the same HTML form. Everything below was run with Appium 3.6.0 (XCUITest driver 11.17, UiAutomator2 driver 8.2) on an iPhone 17 simulator with iOS 27.0 and an Android 14 emulator. I drove the flows through Appium's W3C WebDriver endpoints directly; the snippets below are the same calls written with the Python client.
The practice screen
The form lives in ChaosBank, a deliberately buggy banking app I built for practicing mobile testing (intro post). Its login is a small HTML page loaded into a WKWebView on iOS and a WebView on Android:
<input id="web-username" type="text" />
<input id="web-password" type="password" />
<button id="web-submit" type="submit">Log in</button>
On submit, the page posts the credentials back to native code (WKScriptMessageHandler on iOS, addJavascriptInterface on Android), and the app moves on to a native OTP screen. So a test has to cross from native to web and back again, which is exactly what real apps make you do.
Two launch flags make it convenient to practice on:
# iOS (simulator launch arguments)
-ChaosBankShowWebLogin 1 # open the web login sheet right away
-ChaosBankInspectableWeb 1 # allow Mode 2
# Android (intent extras)
-e CHAOSBANK_SHOW_WEB_LOGIN 1
-e CHAOSBANK_INSPECTABLE_WEB 1
Without the second flag, the iOS app ships an "opaque" WebView and you're limited to Mode 1. With it, the app opts in to inspection:
if #available(iOS 16.4, *), LaunchOptions.current.inspectableWeb {
webView.isInspectable = true
}
if (LaunchOptions.current.inspectableWeb) {
WebView.setWebContentsDebuggingEnabled(true)
}
iOS, Mode 1: the native tree
The snippets use the Python client. Session setup:
from appium import webdriver
from appium.options.ios import XCUITestOptions
from appium.webdriver.common.appiumby import AppiumBy
options = XCUITestOptions().load_capabilities({
"platformName": "iOS",
"appium:automationName": "XCUITest",
"appium:udid": "<your simulator UDID>",
"appium:bundleId": "VadimToptunov.ChaosBank",
"appium:processArguments": {"args": ["-ChaosBankShowWebLogin", "1"]},
"appium:noReset": True,
"appium:forceAppLaunch": True,
})
driver = webdriver.Remote("http://127.0.0.1:4723", options=options)
print(driver.contexts) # ['NATIVE_APP']
Only NATIVE_APP: the WebView isn't inspectable, so there's nothing to switch into. A CSS selector fails here too, because in the native context there's no DOM to search.
What XCUITest does expose is the web form as native elements inside an XCUIElementTypeWebView: a text field, a secure text field and a button. Note what's missing: the HTML id attributes aren't there. So the locators are structural, scoped to the WebView:
user = driver.find_element(AppiumBy.IOS_CLASS_CHAIN,
"**/XCUIElementTypeWebView/**/XCUIElementTypeTextField")
password = driver.find_element(AppiumBy.IOS_CLASS_CHAIN,
"**/XCUIElementTypeWebView/**/XCUIElementTypeSecureTextField")
submit = driver.find_element(AppiumBy.IOS_CLASS_CHAIN,
"**/XCUIElementTypeWebView/**/XCUIElementTypeButton[`label == 'Log in'`]")
user.send_keys("tester")
password.send_keys("hunter2")
submit.click()
Keep every locator scoped to the WebView. My first version found the button with AppiumBy.ACCESSIBILITY_ID, "Log in", and it did find a "Log in" button. Just not this one: it was the native button on the screen behind the sheet, which has the same label. The tap went nowhere, and the test didn't fail until the next screen, where nothing made sense.
The same thing in plain XCUITest, as the ChaosBank × KassiOS reference suite does it:
let username = app.webViews.textFields.firstMatch
let password = app.webViews.secureTextFields.firstMatch
let submit = app.webViews.buttons
.matching(NSPredicate(format: "label == %@", "Log in"))
.firstMatch
iOS, Mode 2: the WEBVIEW context
Same session, plus the opt-in flag:
"appium:processArguments": {"args": [
"-ChaosBankShowWebLogin", "1",
"-ChaosBankInspectableWeb", "1",
]},
Now there are two contexts:
print(driver.contexts) # ['NATIVE_APP', 'WEBVIEW_65566.1']
The number after WEBVIEW_ is a process and page id. It changes from run to run, so don't hard-code it:
webview = next(c for c in driver.contexts if c.startswith("WEBVIEW"))
driver.switch_to.context(webview)
driver.find_element(AppiumBy.CSS_SELECTOR, "#web-username").send_keys("tester")
driver.find_element(AppiumBy.CSS_SELECTOR, "#web-password").send_keys("hunter2")
print(driver.execute_script("return document.getElementById('web-username').value")) # tester
driver.find_element(AppiumBy.CSS_SELECTOR, "#web-submit").click()
driver.switch_to.context("NATIVE_APP") # the OTP screen is native again
Inside the WebView you get the real ids, CSS selectors and JavaScript. The locators are the ones the web developers wrote, and you can read and set DOM state directly. The catch is that the app has to opt in. Also remember to switch back: the OTP screen after the login is native, and Appium won't find it from the WEBVIEW context.
Android, Mode 1: the native tree
from appium.options.android import UiAutomator2Options
options = UiAutomator2Options().load_capabilities({
"platformName": "Android",
"appium:automationName": "UiAutomator2",
"appium:appPackage": "com.vadimtoptunov.chaosbank_android",
"appium:appActivity": ".MainActivity",
"appium:optionalIntentArguments": "-e CHAOSBANK_SHOW_WEB_LOGIN 1",
"appium:noReset": True,
"appium:forceAppLaunch": True,
})
driver = webdriver.Remote("http://127.0.0.1:4723", options=options)
Android has one nice difference from iOS: UiAutomator2 exposes the HTML id of each form field as the native resource-id. The username field shows up in the page source as
<android.widget.EditText resource-id="web-username" text="" ... />
so you can locate it by id even without switching context. But not with the id strategy:
driver.find_element(AppiumBy.ID, "web-username") # NoSuchElementException
UiAutomator2's id strategy expects an Android resource id and qualifies a bare one with the app's package, so it looks for com.vadimtoptunov.chaosbank_android:id/web-username, which doesn't exist. Match the attribute exactly instead:
user = driver.find_element(AppiumBy.XPATH, "//android.widget.EditText[@resource-id='web-username']")
password = driver.find_element(AppiumBy.ANDROID_UIAUTOMATOR, 'new UiSelector().resourceId("web-password")')
submit = driver.find_element(AppiumBy.XPATH, "//android.webkit.WebView//android.widget.Button[@text='Log in']")
The fields also don't show up in the native tree right away. In my runs Appium found them about two seconds after the sheet opened, and a uiautomator dump taken right after launch showed a WebView with no fields in it at all. Wait for the element instead of assuming it's there.
Android, Mode 2: the WEBVIEW context
Add the opt-in extra and tell Appium which Chromedriver to use:
"appium:optionalIntentArguments": "-e CHAOSBANK_SHOW_WEB_LOGIN 1 -e CHAOSBANK_INSPECTABLE_WEB 1",
"appium:chromedriverExecutable": "/path/to/chromedriver_113",
print(driver.contexts) # ['NATIVE_APP', 'WEBVIEW_com.vadimtoptunov.chaosbank_android']
From here it's the same code as on iOS: switch, use CSS selectors, switch back. The one Android-specific piece is Chromedriver. Appium drives the WebView's DOM through Chromedriver, and its major version has to match the Chromium version of the device's WebView. My emulator has WebView 113.0.5672.136, and Chromedriver 113 was already on disk, so I pointed chromedriverExecutable at it. On a different device you'll need a different Chromedriver. Appium can download a matching one for you if you start the server with appium server --allow-insecure uiautomator2:chromedriver_autodownload.
A debug build always looks like Mode 2
This one surprised me. On Android, the WEBVIEW context showed up even without the flag:
# extras: only -e CHAOSBANK_SHOW_WEB_LOGIN 1
print(driver.contexts) # ['NATIVE_APP', 'WEBVIEW_com.vadimtoptunov.chaosbank_android']
That's Android, not Appium. WebView debugging is switched on automatically for any app built as debuggable, and every debug build is. setWebContentsDebuggingEnabled(true) only changes anything in a release build. So a Mode 2 test that passes on your debug build tells you nothing about the build users install, where only Mode 1 works. To check that, run it against a release build. I only verified the debug side here.
Things that cost me time
Some of these aren't about WebViews at all, but I ran into every one of them while checking the snippets above:
-
Launch arguments are ignored if the app is already running. With
noReset, Appium may attach to the running app instead of relaunching it, so a new-ChaosBankInspectableWeb 1never reaches it. The symptom was a session that started in two seconds and showed onlyNATIVE_APP.appium:forceAppLaunch: Truefixes it. -
A headless simulator can fail session creation. If the simulator is booted without its window, the XCUITest driver tries to restart it with the window visible and can time out with "Simulator is not in 'Shutdown' state".
appium:isHeadless: Truetells it to leave the simulator alone. - Scope your web locators to the WebView. Native screens behind a sheet or dialog can have elements with the same label.
- Wait for web content to show up in the native tree (Android especially).
-
Switch back to
NATIVE_APPbefore looking for native screens.
Mode 1 or Mode 2?
| Mode 1 (native tree) | Mode 2 (WEBVIEW context) | |
|---|---|---|
| Needs the app to opt in | no | yes (isInspectable / setWebContentsDebuggingEnabled, or a debug build on Android) |
HTML ids usable |
Android only, as resource-id
|
yes, plus CSS selectors |
| JavaScript and DOM state | no | yes |
| Extra moving parts | none | Chromedriver matching the WebView (Android) |
| Works on what users install | yes | usually not |
If the team owns the app and can ship a test build with inspection on, I'd write most WebView tests in Mode 2: the locators are better and you can check DOM state directly. But I'd keep at least one Mode 1 test on the critical path, because it's the only kind that runs against the real, opaque build.
And keep inspection out of production. An inspectable WebView with a login form in it lets anyone with a debugger attached read what's typed into it.
Try it yourself
Both ChaosBank apps are on GitHub, and the flags above open the login screen straight away. If you'd rather start from native XCUITest, the reference suite has a full login test that goes web login → OTP → passcode → home.
Top comments (2)
The point that a debug build on Android always exposes the WEBVIEW context is a good one, it quietly makes Mode 2 tests pass on a build users never get. On iOS, do you gate isInspectable behind a compile-time flag like #if DEBUG, or a launch argument that can still exist in a release binary?
It's a launch argument, not #if DEBUG. In ChaosBank that's deliberate — it's a practice range, so I flip -ChaosBankInspectableWeb 1 per run without a rebuild. The isInspectable = true in WebLoginView is guarded only by that flag, so you're right: the path is in the release binary too.
For a real app #if DEBUG is the stronger gate — the line just isn't there in release. One nuance vs Android though: an installed App Store build doesn't take external launch arguments the way adb am start -e does (they come from the Xcode scheme at dev time), so the real exposure is smaller than the Android case. Compile-time is still the right call for production.