switchContext

Switch to a specific context using a given Webview name, title, or url.

This method enhances the default Appium context command by offering more flexibility and precision for switching between native and webview contexts in hybrid mobile applications.

How Contexts Work

For an overview of Hybrid Apps and webviews, refer to the Hybrid Apps documentation. Below is a summary of how the switchContext command addresses common challenges:

Android Challenges

• Webviews often contain multiple pages (similar to browser tabs). Identifying the correct page requires additional metadata such as title or url, which is not provided by default Appium methods.
• Default Appium methods return only basic context names (e.g., WEBVIEW_{packageName}) without details about the content or pages within the webview.
• Switching contexts on Android involves two steps, which are handled automatically by this method:
  1. Switch to the Webview context using WEBVIEW_{packageName}.
  2. Select the appropriate page within the Webview using the switchToWindow method.

iOS Challenges

• Webviews are identified by generic IDs (e.g., WEBVIEW_{id}), which do not provide information about the content or the app screen they correspond to.
• Determining the correct webview for interaction often requires trial and error.

The switchContext method simplifies this process by retrieving detailed metadata (e.g., title, url, and visibility) to ensure accurate and reliable context switching.

Why Use This Method?

• Simplified Switching: If you know the title or url of the desired webview, this method eliminates the need for additional calls to getContexts or combining multiple methods like switchContext({id}) and getTitle().
• Automatic Context Matching: Finds the best match for a context based on:
  • Platform-specific identifiers (bundleId for iOS, packageName for Android).
  • Exact or partial matches for title or url (supports both strings and regular expressions).
  • Android-specific checks to ensure webviews are attached and visible.
• Fine-Grained Control: Custom retry intervals and timeouts (Android-only) allow you to handle delays in webview initialization.
• Default Appium Method Access: If needed, you can use the default Appium switchContext command via driver.switchAppiumContext().

Notes and Limitations

• If the title or url of the desired webview is known, this method can automatically locate and switch to the matching context without additional getContexts calls.
• Android-specific options like androidWebviewConnectionRetryTime and androidWebviewConnectTimeout are not applicable to iOS.
• Logs reasons for context-matching failures to assist with debugging.
• When using an object as input, either title or url is required.

Parameters

Name	Type	Details
context	string, SwitchContextOptions	The name of the context to switch to. An object with more context options can be provided.
options	SwitchContextOptions	switchContext command options
options.title	string, RegExp	The title of the page to switch to. This will be the content of the title-tag of a webviewpage. You can use a string that needs to fully match or or a regular expression. IMPORTANT: When you use options then or the title or the url property is required.
options.url	string, RegExp	The url of the page to switch to. This will be the url of a webviewpage. You can use a string that needs to fully match or or a regular expression. IMPORTANT: When you use options then or the title or the url property is required.
options.androidWebviewConnectionRetryTime optional	number	The time in milliseconds to wait between each retry to connect to the webview. Default is 500 ms (optional). ANDROID-ONLY and will only be used when a title or url is provided.
options.androidWebviewConnectTimeout optional	number	The maximum amount of time in milliseconds to wait for a web view page to be detected. Default is 5000 ms (optional). ANDROID-ONLY and will only be used when a title or url is provided.

Examples

example.test.js

it('should switch to a webview by name and uses the default Appium `context`-method', async () => {
    // For Android, the context will be '`WEBVIEW_{packageName}`'
    await driver.switchContext('WEBVIEW_com.wdiodemoapp')
    // For iOS, the context will be 'WEBVIEW_{number}'
    await driver.switchContext('WEBVIEW_94703.19')
})

exact.title.test.js

it('should switch to a webview and match a webview based on an EXACT match of the `title` of the webview', async () => {
    await driver.switchContext({
        // In this case the title needs to be an exact match
        title: 'Webview Title',
    })
})

exact.url.test.js

it('should switch to a webview and match a webview based on an EXACT match of the `title` of the webview', async () => {
    await driver.switchContext({
        // In this case the url needs to be an exact match
        url: 'https://webdriver.io',
    })
})

regex.title.url.test.js

it('should switch to a webview and match a webview based on regex match of the `title` and `url` of the webview', async () => {
    await driver.switchContext({
        // The title should NOT end with 'foo'
        title: /^(?!.*foo$)/,
        // Matches any string that contains the substring `docs/api/mobile/switchContext`
        url: /.*docs\/api\/mobile\/switchContext/,
    })
})

android.context.waits.test.js

it('should switch to a webview for Android but wait longer to connect and find a webview based on provided options', async () => {
    await driver.switchContext({
        // In this case the title need to be an exact match
        title: 'Webview Title',
        // For Android we might need to wait a bit longer to connect to the webview, so we can provide some additional options
        androidWebviewConnectionRetryTime: 1*1000,  // Retry every 1 second
        androidWebviewConnectTimeout: 10*1000,      // Timeout after 10 seconds
    })
})