Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 37 ยท Android and iOS Specifics

Hybrid Apps and WebViews: Switching Contexts

Test hybrid mobile apps with Appium: list contexts, switch between NATIVE_APP and WEBVIEW, set up ChromeDriver, and use web locators inside embedded pages.

Many apps are not purely native. A checkout page, a help center, a login provider or even the whole app may be a web page shown inside a WebView, a native component that embeds a browser engine. The native driver sees a WebView as one big opaque element, so it cannot find a button inside the page. To test that content you have to change the context: the part of the app Appium is talking to.

This lesson explains contexts, how to switch safely, what each platform needs behind the scenes, and how to test mobile Safari or Chrome as the "app" itself.

Appium and devices cannot run on this site. The Appium code is read-only; the runnable examples simulate the context list and the waiting loop so you can practice the logic.

Two worlds: native and web

Every session starts in the NATIVE_APP context. In that context you use native locators (accessibility ID, resource ID, predicates). A web context is named WEBVIEW_ plus an identifier, and inside it Appium behaves like Selenium: CSS selectors, XPath on the DOM, get(url) and JavaScript execution.

Python
print(driver.contexts)
# for example: ['NATIVE_APP', 'WEBVIEW_com.example.shop']
print(driver.current_context)
# 'NATIVE_APP'

Platform differences in the names:

  • Android: WEBVIEW_<package name>, for example WEBVIEW_com.example.shop. Chrome itself appears as WEBVIEW_chrome. Several WebViews in one app can show up as additional entries, sometimes with a :<page> suffix.
  • iOS: WEBVIEW_<number>, for example WEBVIEW_12345.1. The number changes every run, so never hard-code it.

Switching, and switching back

Python
from appium.webdriver.common.appiumby import AppiumBy
from selenium.webdriver.common.by import By

driver.find_element(AppiumBy.ACCESSIBILITY_ID, "Open help center").click()

webview = next(c for c in driver.contexts if c.startswith("WEBVIEW"))
driver.switch_to.context(webview)

driver.find_element(By.CSS_SELECTOR, "input[name='q']").send_keys("refund")
driver.find_element(By.CSS_SELECTOR, "button[type='submit']").click()

driver.switch_to.context("NATIVE_APP")
driver.find_element(AppiumBy.ACCESSIBILITY_ID, "Back").click()

Switching is not instant: the WebView may not exist yet, and the page may still be loading. The list of contexts changes while the app navigates. A robust test waits until a web context appears, then switches. The next section builds that wait as a stand-in.

Stand-in: wait for a context

Real tests poll driver.contexts. This stand-in uses a fake driver whose WebView appears after a few polls, so you can see the pattern and the failure message.

Python Waiting for a WebView (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The point is the loop with a limit and a clear error message, instead of a switch that fails with a vague "context not found".

What the platforms need

Android uses ChromeDriver to talk to the WebView, and the ChromeDriver version must match the Chrome or WebView version on the device. The common options:

JSON
{
  "appium:chromedriverAutodownload": true,
  "appium:chromedriverExecutable": "/opt/chromedrivers/chromedriver-130",
  "appium:autoWebview": false,
  "appium:webviewConnectTimeout": 10000
}

chromedriverAutodownload downloads a matching driver, but it is an insecure feature that you must enable on the server: appium --allow-insecure=uiautomator2:chromedriver_autodownload. In the app itself, the developers must call WebView.setWebContentsDebuggingEnabled(true), usually in debug builds only; without it the WebView is invisible to automation.

iOS reaches WebViews through Safari's remote debugging, which the XCUITest driver handles. On simulators it just works. On real devices, Web Inspector must be enabled in Settings, Safari, Advanced. Set appium:includeSafariInWebviews to see Safari tabs as contexts.

Testing a mobile browser

You can also automate the browser instead of an app by setting browserName:

Python
from appium.options.android import UiAutomator2Options

options = UiAutomator2Options()
options.platform_name = "Android"
options.browser_name = "Chrome"
driver = webdriver.Remote("http://127.0.0.1:4723", options=options)
driver.get("https://example.com")

On iOS use Safari. Here the session starts directly in a web context, and all Selenium commands apply.

Window handles versus contexts

Do not confuse the two. A context switches between native and web worlds. A window handle (driver.window_handles, switch_to.window) switches between browser tabs inside a web context. When a link opens a new tab inside a WebView, first make sure you are in the web context, then switch the window.

Stand-in: choose the right context

Python Which locator for which context? (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Troubleshooting

  • contexts shows only NATIVE_APP: debugging is not enabled in the app, the page has not loaded, or on iOS Web Inspector is off.
  • "No Chromedriver found that can automate Chrome": the driver version does not match; supply chromedriverExecutable or enable autodownload.
  • Elements are found but clicks miss: after scrolling a web page the native overlay can sit on top; try the JavaScript click driver.execute_script("arguments[0].click()", el).
  • Tests become flaky after a redirect: re-read driver.contexts after navigation, because the WebView name may change.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which context does every Appium session start in?

    The session starts in NATIVE_APP; you must switch to a WEBVIEW context to use web locators.
  2. 2. Why should you not hard-code an iOS WebView context name?

    iOS names look like WEBVIEW_12345.1 and the number differs each run, so pick one from driver.contexts.
  3. 3. Which locator works in a WebView context?

    Inside a web context Appium behaves like Selenium, so CSS and XPath apply.
  4. 4. What must developers enable so that Android WebViews are visible to automation?

    WebView.setWebContentsDebuggingEnabled(true), typically in debug builds.

Summary

  • Native and web content live in different contexts; driver.contexts lists them and switch_to.context changes them.
  • Wait for the web context to appear instead of switching immediately, and switch back to NATIVE_APP for native controls.
  • Android needs a matching ChromeDriver and a debuggable WebView; iOS needs Web Inspector on real devices.
  • Contexts are not window handles: contexts pick the world, handles pick the tab.

Next: Device Features: Permissions, Location, Biometrics and Deep Links