feat: enhance getContext(s)|switchContext (webdriverio#14958)

* feat: add custom app identifier for switchContext

* feat: add waitForWebviewMs for Android

Author: wswebcreation

packages/webdriverio/src/commands/mobile/getContext.ts

@@ -1,7 +1,6 @@
 import logger from '@wdio/logger'
 import type { Context, DetailedContext } from '@wdio/protocols'
-
-import type { AppiumDetailedCrossPlatformContexts } from '../../types.js'
+import type { AppiumDetailedCrossPlatformContexts, GetContextsOptions } from '../../types.js'
 
 const log = logger('webdriver')
 
@@ -99,10 +98,23 @@ const log = logger('webdriver')
     })
  * </example>
  *
+ * <example>
+ *    :wait.for.webview.test.js
+ *    it('should wait for webview to become available before retrieving context', async () => {
+ *        // For Android
+ *        await driver.getContext({
+ *            returnDetailedContext: true,
+ *            // Wait for webview to become available at the Appium level before WebdriverIO's retry logic
+ *            waitForWebviewMs: 3000,  // Wait 3 seconds for webview to become available
+ *        })
+ *    })
+ * </example>
+ *
  * @param {GetContextsOptions=} options                                     The `getContext` options (optional)
  * @param {boolean=}            options.returnDetailedContext               By default, we only return the context name based on the default Appium `context` API, which is only a string. If you want to get back detailed context information, set this to `true`. Default is `false` (optional).
  * @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>
  * @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>
