feat: Add mobile extension for the 'expectNotification' call (appium#…

…1287)

README.md

@@ -637,6 +637,21 @@ Name | Type | Required | Description | Example
 bundleId | string | yes | The bundle identifier of the target application | com.apple.Preferences
 payload | map | yes | Valid Apple Push Notification values. Read the `Create the JSON Payload` topic of the [official Apple documentation](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification?language=objc) for more details on the payload creation. | `{"aps": {"alert": "This is a simulated notification!", "badge": 3, "sound": "default"} }`
 
+### mobile: expectNotification
+
+Blocks until the expected notification is delivered.
+It is a thin wrapper over [XCTNSNotificationExpectation](https://developer.apple.com/documentation/xctest/xctnsnotificationexpectation?language=objc) and
+[XCTDarwinNotificationExpectation](https://developer.apple.com/documentation/xctest/xctdarwinnotificationexpectation?language=objc) entities.
+The extension call throws [TimeoutError](https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/error_exports_TimeoutError.html) if the expected notification has not been delivered within the given timeout.
+
+#### Arguments
+
+Name | Type | Required | Description | Example
+--- | --- | --- | --- | ---
+name | string | yes | The name of the notification to expect | com.example.fooAllDone
+type | string | no | Which notification type to expect. Either `plain` (the default value) to wait for a notification from the *default* notification center or `darwin` to wait for a system notification. | darwin
+timeoutSeconds | number | no | For how long to wait until the notification is delivered in float seconds. 60 seconds by default | 5.5
+
 ### mobile: enrollBiometric
 
 Enrolls biometric authentication on Simulator.

lib/commands/execute.js

@@ -120,6 +120,7 @@ extensions.executeMobile = async function executeMobile (mobileCommand, opts = {
     listXCTestsInTestBundle: 'mobileListXCTestsInTestBundle',
 
     pushNotification: 'mobilePushNotification',
+    expectNotification: 'mobileExpectNotification',
   };
 
   if (!_.has(commandMap, mobileCommand)) {

lib/commands/notifications.js

@@ -46,4 +46,33 @@ extensions.mobilePushNotification = async function mobilePushNotification (opts
   });
 };
 
+
+/**
+ * @typedef {Object} NotificationExpectationOptions
+ *
+ * @property {!string} name - The name of the notification to expect
+ * @property {?string} type [plain] - Which notification type to expect.
+ * Either 'plain' to wait for a notification from the default notification center or 'darwin'
+ * to wait for a system notification.
+ * @property {number} timeoutSeconds [60] - For how long to wait until the notification is delivered
+ * in float seconds.
+ */
+
+/**
+ * Blocks until the expected notification is delivered.
+ * This method is a thin wrapper over XCTNSNotificationExpectation and
+ * XCTDarwinNotificationExpectation entities.
+ *
+ * @param {NotificationExpectationOptions} opts
+ * @throws TimeoutError if the expected notification has not been delivered within the given timeout
+ */
+extensions.mobileExpectNotification = async function mobileExpectNotification (opts = {}) {
+  const { name, type, timeoutSeconds } = opts;
+  return await this.proxyCommand('/wda/expectNotification', 'POST', {
+    name,
+    type,
+    timeout: timeoutSeconds,
+  });
+};
+
 export default extensions;

package.json

@@ -51,7 +51,7 @@
     "appium-ios-simulator": "^3.25.1",
     "appium-remote-debugger": "^8.13.2",
     "appium-support": "^2.47.1",
-    "appium-webdriveragent": "^3.0.0",
+    "appium-webdriveragent": "^3.4.0",
     "appium-xcode": "^3.8.0",
     "async-lock": "^1.0.0",
     "asyncbox": "^2.3.1",