webdriverio 9.6.3 → 9.7.0

package/build/commands/browser.d.ts

@@ -47,4 +47,7 @@ export * from './browser/waitUntil.js';
  */
 export * from './mobile/swipe.js';
 export * from './mobile/tap.js';
+export * from './mobile/getContext.js';
+export * from './mobile/getContexts.js';
+export * from './mobile/switchContext.js';
 //# sourceMappingURL=browser.d.ts.map

package/build/commands/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/commands/browser.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,2BAA2B,CAAA;AACzC,cAAc,sBAAsB,CAAA;AACpC,cAAc,sBAAsB,CAAA;AACpC,cAAc,2BAA2B,CAAA;AACzC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA;AACzC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,2BAA2B,CAAA;AACzC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,qBAAqB,CAAA;AACnC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,sBAAsB,CAAA;AACpC,cAAc,sBAAsB,CAAA;AACpC,cAAc,kCAAkC,CAAA;AAChD,cAAc,6BAA6B,CAAA;AAC3C,cAAc,qBAAqB,CAAA;AACnC,cAAc,yBAAyB,CAAA;AACvC,cAAc,yBAAyB,CAAA;AACvC,cAAc,0BAA0B,CAAA;AACxC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,2BAA2B,CAAA;AACzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,uBAAuB,CAAA;AACrC,cAAc,0BAA0B,CAAA;AACxC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,0BAA0B,CAAA;AACxC,cAAc,yBAAyB,CAAA;AACvC,cAAc,kBAAkB,CAAA;AAChC,cAAc,wBAAwB,CAAA;AACtC;;GAEG;AACH,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/commands/browser.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,2BAA2B,CAAA;AACzC,cAAc,sBAAsB,CAAA;AACpC,cAAc,sBAAsB,CAAA;AACpC,cAAc,2BAA2B,CAAA;AACzC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA;AACzC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,2BAA2B,CAAA;AACzC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,qBAAqB,CAAA;AACnC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,sBAAsB,CAAA;AACpC,cAAc,sBAAsB,CAAA;AACpC,cAAc,kCAAkC,CAAA;AAChD,cAAc,6BAA6B,CAAA;AAC3C,cAAc,qBAAqB,CAAA;AACnC,cAAc,yBAAyB,CAAA;AACvC,cAAc,yBAAyB,CAAA;AACvC,cAAc,0BAA0B,CAAA;AACxC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,2BAA2B,CAAA;AACzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,uBAAuB,CAAA;AACrC,cAAc,0BAA0B,CAAA;AACxC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,0BAA0B,CAAA;AACxC,cAAc,yBAAyB,CAAA;AACvC,cAAc,kBAAkB,CAAA;AAChC,cAAc,wBAAwB,CAAA;AACtC;;GAEG;AACH,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA"}

package/build/commands/mobile/getContext.d.ts

