メインコンテンツにスキップ

switchContext

指定されたWebviewのname、title、またはurlを使用して特定のコンテキストに切り替えます。

このメソッドは、ハイブリッドモバイルアプリケーションのネイティブとWebviewコンテキスト間の切り替えにおいて、 より柔軟性と精度を提供することで、デフォルトのAppium contextコマンドを強化します。

コンテキストの仕組み​

ハイブリッドアプリとWebviewの概要については、ハイブリッドアプリのドキュメントを参照してください。 以下はswitchContextコマンドが一般的な課題にどのように対処するかの概要です：

Androidの課題​

  • Webviewには多くの場合、複数のページ（ブラウザのタブに似ています）が含まれています。正しいページを識別するにはtitleやurlなどの 追加のメタデータが必要ですが、デフォルトのAppiumメソッドではこれらは提供されません。
  • デフォルトのAppiumメソッドは、Webview内のコンテンツやページに関する詳細情報なしに、基本的なコンテキスト名 （例：WEBVIEW_{packageName}）のみを返します。
  • Androidでのコンテキスト切り替えには、このメソッドで自動的に処理される2つのステップが含まれます：
    1. WEBVIEW_{packageName}を使用してWebviewコンテキストに切り替える。
    2. switchToWindowメソッドを使用してWebview内の適切なページを選択する。

iOSの課題​

  • Webviewは一般的なID（例：WEBVIEW_{id}）で識別され、コンテンツやそれが対応するアプリ画面に関する情報は提供されません。
  • インタラクションのための正しいWebviewの決定には、多くの場合試行錯誤が必要です。

switchContextメソッドは、詳細なメタデータ（例：title、url、可視性）を取得することで、 正確で信頼性の高いコンテキスト切り替えを確保し、このプロセスを簡素化します。

このメソッドを使用する理由​

  • 簡素化された切り替え：目的のWebviewのtitleやurlを知っている場合、このメソッドはgetContextsへの追加呼び出しや switchContext({id})とgetTitle()のような複数のメソッドを組み合わせる必要性を排除します。
  • 自動コンテキスト一致：以下に基づいてコンテキストの最適な一致を見つけます：
    • プラットフォーム固有の識別子（iOSのbundleId、AndroidのpackageName）。
    • titleまたはurlの完全一致または部分一致（文字列と正規表現の両方をサポート）。
    • Webviewがアタッチされて可視であることを確認するAndroid固有のチェック。
  • 細かい制御：カスタムリトライ間隔とタイムアウト（Androidのみ）により、Webview初期化の遅延を処理できます。
  • デフォルトAppiumメソッドアクセス：必要に応じて、driver.switchAppiumContext()を介してデフォルトのAppium switchContextコマンドを使用できます。
注意事項と制限
  • 目的のWebviewのtitleまたはurlが分かっている場合、このメソッドは追加のgetContexts呼び出しなしに一致するコンテキストを自動的に見つけて切り替えることができます。
  • androidWebviewConnectionRetryTimeやandroidWebviewConnectTimeoutなどのAndroid固有のオプションはiOSには適用されません。
  • デバッグを支援するために、コンテキスト一致の失敗理由をログに記録します。
  • 入力としてオブジェクトを使用する場合、titleまたはurlが必要です。
パラメータ​
名前タイプ詳細
contextstring, SwitchContextOptions切り替え先のコンテキストの名前。より多くのコンテキストオプションを含むオブジェクトを提供できます。
optionsSwitchContextOptionsswitchContextコマンドオプション
options.title
optional		string, RegExp切り替え先のページのタイトル。これはWebviewページのtitleタグの内容になります。完全に一致する必要がある文字列または正規表現を使用できます。
重要： オプションを使用する場合、titleまたはurlプロパティのいずれかが必要です。
options.url
optional		string, RegExp切り替え先のページのURL。これはWebviewページのurlになります。完全に一致する必要がある文字列または正規表現を使用できます。
重要： オプションを使用する場合、titleまたはurlプロパティのいずれかが必要です。
options.androidWebviewConnectionRetryTime
optional		numberWebviewへの接続を再試行する各間隔の時間（ミリ秒）。デフォルトは500ミリ秒（オプション）。
ANDROIDのみで、titleまたはurlが提供されている場合にのみ使用されます。
options.androidWebviewConnectTimeout
optional		numberWebviewページの検出を待つ最大時間（ミリ秒）。デフォルトは5000ミリ秒（オプション）。
ANDROIDのみで、titleまたはurlが提供されている場合にのみ使用されます。
例​
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
    })
})

Welcome! How can I help?

WebdriverIO AI Copilot