# 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[](#how-contexts-work "Direct link to How Contexts Work")
For an overview of Hybrid Apps and webviews, refer to the [Hybrid Apps documentation](/docs/api/mobile.md#hybrid-apps). Below is a summary of how the `switchContext` command addresses common challenges:
#### Android Challenges[](#android-challenges "Direct link to 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[](#ios-challenges "Direct link to 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?[](#why-use-this-method "Direct link to 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()`.
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[](#parameters "Direct link to 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.appIdentifier`
*optional* | `string` | 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. |
| `options.title`
*optional* | `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`
*optional* | `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[](#examples "Direct link to 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
})
})
app.identifier.test.js
t('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/,
})
)
```
## Support[](#support "Direct link to Support")
 
**Supported platforms:** iOS, Android
note
Refer to the official [Appium driver documentation](https://appium.io/docs/en/latest/ecosystem/) to see which driver versions support this command.