system-testing 1.0.24 → 1.0.26

package/README.md

@@ -0,0 +1,63 @@
+# System testing
+
+Rails inspired system testing for Expo apps.
+
+## Install
+
+```bash
+npm install --save-dev system-testing
+```
+
+## Usage
+
+```js
+import retry from "awaitery/src/retry.js"
+import SystemTest from "system-testing/src/system-test.js"
+import wait from "awaitery/src/wait.js"
+import waitFor from "awaitery/src/wait-for.js"
+
+import createUser from "@/src/testing/create-user.js"
+import initialize from "@/src/initialize"
+import Option from "@/src/models/option"
+
+describe("Sign in page", () => {
+  test("it navigates to the sign in page and signs in", async () => {
+    await initialize()
+
+    await SystemTest.run(async (systemTest) => {
+      await createUser(userAttributes)
+
+      await systemTest.visit("/")
+      await systemTest.findByTestID("frontpageScreen", {useBaseSelector: false})
+      await wait(250)
+
+      await retry(async () => {
+        await systemTest.click("[data-testid='signInButton']")
+        await systemTest.findByTestID("app/sign-in")
+      })
+
+      await systemTest.interact("[data-testid='signInEmailInput']", "sendKeys", "user@example.com")
+      await systemTest.interact("[data-testid='signInPasswordInput']", "sendKeys", "password")
+
+      const emailInputValue = await systemTest.interact("[data-testid='signInEmailInput']", "getAttribute", "value")
+      const passwordInputValue = await systemTest.interact("[data-testid='signInPasswordInput']", "getAttribute", "value")
+
+      expect(emailInputValue).toEqual("user@example.com")
+      expect(passwordInputValue).toEqual("password")
+
+      await systemTest.click("[data-testid='signInSubmitButton']")
+      await systemTest.expectNotificationMessage("You were signed in.")
+
+      await waitFor(async () => {
+        const optionUserID = await Option.findBy({key: "userID"})
+
+        if (!optionUserID) {
+          throw new Error("Option for user ID didn't exist")
+        }
+
+        expect(optionUserID.value()).toEqual("805")
+      })
+    })
+  })
+})
+```

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.24",
+  "version": "1.0.26",
   "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

@@ -101,8 +101,7 @@ export default class SystemTestBrowserHelper {
   }
 
   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"))

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

@@ -21,7 +21,7 @@ export default class SystemTestHttpServer {
     try {
       await fs.stat(filePath)
       fileExists = true
-    } catch (_error) {
+    } catch (_error) { // eslint-disable-line no-unused-vars
       fileExists = false
     }
 
@@ -38,8 +38,7 @@ export default class SystemTestHttpServer {
   }
 
   async start() {
-    this.basePath = await fs.realpath(`${__dirname}/../..`) // eslint-disable-line no-undef
-
+    this.basePath = await fs.realpath(`${__dirname}/../..`)
     await this.startHttpServer()
   }
 

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}
    */