@@ -0,0 +1,107 @@
+import type { DetailedContext } from '@wdio/protocols';
+/**
+ * Retrieve the context of the current session.
+ *
+ * This method enhances the default Appium `context`/WebdriverIO `getContext` command by providing an option to
+ * return detailed context information, making it easier to work with hybrid apps that use webviews.
+ *
+ * ### How Contexts Work
+ * Refer to [Hybrid Apps documentation](/docs/api/mobile#hybrid-apps) for more information. Below is an explanation of the challenges associated with the `getContext` command:
+ *
+ * #### For Android:
+ * - Webviews can contain multiple pages (like browser tabs), and identifying the correct page requires additional metadata
+ *   such as `title` or `url`.
+ * - The default Appium methods only provide basic context names (e.g., `WEBVIEW_{packageName}`) without detailed information
+ *   about the pages inside the webview.
+ *
+ * #### For iOS:
+ * - Each webview is identified by a generic `WEBVIEW_{id}` string, which doesn’t indicate its contents or the app screen
+ *   it belongs to.
+ *
+ * ### Why Use This Method?
+ * - **Default Behavior**:
+ *   - Returns the current context as a string (e.g., `NATIVE_APP` or `WEBVIEW_{id}`).
+ * - **Detailed Context**:
+ *   - When `returnDetailedContext` is enabled, retrieves metadata such as:
+ *     - **Android**: `packageName`, `title`, `url`, and `webviewPageId`.
+ *     - **iOS**: `bundleId`, `title`, and `url`.
+ * - **Android-Specific Options**:
+ *   - Retry intervals and timeouts can be customized to handle delays in webview initialization.
+ *
+ * :::info Notes and Limitations
+ *
+ * - If `returnDetailedContext` is not enabled, the method behaves like the default Appium `getContext` method.
+ * - If you want to use the "default" Appium `context` method, you can use the `driver.getAppiumContext()` method, see
+ * also the [Appium Contexts](/docs/api/appium#getappiumcontext) command.
+ * - **Android:** Android-specific options (`androidWebviewConnectionRetryTime` and `androidWebviewConnectTimeout`) have no effect on iOS.
+ * - Logs warnings if multiple or no detailed contexts are found:
+ *   - `We found more than 1 detailed context for the current context '{context}'. We will return the first context.`
+ *   - `We did not get back any detailed context for the current context '{context}'. We will return the current context as a string.`
+ *
+ * :::
+ *
+ * <example>
+    :default.test.js
+    it('should return the current context with the default Appium `context` method', async () => {
+        // For Android
+        await driver.getContext()
+        // Returns 'WEBVIEW_com.wdiodemoapp' or 'NATIVE_APP'
+        //
+        // For iOS, the context will be 'WEBVIEW_{number}'
+        await driver.getContext()
+        // Returns 'WEBVIEW_94703.19' or 'NATIVE_APP'
+    })
+ * </example>
+ *
+ * <example>
+    :detailed.test.js
+    it('should return the context of the current session with more detailed information', async () => {
+        // For Android
+        await driver.getContext({ returnDetailedContext: true})
+        // Returns or `NATIVE_APP`, or
+        // {
+        //   id: 'WEBVIEW_com.wdiodemoapp',
+        //   title: 'WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO',
+        //   url: 'https://webdriver.io/',
+        //   packageName: 'com.wdiodemoapp',
+        //   webviewPageId: '5C0425CF67E9B169245F48FF21172912'
+        // }
+        //
+        // For iOS, the context will be 'WEBVIEW_{number}'
+        await driver.getContext({ returnDetailedContext: true})
+        // Returns or `NATIVE_APP`, or
+        // {
+        //   id: 'WEBVIEW_64981.1',
+        //   title: 'WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO',
+        //   url: 'https://webdriver.io/',
+        //   bundleId: 'org.reactjs.native.example.wdiodemoapp'
+        // }
+    })
+ * </example>
+ *
+ * <example>
+    :customize.retry.test.js
+    it('should be able to cusomize the retry intervals and timeouts to handle delayed webview initialization', async () => {
+        // For Android
+        await driver.getContext({
+            returnDetailedContext: true,
+            // NOTE: The following options are Android-specific
+            // 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 {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>
+ * @skipUsage
+ */
+export declare function getContext(this: WebdriverIO.Browser, options?: {
+    returnDetailedContext?: boolean;
+    androidWebviewConnectionRetryTime?: number;
+    androidWebviewConnectTimeout?: number;
+}): Promise<string | DetailedContext>;
+//# sourceMappingURL=getContext.d.ts.map

package/build/commands/mobile/getContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getContext.d.ts","sourceRoot":"","sources":["../../../src/commands/mobile/getContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAW,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAM/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG;AACH,wBAAsB,UAAU,CAC5B,IAAI,EAAE,WAAW,CAAC,OAAO,EACzB,OAAO,CAAC,EAAE;IACN,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,iCAAiC,CAAC,EAAE,MAAM,CAAC;IAC3C,4BAA4B,CAAC,EAAE,MAAM,CAAC;CACzC,GACF,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC,CAgBnC"}

package/build/commands/mobile/getContexts.d.ts

