tftsr-devops_investigation/node_modules/webdriverio/build/commands/mobile/switchContext.d.ts

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). 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.
 * - **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>
 *
 * <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.
 * @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