+ * @param {number=}             options.waitForWebviewMs                    The time in milliseconds to wait for webviews to become available before returning contexts. This parameter is passed directly to the Appium `mobile: getContexts` command. Default is `0` ms (optional). <br /><strong>ANDROID-ONLY</strong> <br />This is useful when you know that a webview is loading but needs additional time to become available. This option works at the Appium level, before WebdriverIO's retry logic (`androidWebviewConnectionRetryTime` and `androidWebviewConnectTimeout`) is applied.
  * @skipUsage
  */
 export async function getContext(
@@ -111,6 +123,7 @@ export async function getContext(
         returnDetailedContext?: boolean,
         androidWebviewConnectionRetryTime?: number,
         androidWebviewConnectTimeout?: number,
+        waitForWebviewMs?: number,
     }
 ): Promise<string | DetailedContext> {
     const browser = this
@@ -133,10 +146,10 @@ export async function getContext(
 async function getDetailedContext(
     browser: WebdriverIO.Browser,
     currentAppiumContext: string,
-    options?: { androidWebviewConnectionRetryTime?: number, androidWebviewConnectTimeout?: number },
+    options?: Pick<GetContextsOptions, 'androidWebviewConnectionRetryTime' | 'androidWebviewConnectTimeout' | 'waitForWebviewMs'>,
 ): Promise<string | DetailedContext> {
     const detailedContexts = await browser.getContexts({
-        ...{ options },
+        ...options,
         // Defaults
         returnDetailedContexts: true,           // We want to get back the detailed context information
         isAndroidWebviewVisible: true,          // We only want to get back the visible webviews

packages/webdriverio/src/commands/mobile/getContexts.ts

@@ -150,13 +150,26 @@ const log = logger('webdriver')
     })
  * </example>
  *
+ * <example>
+ *    :wait.for.webview.test.js
+ *    it('should wait for webview to become available before retrieving contexts', async () => {
+ *        // For Android
+ *        await driver.getContexts({
+ *            returnDetailedContexts: true,
+ *            // Wait for webview to become available at the Appium level before WebdriverIO's retry logic
+ *            waitForWebviewMs: 3000,  // Wait 3 seconds for webview to become available
+ *        })
+ *    })
+ * </example>
+ *
  * @param {GetContextsOptions=} options                                     The `getContexts` options (optional)
  * @param {boolean=}            options.returnDetailedContexts              By default, we only return the context names based on the default Appium `contexts` API. If you want to get all data, you can set this to `true`. Default is `false` (optional).
  * @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>
  * @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>
  * @param {boolean=}            options.filterByCurrentAndroidApp           By default, we return all webviews. If you want to filter the webviews by the current Android app that is opened, you can set this to `true`. Default is `false` (optional). <br /><strong>NOTE:</strong> Be aware that you can also NOT find any Webview based on this "restriction". <br /><strong>ANDROID-ONLY</strong>
  * @param {boolean=}            options.isAndroidWebviewVisible             By default, we only return the webviews that are attached and visible. If you want to get all webviews, you can set this to `false` (optional). Default is `true`. <br /><strong>ANDROID-ONLY</strong>
  * @param {boolean=}            options.returnAndroidDescriptionData        By default, no Android Webview (Chrome) description description data. If you want to get all data, you can set this to `true`. Default is `false` (optional). <br />By enabling this option you will get extra data in the response, see the `description.data.test.js` for more information. <br /><strong>ANDROID-ONLY</strong>
+ * @param {number=}             options.waitForWebviewMs                    The time in milliseconds to wait for webviews to become available before returning contexts. This parameter is passed directly to the Appium `mobile: getContexts` command. Default is `0` ms (optional). <br /><strong>ANDROID-ONLY</strong> <br />This is useful when you know that a webview is loading but needs additional time to become available. This option works at the Appium level, before WebdriverIO's retry logic (`androidWebviewConnectionRetryTime` and `androidWebviewConnectTimeout`) is applied.
  * @skipUsage
  */
 export async function getContexts(
@@ -220,6 +233,7 @@ type GetCurrentContexts = {
     filterByCurrentAndroidApp: boolean;
     isAndroidWebviewVisible: boolean;
     returnAndroidDescriptionData: boolean;
+    waitForWebviewMs?: number;
 }
 
 type ParsedAndroidContexts = {
@@ -380,8 +394,11 @@ async function getCurrentContexts({
     filterByCurrentAndroidApp,
     isAndroidWebviewVisible,
     returnAndroidDescriptionData,
+    waitForWebviewMs,
 }: GetCurrentContexts): Promise<AppiumDetailedCrossPlatformContexts> {
-    const contexts = await browser.execute('mobile: getContexts') as IosDetailedContext[] | AndroidChromeInternalContexts
+    const contexts = await (waitForWebviewMs !== undefined
+        ? browser.execute('mobile: getContexts', { waitForWebviewMs })
+        : browser.execute('mobile: getContexts')) as IosDetailedContext[] | AndroidChromeInternalContexts
 
     // The logic for iOS is clear, we can just return the contexts which will be an array of objects with more data (see the type) instead of only strings
     if (browser.isIOS) {

packages/webdriverio/src/commands/mobile/switchContext.ts

@@ -35,7 +35,7 @@ const log = logger('webdriver')
  * - **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).
+ *   - Platform-specific identifiers (`bundleId` for iOS, `packageName` for Android). By default, uses the active app identifier, but you can provide a custom `appIdentifier` to search in a specific app (useful for overlays or non-active apps).
  *   - 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.
@@ -105,8 +105,25 @@ const log = logger('webdriver')
     })
  * </example>
  *
+ * <example>
+ *    :app.identifier.test.js
+ *    it('should switch to a webview by providing a specific app identifier (bundleId for iOS or packageName for Android)', async () => {
+ *        // For Android, provide the packageName to search in a specific app (useful for overlays or non-active apps)
+ *        await driver.switchContext({
+ *            appIdentifier: 'com.otherApp',
+ *            title: 'Other Apps',
+ *        })
+ *        // For iOS, provide the bundleId to search in a specific app
+ *        await driver.switchContext({
+ *            appIdentifier: 'com.apple.mobilesafari',
+ *            url: /.*apple.com/,
+ *        })
+ *    })
+ * </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=}                     options.appIdentifier                       The app identifier to search in. For iOS, this should be the `bundleId`. For Android, this should be the `packageName`. If not provided, the method will use the active app identifier. This is useful when you need to search for webviews in overlays or non-active apps that are not recognized as the "active" app.
  * @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.
@@ -165,8 +182,13 @@ async function switchToContext(
     const contexts = await browser.getContexts(getContextsOptions) as AppiumDetailedCrossPlatformContexts
 
     // 2. Find the matching context
-    // @ts-expect-error
-    const identifier = browser.isIOS ? (await browser.execute('mobile: activeAppInfo'))?.bundleId : await browser.getCurrentPackage()
+    let identifier: string
+    if (options.appIdentifier) {
+        identifier = options.appIdentifier
+    } else {
+        // @ts-expect-error
+        identifier = browser.isIOS ? (await browser.execute('mobile: activeAppInfo'))?.bundleId : await browser.getCurrentPackage()
+    }
     const { matchingContext, reasons } = findMatchingContext({ browser, contexts, identifier, ...(options?.title && { title: options.title }), ...(options?.url && { url: options.url }) })
 
     if (!matchingContext) {

packages/webdriverio/src/types.ts

@@ -653,6 +653,7 @@ export type GetContextsOptions = {
     isAndroidWebviewVisible?: boolean;
     returnAndroidDescriptionData?: boolean;
     returnDetailedContexts?: boolean;
+    waitForWebviewMs?: number;
 }
 
 export type ActiveAppInfo = {

packages/webdriverio/tests/commands/mobile/__snapshots__/switchContext.test.ts.snap

@@ -52,3 +52,23 @@ exports[`switchContext test > should throw an error when no matching context is
   - App bundleId 'com.foo' did not match: 'WEBVIEW_86152.1'
   - Title 'No matching Title' did not match: 'Apple']
 `;
+
+exports[`switchContext test > should throw an error when the provided appIdentifier does not match any context 1`] = `
+[Error: We parsed a total of 5 Webviews but did not find a matching context. The reasons are:
+- Webview 1: 'NATIVE_APP'
+  - Skipped context because it is NATIVE_APP
+- Webview 2: 'WEBVIEW_com.wdiodemoapp'
+  - App packageName 'com.nonexistent.app' did not match: 'WEBVIEW_com.wdiodemoapp'
+  - Title 'Some Title' did not match: 'WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO'
+- Webview 3: 'WEBVIEW_com.otherApp'
+  - App packageName 'com.nonexistent.app' did not match: 'WEBVIEW_com.otherApp'
+  - Title 'Some Title' did not match: 'Other Apps · I am just another app'
+- Webview 4: 'WEBVIEW_com.otherNonVisibleApp'
+  - App packageName 'com.nonexistent.app' did not match: 'WEBVIEW_com.otherNonVisibleApp'
+  - Title 'Some Title' did not match: 'Other Apps · I am just another app which is not visible'
+  - Additional Android checks failed
+- Webview 5: 'WEBVIEW_chrome'
+  - App packageName 'com.nonexistent.app' did not match: 'WEBVIEW_chrome'
+  - Title 'Some Title' did not match: 'Android | Get more done with Google on Android-phones and devices'
+  - Additional Android checks failed]
+`;

packages/webdriverio/tests/commands/mobile/getContexts.test.ts

@@ -510,4 +510,20 @@ describe('getContexts test', () => {
             expect(emptyContext.packageName).toBe('com.ismobile.android.blaandroid')
         }
     })
+
+    it('should pass waitForWebviewMs parameter to mobile: getContexts when provided', async () => {
+        browser = await remote({
+            baseUrl: 'http://foobar.com',
+            capabilities: {
+                browserName: 'foobar',
+                mobileMode: true,
+                platformName: 'iOS',
+            } as any
+        })
+        const executeSpy = vi.spyOn(browser, 'execute').mockResolvedValue(iOSContexts)
+        await browser.getContexts({ returnDetailedContexts: true, waitForWebviewMs: 3000 })
+
+        expect(executeSpy).toHaveBeenCalledTimes(1)
+        expect(executeSpy).toHaveBeenCalledWith('mobile: getContexts', { waitForWebviewMs: 3000 })
+    })
 })

packages/webdriverio/tests/commands/mobile/switchContext.test.ts

@@ -295,4 +295,55 @@ describe('switchContext test', () => {
         getCurrentPackageSpy.mockRestore()
         switchAppiumContextSpy.mockRestore()
     })
+
+    it('should find a matching context when using a custom appIdentifier', async () => {
+        logSpy = vi.spyOn(log, 'info')
+        browser = await remote({
+            baseUrl: 'http://foobar.com',
+            capabilities: {
+                browserName: 'foobar',
+                mobileMode: true,
+                platformName: 'Android',
+            } as any
+        })
+        const getContextsSpy = vi.spyOn(browser, 'getContexts').mockResolvedValue(androidContexts)
+        const switchAppiumContextSpy = vi.spyOn(browser, 'switchAppiumContext')
+        const switchToWindowSpy = vi.spyOn(browser, 'switchToWindow')
+
+        // Use appIdentifier to search in a different app than the active one
+        await browser.switchContext({
+            appIdentifier: 'com.otherApp',
+            title: 'Other Apps',
+        })
+        expect(getContextsSpy).toHaveBeenCalledTimes(1)
+        expect(logSpy).toHaveBeenCalledWith('WebdriverIO found a matching context:', JSON.stringify(androidContexts[2], null, 2))
+        expect(switchAppiumContextSpy).toHaveBeenCalledWith('WEBVIEW_com.otherApp')
+        expect(switchToWindowSpy).toHaveBeenCalledWith(androidContexts[2].webviewPageId)
+
+        logSpy.mockRestore()
+        getContextsSpy.mockRestore()
+        switchAppiumContextSpy.mockRestore()
+        switchToWindowSpy.mockRestore()
+    })
+
+    it('should throw an error when the provided appIdentifier does not match any context', async () => {
+        browser = await remote({
+            baseUrl: 'http://foobar.com',
+            capabilities: {
+                browserName: 'foobar',
+                mobileMode: true,
+                platformName: 'Android',
+            } as any
+        })
+        const getContextsSpy = vi.spyOn(browser, 'getContexts').mockResolvedValue(androidContexts)
+        const switchAppiumContextSpy = vi.spyOn(browser, 'switchAppiumContext')
+
+        await expect(browser.switchContext({
+            appIdentifier: 'com.nonexistent.app',
+            title: 'Some Title',
+        })).rejects.toThrowErrorMatchingSnapshot()
+
+        getContextsSpy.mockRestore()
+        switchAppiumContextSpy.mockRestore()
+    })
 })