@@ -0,0 +1,158 @@
+import type { AppiumDetailedCrossPlatformContexts, GetContextsOptions } from '../../types.js';
+import type { Context } from '@wdio/protocols';
+/**
+ * The WebdriverIO `getContexts` method is an improved version of the default Appium `contexts`
+ * (and the previous WebdriverIO `getContexts`) command. It provides detailed and actionable information
+ * about available contexts in a mobile app session, addressing the limitations of the default Appium methods.
+ *
+ * ### How Webviews Work and Why This Method Helps
+ * For more details, refer to the [Hybrid Apps documentation](/docs/api/mobile#hybrid-apps). Below is a summary of the challenges addressed by the `getContexts` command:
+ *
+ * #### Android Challenges
+ * - A single webview (e.g., `WEBVIEW_{packageName}`) may contain multiple pages (similar to browser tabs).
+ * - The default Appium methods do not include details about these pages, such as their `title`, `url`, or visibility,
+ *   making it hard to identify the correct page and leading to potential flakiness.
+ *
+ * #### iOS Challenges
+ * - The default Appium method only returns generic webview IDs (e.g., `WEBVIEW_{id}`) without any additional metadata.
+ * - This makes it difficult to determine which webview corresponds to the target app screen.
+ *
+ * The enhanced `getContexts` method solves these issues by returning detailed context objects, which include:
+ * - **For Android:** `title`, `url`, `packageName`, `webviewPageId`, and layout details (`screenX`, `screenY`, `width`, and `height`).
+ * - **For iOS:** `bundleId`, `title`, and `url`.
+ *
+ * These enhancements make debugging and interacting with hybrid apps more reliable.
+ *
+ * ### Why Use This Method?
+ * By default, the Appium `contexts` method returns only an array of strings representing available contexts:
+ * - **For Android:** `['NATIVE_APP', 'WEBVIEW_com.wdiodemoapp', ...]`
+ * - **For iOS:** `['NATIVE_APP', 'WEBVIEW_84392.1', ...]`
+ *
+ * While sufficient for simple scenarios, these default responses lack critical metadata for hybrid app testing:
+ * - **For Android:** The lack of page-specific metadata makes it challenging to interact with the correct webview.
+ * - **For iOS:** Generic webview IDs provide no insight into the content or app screen they represent.
+ *
+ * The enhanced `getContexts` method provides:
+ * - Detailed metadata for both Android and iOS.
+ * - Options to filter and customize the returned contexts for better targeting and interaction.
+ *
+ * :::info Notes and Limitations
+ *
+ * - The enhanced `getContexts` method works on both Android and iOS platforms. However, the returned data may vary depending on the platform and app under test.
+ * - If you do not specify the `returnDetailedContexts` option, the method behaves like the default Appium `contexts` method, returning a simple context array.
+ * - To use the "default" Appium `contexts` method, use `driver.getAppiumContexts()`. For more information, see the [Appium Contexts documentation](/docs/api/appium#getappiumcontexts).
+ *
+ * #### Android Webviews:
+ * - Metadata such as `androidWebviewData` is available only when `returnAndroidDescriptionData` is `true`.
+ * - Using the `getContexts` method on a Chrome browser may occasionally return incomplete data due to mismatched browser/Webview/ChromeDriver versions. In such cases, default values or an incorrect `webviewPageId` (e.g., `0`) may be returned.
+ *
+ * :::
+ *
+ * <example>
+    :example.test.js
+    it('should return all contexts in the current session with the default Appium `contexts`-method.', async () => {
+        // For Android
+        await driver.getContexts()
+        // Returns ['NATIVE_APP', 'WEBVIEW_com.wdiodemoapp', ...]
+        //
+        // For iOS, the context will be 'WEBVIEW_{number}'
+        await driver.getContexts()
+        // Returns [ 'NATIVE_APP', 'WEBVIEW_84392.1', ... ]
+    })
+ * </example>
+ *
+ * <example>
+    :detailed.test.js
+    it('should return all contexts in the current session with detailed info.', async () => {
+        // For Android
+        await driver.getContexts({returnDetailedContexts: true})
+        // Returns [
+        //   { id: 'NATIVE_APP' },
+        //   {
+        //       id: 'WEBVIEW_com.wdiodemoapp',
+        //       title: 'WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO',
+        //       url: 'https://webdriver.io/',
+        //       packageName: 'com.wdiodemoapp',
+        //       webviewPageId: '58B0AA2DBBBBBE9008C35AE42385BB0D'
+        //   },
+        //   {
+        //       id: 'WEBVIEW_chrome',
+        //       title: 'Android | Get more done with Google on Android-phones and devices',
+        //       url: 'https://www.android.com/',
+        //       packageName: 'com.android.chrome',
+        //       webviewPageId: '0'
+        //   }
+        // ]
+        //
+        // For iOS, the context will be 'WEBVIEW_{number}'
+        await driver.getContexts({returnDetailedContexts: true})
+        // Returns: [
+        //   { id: 'NATIVE_APP' },
+        //   {
+        //       id: 'WEBVIEW_86150.1',
+        //       title: 'WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO',
+        //       url: 'https://webdriver.io/',
+        //       bundleId: 'org.reactjs.native.example.wdiodemoapp'
+        //   },
+        //   {
+        //       id: 'WEBVIEW_86152.1',
+        //       title: 'Apple',
+        //       url: 'https://www.apple.com/',
+        //       bundleId: 'com.apple.mobilesafari'
+        //   }
+        // ]
+    })
+ * </example>
+ *
+ * <example>
+    :description.data.test.js
+    it('should return Android description data for the webview', async () => {
+        // For Android
+        await driver.getContexts({returnDetailedContexts: true})
+        // Returns [
+        //   { id: 'NATIVE_APP' },
+        //   {
+        //       androidWebviewData: {
+        //          // Indicates whether the web page is currently attached to a web view.
+        //          // `true` means the page is attached and likely active, `false` indicates it is not.
+        //          attached: true,
+        //          // Indicates whether the web page is empty or not. An empty page typically means that
+        //          // there is no significant content loaded in it. `true` indicates the page is empty,
+        //          // `false` indicates it has content.
+        //          empty: false,
+        //          // Indicates whether the page has never been attached to a web view. If `true`, the
+        //          // page has never been attached, which could indicate a new or unused page. If `false`,
+        //          // the page has been attached at some point.
+        //          neverAttached: false,
+        //          // Indicates whether the web page is visible on the screen. `true` means the page is
+        //          // visible to the user, `false` means it is not.
+        //          visible: true,
+        //          // This data can be super useful to determine where on the screen the webview is located
+        //          // and can come in handy when you want to interact with elements on the screen based on
+        //          // coordinates based on the top-left corner of the screen
+        //          screenX: 0,
+        //          screenY: 151,
+        //          height: 2589,
+        //          width: 1344
+        //       },
+        //       id: 'WEBVIEW_com.wdiodemoapp',
+        //       title: 'WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO',
+        //       url: 'https://webdriver.io/',
+        //       packageName: 'com.wdiodemoapp',
+        //       webviewPageId: '58B0AA2DBBBBBE9008C35AE42385BB0D'
+        //   }
+        // ]
+    })
+ * </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>
+ * @skipUsage
+ */
+export declare function getContexts(this: WebdriverIO.Browser, options?: GetContextsOptions): Promise<Context[] | AppiumDetailedCrossPlatformContexts>;
+//# sourceMappingURL=getContexts.d.ts.map

