feat: Add a BiDi event upon context change

docs/reference/bidi.md

@@ -45,3 +45,19 @@ Events are only emitted if the `appium:enablePerformanceLogging` capability valu
 Events are emitted for both emulator and real devices. Each event contains a single Appium server log line.
 Events are always emitted with the `NATIVE_APP` context.
 Events are only emitted if the `get_server_logs` server security feature is enabled.
+
+## appium.contextUpdate
+
+This event is emitted upon the context change, either explicit or implicit.
+The event is always emitted upon new session initialization.
+See the [GitHub feature ticket](https://github.com/appium/appium/issues/20741) for more details.
+
+The event contains the following params:
+
+### name
+
+Contains the actual name of the new context, for example `NATIVE_APP`.
+
+### type
+
+Either `NATIVE` or `WEB` depending on which context is currently active in the driver session.

lib/commands/context.js

@@ -3,7 +3,7 @@ import {errors, isErrorType} from 'appium/driver';
 import {util, timing} from 'appium/support';
 import IOSPerformanceLog from '../device-log/ios-performance-log';
 import _ from 'lodash';
-import { NATIVE_WIN } from '../utils';
+import { NATIVE_WIN, BIDI_EVENT_NAME } from '../utils';
 
 const WEBVIEW_WIN = 'WEBVIEW';
 const WEBVIEW_BASE = `${WEBVIEW_WIN}_`;
@@ -345,6 +345,7 @@ const extensions = {
       (async () => {
         try {
           await /** @type {RemoteDebugger} */ (this.remote).selectPage(appIdKey, parseInt(newPage, 10));
+          await notifyBiDiContextChange.bind(this)();
         } catch (e) {
           this.log.warn(`Failed to select page: ${e.message}`);
           this.curContext = oldContext;
@@ -372,6 +373,7 @@ const helpers = {
     }
     await this.remote.disconnect();
     this.curContext = null;
+    await notifyBiDiContextChange.bind(this)();
     this.curWebFrames = [];
     this.remote = null;
   },
@@ -519,6 +521,7 @@ const commands = {
     if (isNativeContext(strName)) {
       // switching into the native context
       this.curContext = null;
+      await notifyBiDiContextChange.bind(this)();
       return;
     }
 
@@ -548,6 +551,7 @@ const commands = {
     try {
       this.selectingNewPage = true;
       await (/** @type {RemoteDebugger} */ (this.remote)).selectPage(appIdKey, pageIdKey, skipReadyCheck);
+      await notifyBiDiContextChange.bind(this)();
     } catch (err) {
       this.curContext = this.curWindowHandle = oldContext;
       throw err;
@@ -699,6 +703,24 @@ function isUrlIgnored(url, safariIgnoreWebHostnames) {
   return false;
 }
 
+/**
+ * https://github.com/appium/appium/issues/20741
+ *
+ * @this {XCUITestDriver}
+ * @returns {Promise<void>}
+ */
+export async function notifyBiDiContextChange() {
+  const name = await this.getCurrentContext();
+  const type = name === NATIVE_WIN ? 'NATIVE' : 'WEB';
+  this.eventEmitter.emit(BIDI_EVENT_NAME, {
+    method: 'appium.contextUpdate',
+    params: {
+      name,
+      type,
+    },
+  });
+}
+
 export default {...helpers, ...extensions, ...commands};
 
 /**

lib/driver.js

@@ -62,6 +62,7 @@ import {
   translateDeviceName,
 } from './utils';
 import { AppInfosCache } from './app-infos-cache';
+import { notifyBiDiContextChange } from './commands/context';
 
 const SHUTDOWN_OTHER_FEAT_NAME = 'shutdown_other_sims';
 const CUSTOMIZE_RESULT_BUNDLE_PATH = 'customize_result_bundle_path';
@@ -660,6 +661,9 @@ export class XCUITestDriver extends BaseDriver {
 
     if (this.isSafari() || this.opts.autoWebview) {
       await this.activateRecentWebview();
+    } else {
+      // We want to always setup the initial context value upon session startup
+      await notifyBiDiContextChange.bind(this)();
     }
     if (this.isSafari()) {
       if (shouldSetInitialSafariUrl(this.opts)) {