system-testing 1.0.25 → 1.0.27

package/eslint.config.js

@@ -0,0 +1,23 @@
+import js from "@eslint/js"
+import {jsdoc} from "eslint-plugin-jsdoc"
+import globals from "globals"
+import { defineConfig } from "eslint/config"
+
+export default defineConfig([
+  {
+    files: ["**/*.{js,mjs,cjs}"],
+    plugins: {js},
+    extends: ["js/recommended"],
+    languageOptions: {
+      globals: {...globals.browser, ...globals.node}
+    }
+  },
+  jsdoc({
+    config: "flat/recommended",
+    rules: {
+      "jsdoc/reject-any-type": "off",
+      "jsdoc/require-param-description": "off",
+      "jsdoc/require-returns-description": "off"
+    }
+  })
+])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "system-testing",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "System testing with Selenium and browsers.",
   "keywords": [
     "system",
@@ -21,6 +21,7 @@
   "type": "module",
   "main": "src/index.js",
   "scripts": {
+    "lint": "eslint",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
@@ -34,5 +35,11 @@
   },
   "peerDependencies": {
     "selenium-webdriver": "^4.34.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "eslint": "^9.39.1",
+    "eslint-plugin-jsdoc": "^61.4.1",
+    "globals": "^16.5.0"
   }
 }

package/peak_flow.yml

@@ -0,0 +1,4 @@
+before_script:
+  - npm install
+script:
+  - npm run lint

package/src/system-test-browser-helper.js

@@ -100,15 +100,20 @@ export default class SystemTestBrowserHelper {
     this.communicator.sendCommand(data)
   }
 
+  /**
+   * @returns {void}
+   */
   connectWebSocket() {
-    this.ws = new WebSocket("ws://localhost:1985") // eslint-disable-line no-undef
-
+    this.ws = new WebSocket("ws://localhost:1985")
     this.communicator.ws = this.ws
     this.ws.addEventListener("error", digg(this, "communicator", "onError"))
     this.ws.addEventListener("open", digg(this, "communicator", "onOpen"))
     this.ws.addEventListener("message", (event) => this.communicator.onMessage(event.data))
   }
 