package/build/commands/mobile/getContexts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getContexts.d.ts","sourceRoot":"","sources":["../../../src/commands/mobile/getContexts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAA0B,mCAAmC,EAAE,kBAAkB,EAAsB,MAAM,gBAAgB,CAAA;AACzI,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAI9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyJG;AACH,wBAAsB,WAAW,CAC7B,IAAI,EAAE,WAAW,CAAC,OAAO,EACzB,OAAO,CAAC,EAAE,kBAAkB,GAC7B,OAAO,CAAC,OAAO,EAAE,GAAG,mCAAmC,CAAC,CAsB1D"}

package/build/commands/mobile/switchContext.d.ts

@@ -0,0 +1,112 @@
+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

package/build/commands/mobile/switchContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"switchContext.d.ts","sourceRoot":"","sources":["../../../src/commands/mobile/switchContext.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAmF,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAI3I;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4GG;AACH,wBAAsB,aAAa,CAC/B,IAAI,EAAE,WAAW,CAAC,OAAO,EACzB,OAAO,EAAE,MAAM,GAAG,oBAAoB,iBAuBzC"}

package/build/commands/mobile.d.ts

@@ -3,4 +3,7 @@ export * from './mobile/longPress.js';
 export * from './mobile/pinch.js';
 export * from './mobile/tap.js';
 export * from './mobile/zoom.js';
+export * from './mobile/getContext.js';
+export * from './mobile/getContexts.js';
+export * from './mobile/switchContext.js';
 //# sourceMappingURL=mobile.d.ts.map

package/build/commands/mobile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mobile.d.ts","sourceRoot":"","sources":["../../src/commands/mobile.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA"}
+{"version":3,"file":"mobile.d.ts","sourceRoot":"","sources":["../../src/commands/mobile.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA"}

package/build/index.cjs

@@ -90,14 +90,14 @@ exports.Key = {
   ZenkakuHankaku: "\uE040"
 };
 exports.remote = async function(params, remoteModifier) {
-  const { remote } = await import("./index.js");
+  const { remote } = await import("./node.js");
   return remote(params, remoteModifier);
 };
 exports.attach = async function(attachOptions) {
-  const { attach } = await import("./index.js");
+  const { attach } = await import("./node.js");
   return attach(attachOptions);
 };
 exports.multiremote = async function(params, { automationProtocol } = {}) {
-  const { multiremote } = await import("./index.js");
+  const { multiremote } = await import("./node.js");
   return multiremote(params, { automationProtocol });
 };