chore: Improve typing on webview commands

lib/commands/context.js

@@ -13,12 +13,14 @@ const DEFAULT_REMOTE_DEBUGGER_CONNECT_TIMEOUT_MS = 5000;
 const extensions = {
   /**
    * @this {XCUITestDriver}
+   * @param {boolean} [useUrl=false]
+   * @returns {Promise<import('./types').ViewContext<typeof NATIVE_WIN>[]>}
    */
   async getContextsAndViews(useUrl = true) {
     this.log.debug('Retrieving contexts and views');
     const webviews = await this.listWebFrames(useUrl);
     /**
-     * @type {[import('./types').ViewContext<typeof NATIVE_WIN>]}
+     * @type {import('./types').ViewContext<typeof NATIVE_WIN>[]}
      */
     const ctxs = [{id: NATIVE_WIN, view: {}}];
     this.contexts = [NATIVE_WIN];
@@ -34,13 +36,15 @@ const extensions = {
    * and frame to load, which leads to race conditions and flakiness,
    * let's see if we can transition to something better
    * @this {XCUITestDriver}
+   * @returns {boolean}
    */
   useNewSafari() {
     return this.isSimulator() && this.isSafari();
   },
 
   /**
    * @this {XCUITestDriver}
+   * @returns {Promise<void>}
    */
   async activateRecentWebview() {
     this.log.debug('Activating a recent webview');
@@ -60,6 +64,7 @@ const extensions = {
   },
   /**
    * @this {XCUITestDriver}
+   * @returns {Promise<import('../types').Page[]>}
    */
   async listWebFrames(useUrl = true) {
     useUrl = useUrl && !this.isRealDevice() && !!this.getCurrentUrl();
@@ -90,6 +95,7 @@ const extensions = {
   },
   /**
    * @this {XCUITestDriver}
+   * @returns {Promise<void>}
    */
   async connectToRemoteDebugger() {
     this.remote = await this.getNewRemoteDebugger();
@@ -125,7 +131,7 @@ const extensions = {
    * client code would have to connect to each of them in order to detect the
    * one which needs to be interacted with. This extra effort is not needed with
    * the information provided by this extension.
-   * @param {number} waitForWebviewMs - The period to poll for available webview(s) (in ms)
+   * @param {number} [waitForWebviewMs=0] - The period to poll for available webview(s) (in ms)
    * @returns {Promise<Context[]>} The list of available context objects along with their properties.
    * @this {XCUITestDriver}
    */
@@ -163,8 +169,9 @@ const extensions = {
     }
   },
   /**
-   * @param {import('./types').PageChangeNotification} pageChangeNotification
    * @this {XCUITestDriver}
+   * @param {import('./types').PageChangeNotification} pageChangeNotification
+   * @returns {Promise<void>}
    */
   async onPageChange(pageChangeNotification) {
     this.log.debug(
@@ -325,6 +332,7 @@ const extensions = {
 const helpers = {
   /**
    * @this {XCUITestDriver}
+   * @returns {Promise<void>}
    */
   async stopRemote(closeWindowBeforeDisconnecting = false) {
     if (!this.remote) {
@@ -341,12 +349,14 @@ const helpers = {
   },
   /**
    * @this {XCUITestDriver}
+   * @param {string|undefined|null} url
    */
   setCurrentUrl(url) {
     this._currentUrl = url;
   },
   /**
    * @this {XCUITestDriver}
+   * @returns {string|undefined|null}
    */
   getCurrentUrl() {
     return this._currentUrl;
@@ -355,6 +365,7 @@ const helpers = {
    * @param {RegExp} titleRegExp
    * @param {RegExp} urlRegExp
    * @this {XCUITestDriver}
+   * @returns {Promise<string|undefined>}
    */
   async getRecentWebviewContextId(titleRegExp, urlRegExp) {
     if (!_.isRegExp(titleRegExp) && !_.isRegExp(urlRegExp)) {
@@ -380,12 +391,14 @@ const helpers = {
   },
   /**
    * @this {XCUITestDriver}
+   * @returns {boolean}
    */
   isWebContext() {
     return !!this.curContext && this.curContext !== NATIVE_WIN;
   },
   /**
    * @this {XCUITestDriver}
+   * @returns {boolean}
    */
   isWebview() {
     return this.isWebContext();
@@ -428,6 +441,7 @@ const helpers = {
 const commands = {
   /**
    * @this {XCUITestDriver}
+   * @returns {Promise<string>}
    */
   // eslint-disable-next-line require-await
   async getCurrentContext() {
@@ -442,8 +456,9 @@ const commands = {
    *
    * @param {string|Context} name - The name of context to set. It could be 'null' as NATIVE_WIN.
    * @param {any} [callback] The callback. (It is not called in this method)
-   * @param {boolean} skipReadyCheck - Whether it waits for the new context is ready
+   * @param {boolean} [skipReadyCheck=false] - Whether it waits for the new context is ready
    * @this {XCUITestDriver}
+   * @returns {Promise<void>}
    */
   async setContext(name, callback, skipReadyCheck = false) {
     function alreadyInContext(desired, current) {
@@ -560,6 +575,9 @@ const commands = {
 
   /**
    * @this {XCUITestDriver}
+   * @param {string} name
+   * @param {boolean} [skipReadyCheck]
+   * @returns {Promise<void>}
    */
   async setWindow(name, skipReadyCheck) {
     try {
@@ -571,6 +589,7 @@ const commands = {
   },
   /**
    * @this {XCUITestDriver}
+   * @returns {Promise<string>}
    */
   // eslint-disable-next-line require-await
   async getWindowHandle() {
@@ -585,6 +604,7 @@ const commands = {
   },
   /**
    * @this {XCUITestDriver}
+   * @returns {Promise<string[]>}
    */
   async getWindowHandles() {
     if (!this.isWebContext()) {

lib/driver.js

@@ -1810,9 +1810,11 @@ export class XCUITestDriver extends BaseDriver {
 
   getContexts = commands.contextExtensions.getContexts;
   getCurrentContext = commands.contextExtensions.getCurrentContext;
+  // @ts-ignore This is OK
   getWindowHandle = commands.contextExtensions.getWindowHandle;
   getWindowHandles = commands.contextExtensions.getWindowHandles;
   setContext = commands.contextExtensions.setContext;
+  // @ts-ignore This is OK
   setWindow = commands.contextExtensions.setWindow;
   activateRecentWebview = commands.contextExtensions.activateRecentWebview;
   connectToRemoteDebugger = commands.contextExtensions.connectToRemoteDebugger;