+  /**
+   * @returns {void}
+   */
   enableOnBrowser() {
     this._enabled = true
     this.connectWebSocket()
@@ -117,7 +122,14 @@ export default class SystemTestBrowserHelper {
     this.overrideConsoleLog()
   }
 
+  /**
+   * @returns {boolean}
+   */
   getEnabled() { return this._enabled }
+
+  /**
+   * @returns {EventEmitter}
+   */
   getEvents() { return this.events }
 
   fakeConsoleError = (...args) => {
@@ -186,10 +198,17 @@ export default class SystemTestBrowserHelper {
     }
   }
 
+  /**
+   * @param {function() : void} callback
+   * @returns {void}
+   */
   onInitialize(callback) {
     this._onInitializeCallback = callback
   }
 
+  /**
+   * @returns {void}
+   */
   overrideConsoleLog() {
     if (this.originalConsoleError || this.originalConsoleLog) {
       throw new Error("Console methods has already been overridden!")
@@ -202,6 +221,10 @@ export default class SystemTestBrowserHelper {
     console.log = this.fakeConsoleLog
   }
 
+  /**
+   * @param {string} sql
+   * @returns {Promise<Array<Record<string, any>>>}
+   */
   async sendQuery(sql) {
     return await this.communicator.sendCommand({type: "query", sql})
   }

package/src/system-test-communicator.js

@@ -65,9 +65,8 @@ export default class SystemTestCommunicator {
 
   /**
    * Sends a command and returns a promise that resolves with the response.
-   *
-   * @param {Object} data - The command data to send.
-   * @returns {Promise} A promise that resolves with the response data.
+   * @param {object} data - The command data to send.
+   * @returns {Promise<void>} A promise that resolves with the response data.
    */
   sendCommand(data) {
     return new Promise((resolve, error) => {

package/src/system-test-http-server.js

@@ -4,6 +4,7 @@ import mime from "mime"
 import url from "url"
 
 export default class SystemTestHttpServer {
+  /** @returns {void} */
   close() {
     this.httpServer.close()
   }
@@ -21,7 +22,7 @@ export default class SystemTestHttpServer {
     try {
       await fs.stat(filePath)
       fileExists = true
-    } catch (_error) {
+    } catch (_error) { // eslint-disable-line no-unused-vars
       fileExists = false
     }
 
@@ -37,12 +38,13 @@ export default class SystemTestHttpServer {
     response.end(fileContent)
   }
 
+  /** @returns {Promise<void>} */
   async start() {
-    this.basePath = await fs.realpath(`${__dirname}/../..`) // eslint-disable-line no-undef
-
+    this.basePath = await fs.realpath(`${__dirname}/../..`)
     await this.startHttpServer()
   }
 
+  /** @returns {Promise<void>} */
   startHttpServer() {
     return new Promise((resolve) => {
       this.httpServer = http.createServer(this.onHttpServerRequest)

package/src/system-test.js

@@ -1,4 +1,4 @@
-import {Builder, By} from "selenium-webdriver"
+import {Builder, By, until} from "selenium-webdriver"
 import chrome from "selenium-webdriver/chrome.js"
 import {digg} from "diggerize"
 import fs from "node:fs/promises"
@@ -19,7 +19,6 @@ export default class SystemTest {
 
   /**
    * Gets the current system test instance
-   *
    * @param {object} args
    * @returns {SystemTest}
    */
@@ -33,8 +32,8 @@ export default class SystemTest {
 
   /**
    * Runs a system test
-   *
    * @param {function(SystemTest): Promise<void>} callback
+   * @returns {Promise<void>}
    */
   static async run(callback) {
     const systemTest = this.current()
@@ -54,7 +53,6 @@ export default class SystemTest {
 
   /**
    * Creates a new SystemTest instance
-   *
    * @param {object} args
    * @param {string} args.host
    * @param {number} args.port
@@ -76,21 +74,18 @@ export default class SystemTest {
 
   /**
    * Gets the base selector for scoping element searches
-   *
    * @returns {string}
    */
   getBaseSelector() { return this._baseSelector }
 
   /**
    * Sets the base selector for scoping element searches
-   *
    * @param {string} baseSelector
    */
   setBaseSelector(baseSelector) { this._baseSelector = baseSelector }
 
   /**
    * Gets a selector scoped to the base selector
-   *
    * @param {string} selector
    * @returns {string}
    */
@@ -98,13 +93,19 @@ export default class SystemTest {
     return this.getBaseSelector() ? `${this.getBaseSelector()} ${selector}` : selector
   }
 
-  /** Starts Scoundrel server which the browser connects to for remote evaluation in the browser */
+  /**
+   * Starts Scoundrel server which the browser connects to for remote evaluation in the browser
+   * @returns {void}
+   */
   startScoundrel() {
     this.wss = new WebSocketServer({port: 8090})
     this.serverWebSocket = new ServerWebSocket(this.wss)
     this.server = new Server(this.serverWebSocket)
   }
 
+  /**
+   * @returns {void}
+   */
   stopScoundrel() {
     this.server?.close()
     this.wss?.close()
@@ -112,10 +113,8 @@ export default class SystemTest {
 
   /**
    * Finds all elements by CSS selector
-   *
    * @param {string} selector
    * @param {object} args
-   *
    * @returns {import("selenium-webdriver").WebElement[]}
    */
   async all(selector, args = {}) {
@@ -148,9 +147,9 @@ export default class SystemTest {
 
   /**
    * Clicks an element that has children which fills out the element and would otherwise have caused a ElementClickInterceptedError
-   *
-   * @param {import("selenium-webdriver").WebElement} element
-   **/
+   * @param {string|import("selenium-webdriver").WebElement} elementOrIdentifier
+   * @returns {Promise<void>}
+   */
   async click(elementOrIdentifier) {
     let tries = 0
 
@@ -166,13 +165,13 @@ export default class SystemTest {
       } catch (error) {
         if (error.constructor.name === "ElementNotInteractableError") {
           if (tries >= 3) {
-            throw new Error(`Element ${element.constructor.name} click failed after ${tries} tries - ${error.constructor.name}: ${error.message}`)
+            throw new Error(`Element ${elementOrIdentifier.constructor.name} click failed after ${tries} tries - ${error.constructor.name}: ${error.message}`)
           } else {
             await wait(50)
           }
         } else {
           // Re-throw with un-corrupted stack trace
-          throw new Error(`Element ${element.constructor.name} click failed - ${error.constructor.name}: ${error.message}`)
+          throw new Error(`Element ${elementOrIdentifier.constructor.name} click failed - ${error.constructor.name}: ${error.message}`)
         }
       }
     }
@@ -180,7 +179,6 @@ export default class SystemTest {
 
   /**
    * Finds a single element by CSS selector
-   *
    * @param {string} selector
    * @param {object} args
    * @returns {import("selenium-webdriver").WebElement}
@@ -208,13 +206,16 @@ export default class SystemTest {
 
   /**
    * Finds a single element by test ID
-   *
    * @param {string} testID
    * @param {object} args
-   * @returns {import("selenium-webdriver").WebElement}
+   * @returns {Promise<import("selenium-webdriver").WebElement>}
    */
   async findByTestID(testID, args) { return await this.find(`[data-testid='${testID}']`, args) }
 
+  /**
+   * @param {string|import("selenium-webdriver").WebElement} elementOrIdentifier
+   * @returns {Promise<import("selenium-webdriver").WebElement>}
+   */
   async _findElement(elementOrIdentifier) {
     let element
 
@@ -229,9 +230,9 @@ export default class SystemTest {
 
   /**
    * Finds a single element by CSS selector without waiting
-   *
    * @param {string} selector
-   * @returns {import("selenium-webdriver").WebElement}
+   * @param {object} args
+   * @returns {Promise<import("selenium-webdriver").WebElement>}
    */
   async findNoWait(selector, args) {
     await this.driverSetTimeouts(0)
@@ -245,7 +246,6 @@ export default class SystemTest {
 
   /**
    * Gets browser logs
-   *
    * @returns {Promise<string[]>}
    */
   async getBrowserLogs() {
@@ -268,20 +268,24 @@ export default class SystemTest {
     return browserLogs
   }
 
+  /**
+   * @returns {Promise<string>}
+   */
   async getCurrentUrl() {
     return await this.driver.getCurrentUrl()
   }
 
+  /**
+   * @returns {number}
+   */
   getTimeouts() { return this._timeouts }
 
   /**
    * Interacts with an element by calling a method on it with the given arguments.
    * Retrying on ElementNotInteractableError.
-   *
    * @param {import("selenium-webdriver").WebElement|string} elementOrIdentifier - The element or a CSS selector to find the element.
    * @param {string} methodName - The method name to call on the element.
    * @param {...any} args - Arguments to pass to the method.
-   *
    * @returns {Promise<any>}
    */
   async interact(elementOrIdentifier, methodName, ...args) {
@@ -326,8 +330,8 @@ export default class SystemTest {
 
   /**
    * Expects no element to be found by CSS selector
-   *
    * @param {string} selector
+   * @returns {Promise<void>}
    */
   async expectNoElement(selector) {
     let found = false
@@ -346,9 +350,41 @@ export default class SystemTest {
     }
   }
 
+  /**
+   * @param {string} selector
+   * @param {object} args
+   * @returns {Promise<void>}
+   */
+  async waitForNoSelector(selector, args) {
+    const timeStart = new Date().getTime()
+    const timeout = this.getTimeouts()
+    const {useBaseSelector, ...restArgs} = args
+
+    if (Object.keys(restArgs).length > 0) {
+      throw new Error(`Unexpected args: ${Object.keys(restArgs).join(", ")}`)
+    }
+
+    while (true) {
+      try {
+        const actualSelector = useBaseSelector ? this.getSelector(selector) : selector
+
+        await this.driver.wait(until.elementIsNotVisible(By.css(actualSelector)), 0)
+
+        const timeElapsed = new Date().getTime() - timeStart
+
+        if (timeElapsed > timeout) {
+          throw new Error(`Element still found after ${timeout}ms: ${selector}`)
+        }
+      } catch (error) {
+        if (error.message.startsWith("Element couldn't be found after ")) {
+          break
+        }
+      }
+    }
+  }
+
   /**
    * Gets notification messages
-   *
    * @returns {Promise<string[]>}
    */
   async notificationMessages() {
@@ -366,45 +402,65 @@ export default class SystemTest {
 
   /**
    * Expects a notification message to appear and waits for it if necessary.
-   *
    * @param {string} expectedNotificationMessage
+   * @returns {Promise<void>}
    */
   async expectNotificationMessage(expectedNotificationMessage) {
     const allDetectedNotificationMessages = []
+    let foundNotificationMessageElement
 
     await waitFor(async () => {
-      const notificationMessages = await this.notificationMessages()
+      const notificationMessageElements = await this.all("[data-class='notification-message']", {useBaseSelector: false})
+
+      for (const notificationMessageElement of notificationMessageElements) {
+        const notificationMessage = await notificationMessageElement.getText()
 
-      for (const notificationMessage of notificationMessages) {
         if (!allDetectedNotificationMessages.includes(notificationMessage)) {
           allDetectedNotificationMessages.push(notificationMessage)
         }
 
         if (notificationMessage == expectedNotificationMessage) {
+          foundNotificationMessageElement = notificationMessageElement
           return
         }
       }
 
       throw new Error(`Notification message ${expectedNotificationMessage} wasn't included in: ${allDetectedNotificationMessages.join(", ")}`)
     })
+
+    if (foundNotificationMessageElement) {
+      await this.interact(foundNotificationMessageElement, "click") // Dismiss the notification message
+    }
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  async dismissNotificationMessages() {
+    const notificationMessageElements = await this.all("[data-class='notification-message']", {useBaseSelector: false})
+
+    for (const notificationMessageElement of notificationMessageElements) {
+      await this.interact(notificationMessageElement, "click")
+    }
+
+    await this.waitForNoSelector("[data-class='notification-message']", {useBaseSelector: false})
   }
 
   /**
    * Indicates whether the system test has been started
-   *
    * @returns {boolean}
    */
   isStarted() { return this._started }
 
   /**
    * Gets the HTML of the current page
-   *
    * @returns {Promise<string>}
    */
   async getHTML() { return await this.driver.getPageSource() }
 
   /**
    * Starts the system test
+   * @returns {Promise<void>}
    */
   async start() {
     if (process.env.SYSTEM_TEST_HOST == "expo-dev-server") {
@@ -444,8 +500,7 @@ export default class SystemTest {
       await this.find("body > #root", {useBaseSelector: false})
       await this.find("[data-testid='systemTestingComponent']", {visible: null, useBaseSelector: false})
     } catch (error) {
-      await systemTest.takeScreenshot()
-
+      await this.takeScreenshot()
       throw error
     }
 
@@ -453,11 +508,12 @@ export default class SystemTest {
     await this.waitForClientWebSocket()
 
     this._started = true
-    systemTest.setBaseSelector("[data-testid='systemTestingComponent'][data-focussed='true']")
+    this.setBaseSelector("[data-testid='systemTestingComponent'][data-focussed='true']")
   }
 
   /**
    * Restores previously set timeouts
+   * @returns {Promise<void>}
    */
   async restoreTimeouts() {
     if (!this.getTimeouts()) {
@@ -469,8 +525,8 @@ export default class SystemTest {
 
   /**
    * Sets driver timeouts
-   *
    * @param {number} newTimeout
+   * @returns {Promise<void>}
    */
   async driverSetTimeouts(newTimeout) {
     await this.driver.manage().setTimeouts({implicit: newTimeout})
@@ -478,8 +534,8 @@ export default class SystemTest {
 
   /**
    * Sets timeouts and stores the previous timeouts
-   *
    * @param {number} newTimeout
+   * @returns {Promise<void>}
    */
   async setTimeouts(newTimeout) {
     this._timeouts = newTimeout
@@ -488,7 +544,6 @@ export default class SystemTest {
 
   /**
    * Waits for the client web socket to connect
-   *
    * @returns {Promise<void>}
    */
   waitForClientWebSocket() {
@@ -503,6 +558,7 @@ export default class SystemTest {
 
   /**
    * Starts the web socket server
+   * @returns {void}
    */
   startWebSocketServer() {
     this.wss = new WebSocketServer({port: 1985})
@@ -512,6 +568,8 @@ export default class SystemTest {
 
   /**
    * Sets the on command callback
+   * @param {function(object) : void} callback
+   * @returns {void}
    */
   onCommand(callback) {
     this._onCommandCallback = callback
@@ -519,8 +577,8 @@ export default class SystemTest {
 
   /**
    * Handles a command received from the browser
-   *
-   * @param {Object} data
+   * @param {object} data
+   * @param {object} data.data
    * @returns {Promise<any>}
    */
   onCommandReceived = async ({data}) => {
@@ -553,8 +611,8 @@ export default class SystemTest {
 
   /**
    * Handles a new web socket connection
-   *
    * @param {WebSocket} ws
+   * @returns {void}
    */
   onWebSocketConnection = async (ws) => {
     this.ws = ws
@@ -569,6 +627,9 @@ export default class SystemTest {
     }
   }
 
+  /**
+   * @returns {void}
+   */
   onWebSocketClose = () => {
     this.ws = null
     this.communicator.ws = null
@@ -576,8 +637,8 @@ export default class SystemTest {
 
   /**
    * Handles an error reported from the browser
-   *
-   * @param {Object} data
+   * @param {object} data
+   * @returns {void}
    */
   handleError(data) {
     if (data.message.includes("Minified React error #419")) {
@@ -596,6 +657,7 @@ export default class SystemTest {
 
   /**
    * Stops the system test
+   * @returns {Promise<void>}
    */
   async stop() {
     this.stopScoundrel()
@@ -606,8 +668,8 @@ export default class SystemTest {
 
   /**
    * Visits a path in the browser
-   *
    * @param {string} path
+   * @returns {Promise<void>}
    */
   async driverVisit(path) {
     const url = `${this.currentUrl}${path}`
@@ -617,6 +679,7 @@ export default class SystemTest {
 
   /**
    * Takes a screenshot, saves HTML and browser logs
+   * @returns {Promise<void>}
    */
   async takeScreenshot() {
     const path = `${process.cwd()}/tmp/screenshots`
@@ -644,8 +707,8 @@ export default class SystemTest {
 
   /**
    * Visits a path in the browser
-   *
    * @param {string} path
+   * @returns {Promise<void>}
    */
   async visit(path) {
     await this.communicator.sendCommand({type: "visit", path})
@@ -653,8 +716,8 @@ export default class SystemTest {
 
   /**
    * Dismisses to a path in the browser
-   *
    * @param {string} path
+   * @returns {Promise<void>}
    */
   async dismissTo(path) {
     await this.communicator.sendCommand({type: "dismissTo", path})

package/src/use-system-test.js

@@ -9,7 +9,10 @@ const shared = {
   systemTestBrowserHelper: null
 }
 
-const isSystemTestEnabled = () => {
+/**
+ * @returns {boolean}
+ */
+function isSystemTestEnabled() {
   let enabled = false
   const initialUrl = globalThis.location?.href
 
@@ -25,7 +28,10 @@ const isSystemTestEnabled = () => {
   return enabled
 }
 
-const getSystemTestBrowserHelper = () => {
+/**
+ * @returns {SystemTestBrowserHelper}
+ */
+function getSystemTestBrowserHelper() {
   if (!shared.systemTestBrowserHelper) {
     shared.systemTestBrowserHelper = new SystemTestBrowserHelper()
     shared.systemTestBrowserHelper.enableOnBrowser()
@@ -36,13 +42,9 @@ const getSystemTestBrowserHelper = () => {
 
 /**
  * A hook that provides system test capabilities.
- *
- * @param {Object} options - Options for the hook.
- * @param {Function} options.onInitialize - A callback function that is called when the system test browser helper is initialized.
- *
- * @returns {Object} An object containing:
- *  - enabled: A boolean indicating if system test mode is enabled.
- *  - systemTestBrowserHelper: An instance of SystemTestBrowserHelper if enabled, otherwise null.
+ * @param {object} options - Options for the hook.
+ * @param {function() : void} options.onInitialize - A callback function that is called when the system test browser helper is initialized.
+ * @returns {{enabled: boolean, systemTestBrowserHelper: SystemTestBrowserHelper}}
  */
 export default function useSystemTest({onInitialize, ...restArgs} = {}) {
   const router = useRouter()