webdriverio
Version:
Next-gen browser and mobile automation test framework for Node.js
112 lines • 7.06 kB
TypeScript
import type { SwitchContextOptions } from '../../types.js';
/**
* 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](/docs/api/mobile#hybrid-apps).
* 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()`.
*
* :::info 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.
*
* :::
*
* <example>
: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')
})
* </example>
*
* <example>
: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',
})
})
* </example>
*
* <example>
: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',
})
})
* </example>
*
* <example>
: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/,
})
})
* </example>
*
* <example>
: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
})
})
* </example>
*
* @param {string|SwitchContextOptions} context The name of the context to switch to. An object with more context options can be provided.
* @param {SwitchContextOptions} options switchContext command options
* @param {string|RegExp=} options.title 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.<br /><strong>IMPORTANT:</strong> When you use options then or the `title` or the `url` property is required.
* @param {string|RegExp=} options.url 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.<br /><strong>IMPORTANT:</strong> When you use options then or the `title` or the `url` property is required.
* @param {number=} options.androidWebviewConnectionRetryTime The time in milliseconds to wait between each retry to connect to the webview. Default is `500` ms (optional). <br /><strong>ANDROID-ONLY</strong> and will only be used when a `title` or `url` is provided.
* @param {number=} options.androidWebviewConnectTimeout The maximum amount of time in milliseconds to wait for a web view page to be detected. Default is `5000` ms (optional). <br /><strong>ANDROID-ONLY</strong> and will only be used when a `title` or `url` is provided.
* @skipUsage
*/
export declare function switchContext(this: WebdriverIO.Browser, options: string | SwitchContextOptions): Promise<void>;
//# sourceMappingURL=switchContext.d.ts.map