@@ -112,10 +107,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,22 +141,38 @@ 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
-   **/
-  async click(element) {
-    if (typeof element == "string") {
-      element = await this.find(element)
-    }
+   * @param {string|import("selenium-webdriver").WebElement} elementOrIdentifier
+   * @returns {Promise<void>}
+   */
+  async click(elementOrIdentifier) {
+    let tries = 0
+
+    while (true) {
+      tries++
 
-    const actions = this.driver.actions({async: true})
+      try {
+        const element = await this._findElement(elementOrIdentifier)
+        const actions = this.driver.actions({async: true})
 
-    await actions.move({origin: element}).click().perform()
+        await actions.move({origin: element}).click().perform()
+        break
+      } catch (error) {
+        if (error.constructor.name === "ElementNotInteractableError") {
+          if (tries >= 3) {
+            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 ${elementOrIdentifier.constructor.name} click failed - ${error.constructor.name}: ${error.message}`)
+        }
+      }
+    }
   }
 
   /**
    * Finds a single element by CSS selector
-   *
    * @param {string} selector
    * @param {object} args
    * @returns {import("selenium-webdriver").WebElement}
@@ -191,18 +200,33 @@ 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
+
+    if (typeof elementOrIdentifier == "string") {
+      element = await this.find(elementOrIdentifier)
+    } else {
+      element = elementOrIdentifier
+    }
+
+    return element
+  }
+
   /**
    * 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)
@@ -216,7 +240,6 @@ export default class SystemTest {
 
   /**
    * Gets browser logs
-   *
    * @returns {Promise<string[]>}
    */
   async getBrowserLogs() {
@@ -239,37 +262,38 @@ 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) {
-    let element
     let tries = 0
 
     while (true) {
       tries++
 
-      if (typeof elementOrIdentifier == "string") {
-        element = await this.find(elementOrIdentifier)
-      } else {
-        element = elementOrIdentifier
-      }
+      const element = await this._findElement(elementOrIdentifier)
 
       if (!element[methodName]) {
-        // throw new Error(`${element.constructor.name} has no method named: ${methodName}`)
+        throw new Error(`${element.constructor.name} hasn't an attribute named: ${methodName}`)
+      } else if (typeof element[methodName] != "function") {
+        throw new Error(`${element.constructor.name}#${methodName} is not a function`)
       }
 
       try {
@@ -278,9 +302,17 @@ export default class SystemTest {
         if (error.constructor.name === "ElementNotInteractableError") {
           // Retry finding the element and interacting with it
           if (tries >= 3) {
-            throw new Error(`${element.constructor.name} ${methodName} failed after ${tries} tries - ${error.constructor.name}: ${error.message}`)
+            let elementDescription
+
+            if (typeof elementOrIdentifier == "string") {
+              elementDescription = `CSS selector ${elementOrIdentifier}`
+            } else {
+              elementDescription = `${element.constructor.name}`
+            }
+
+            throw new Error(`${elementDescription} ${methodName} failed after ${tries} tries - ${error.constructor.name}: ${error.message}`)
           } else {
-            await wait(100)
+            await wait(50)
           }
         } else {
           // Re-throw with un-corrupted stack trace
@@ -292,8 +324,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
@@ -312,9 +344,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() {
@@ -332,45 +396,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") {
@@ -410,8 +494,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
     }
 
@@ -419,11 +502,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()) {
@@ -435,8 +519,8 @@ export default class SystemTest {
 
   /**
    * Sets driver timeouts
-   *
    * @param {number} newTimeout
+   * @returns {Promise<void>}
    */
   async driverSetTimeouts(newTimeout) {
     await this.driver.manage().setTimeouts({implicit: newTimeout})
@@ -444,8 +528,8 @@ export default class SystemTest {
 
   /**
    * Sets timeouts and stores the previous timeouts
-   *
    * @param {number} newTimeout
+   * @returns {Promise<void>}
    */
   async setTimeouts(newTimeout) {
     this._timeouts = newTimeout
@@ -454,7 +538,6 @@ export default class SystemTest {
 
   /**
    * Waits for the client web socket to connect
-   *
    * @returns {Promise<void>}
    */
   waitForClientWebSocket() {
@@ -469,6 +552,7 @@ export default class SystemTest {
 
   /**
    * Starts the web socket server
+   * @returns {void}
    */
   startWebSocketServer() {
     this.wss = new WebSocketServer({port: 1985})
@@ -478,6 +562,8 @@ export default class SystemTest {
 
   /**
    * Sets the on command callback
+   * @param {function(object) : void} callback
+   * @returns {void}
    */
   onCommand(callback) {
     this._onCommandCallback = callback
@@ -485,8 +571,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}) => {
@@ -519,8 +605,8 @@ export default class SystemTest {
 
   /**
    * Handles a new web socket connection
-   *
    * @param {WebSocket} ws
+   * @returns {void}
    */
   onWebSocketConnection = async (ws) => {
     this.ws = ws
@@ -535,6 +621,9 @@ export default class SystemTest {
     }
   }
 
+  /**
+   * @returns {void}
+   */
   onWebSocketClose = () => {
     this.ws = null
     this.communicator.ws = null
@@ -542,8 +631,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")) {
@@ -562,6 +651,7 @@ export default class SystemTest {
 
   /**
    * Stops the system test
+   * @returns {Promise<void>}
    */
   async stop() {
     this.stopScoundrel()
@@ -572,8 +662,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}`
@@ -583,6 +673,7 @@ export default class SystemTest {
 
   /**
    * Takes a screenshot, saves HTML and browser logs
+   * @returns {Promise<void>}
    */
   async takeScreenshot() {
     const path = `${process.cwd()}/tmp/screenshots`
@@ -610,8 +701,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})
@@ -619,8 +710,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

@@ -36,11 +36,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:
+ * @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 {object} An object containing:
  *  - enabled: A boolean indicating if system test mode is enabled.
  *  - systemTestBrowserHelper: An instance of SystemTestBrowserHelper if enabled, otherwise null.
  */