presidium 3.0.3 → 3.2.0

package/GoogleChromeDevTools.js

@@ -1,5 +1,5 @@
 const EventEmitter = require('events')
-const GoogleChromeForTesting = require('./internal/GoogleChromeForTesting')
+const GoogleChromeForTesting = require('./GoogleChromeForTesting')
 const WebSocket = require('./WebSocket')
 
 let id = 0
@@ -743,13 +743,40 @@ class GoogleChromeDevToolsRuntime {
  *
  * @docs
  * ```coffeescript [specscript]
- * new GoogleChromeDevTools(url string) -> googleChromeDevTools GoogleChromeDevTools
+ * new GoogleChromeDevTools(
+ *   googleChromeForTesting GoogleChromeForTesting
+ * ) -> googleChromeDevTools GoogleChromeDevTools
+ *
+ * new GoogleChromeDevTools(options {
+ *   chromeVersion: 'stable'|'beta'|'dev'|'canary'|string,
+ *   chromeDir: string,
+ *   remoteDebuggingPort: number,
+ *   headless: boolean,
+ *   userDataDir: string,
+ *   useMockKeychain: boolean,
+ * }) -> googleChromeDevTools GoogleChromeDevTools
  * ```
  *
  * Presidium GoogleChromeDevTools client for test automation.
  *
+ * Arguments:
+ *   * `googleChromeForTesting` - an instance of a Presidium [GoogleChromeForTesting](/docs/GoogleChromeForTesting) client.
+ *   * `options`
+ *     * `chromeVersion` - the version of Google Chrome for Testing to download. Defaults to `'stable'`.
+ *     * `chromeDir` - the directory that Google Chrome for Testing will install to. Defaults to ``google-chrome-for-testing'`.
+ *     * `remoteDebuggingPort` - the port that the Chrome DevTools Protocol server will listen on. Defaults to `9222`
+ *     * `headless` - whether to run Google Chrome for Testing in headless mode. Defaults to `false`.
+ *     * `userDataDir` - directory for storing user profile data such as history, bookmarks, cookies, and settings. Defaults to `tmp/chrome`.
+ *     * `useMockKeychain` - whether to use a mock keychain instead of the system's real security keychain. Defaults to `true`.
+ *
+ * Returns:
+ *   * `googleChromeDevTools` - an instance of the Presidium GoogleChromeDevTools client.
+ *
  * ```javascript
- * const googleChromeDevTools = new GoogleChromeDevTools()
+ * const googleChromeForTesting = new GoogleChromeForTesting()
+ * await googleChromeForTesting.init()
+ *
+ * const googleChromeDevTools = new GoogleChromeDevTools(googleChromeForTesting)
  * await googleChromeDevTools.init()
  *
  * const target = await googleChromeDevTools.Target.getTargets()
@@ -791,7 +818,10 @@ class GoogleChromeDevToolsRuntime {
  * Every Chrome DevTools Protocol client needs to first attach to the target using the `Target.attachToTarget` command. The command will establish a protocol session with the given target and return a `sessionId`. The returned `sessionId` should be set on the `GoogleChromeDevTools` client using [`setSessionId`](#setSessionId) or included in every message to the DevTools server.
  *
  * ```javascript
- * const googleChromeDevTools = new GoogleChromeDevTools()
+ * const googleChromeForTesting = new GoogleChromeForTesting()
+ * await googleChromeForTesting.init()
+ *
+ * const googleChromeDevTools = new GoogleChromeDevTools(googleChromeForTesting)
  * await googleChromeDevTools.init()
  *
  * // get targets
@@ -815,12 +845,43 @@ class GoogleChromeDevToolsRuntime {
  * References:
  *   * [Getting Started with the Chrome Devtools Protocol](https://github.com/aslushnikov/getting-started-with-cdp/blob/master/README.md)
  *   * [Chrome Devtools Protocol](https://chromedevtools.github.io/devtools-protocol/)
+ *
+ * Supported platforms:
+ *   * `mac-arm64`
+ *   * `linux64`
+ *
+ * ## Further Installation
+ * Some further installation may be required for Linux platforms.
+ *
+ * ### Install headless dependencies for Amazon Linux 2023
+ * ```sh
+ * sudo dnf install -y cairo pango nss nspr atk at-spi2-atk cups-libs libdrm libxkbcommon libXcomposite libXdamage libXfixes libXrandr mesa-libgbm alsa-lib
+ * ```
+ *
+ * ### Install headless dependencies for Ubuntu
+ * ```sh
+ * sudo apt-get update && sudo apt-get install -y libcairo2 libpango-1.0-0 libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libatspi2.0-0 libcups2 libdrm-dev libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm-dev libasound2-dev
+ *
+ * # disable AppArmor unprivileged security restriction
+ * echo "kernel.apparmor_restrict_unprivileged_userns=0" | sudo tee /etc/sysctl.d/60-apparmor-namespace.conf
+ * sudo sysctl -p /etc/sysctl.d/60-apparmor-namespace.conf
+ * ```
+ *
  */
 class GoogleChromeDevTools extends EventEmitter {
   constructor(options = {}) {
     super()
 
+    if (options.constructor == GoogleChromeForTesting) {
+      this.googleChromeForTesting = options
+    }
+
     this.chromeVersion = options.chromeVersion ?? 'stable'
+    this.chromeDir = options.chromeDir ?? 'google-chrome-for-testing'
+    this.remoteDebuggingPort = options.remoteDebuggingPort ?? 9222
+    this.headless = options.headless ?? false
+    this.userDataDir = options.userDataDir ?? 'tmp/chrome'
+    this.useMockKeychain = options.useMockKeychain ?? true
   }
 
   /**
@@ -846,15 +907,17 @@ class GoogleChromeDevTools extends EventEmitter {
    * ```
    */
   async init() {
-    const googleChromeForTesting = new GoogleChromeForTesting({
+    this.googleChromeForTesting ??= new GoogleChromeForTesting({
       chromeVersion: this.chromeVersion,
-      userDataDir: `${__dirname}/tmp/chrome`,
-      useMockKeychain: true,
+      chromeDir: this.chromeDir,
+      remoteDebuggingPort: this.remoteDebuggingPort,
+      headless: this.headless,
+      userDataDir: this.userDataDir,
+      useMockKeychain: this.useMockKeychain,
     })
-    await googleChromeForTesting.init()
-    this.googleChromeForTesting = googleChromeForTesting
+    await this.googleChromeForTesting.init()
 
-    this.websocket = new WebSocket(googleChromeForTesting.devtoolsUrl, {
+    this.websocket = new WebSocket(this.googleChromeForTesting.devtoolsUrl, {
       offerPerMessageDeflate: false,
     })
     this.websocket.on('error', error => {
@@ -911,6 +974,31 @@ class GoogleChromeDevTools extends EventEmitter {
     this.Runtime.sessionId = sessionId
   }
 
+  /**
+   * @name close
+   *
+   * @docs
+   * ```coffeescript [specscript]
+   * close() -> undefined
+   * ```
+   *
+   * Closes the websocket connection to the DevTools server and terminates the Google Chrome for Testing process.
+   *
+   * Arguments:
+   *   * (none)
+   *
+   * Return:
+   *   * `undefined`
+   *
+   * ```javascript
+   * googleChromeDevTools.close()
+   * ```
+   */
+  close() {
+    this.websocket.sendClose()
+    this.websocket.close()
+    this.googleChromeForTesting.close()
+  }
 }
 
 module.exports = GoogleChromeDevTools

package/{internal/GoogleChromeForTesting.js → GoogleChromeForTesting.js}

@@ -5,10 +5,11 @@ const path = require('path')
 const { spawn } = require('child_process')
 const readline = require('readline')
 const extract = require('extract-zip')
-const HTTP = require('../HTTP')
-const XML = require('../XML')
-const Readable = require('../Readable')
-const walk = require('./walk')
+const HTTP = require('./HTTP')
+const XML = require('./XML')
+const Readable = require('./Readable')
+const walk = require('./internal/walk')
+const sleep = require('./internal/sleep')
 
 async function getChromeVersions() {
   const http = new HTTP()
@@ -23,7 +24,7 @@ function updateConsoleLog(message) {
   process.stdout.write(message);
 }
 
-async function getChromeUrl() {
+function getPlatform() {
   let platform = os.platform()
   if (platform == 'darwin') {
     platform = 'mac'
@@ -36,6 +37,12 @@ async function getChromeUrl() {
     platform = `${platform}${arch.slice(1)}`
   }
 
+  return platform
+}
+
+async function getChromeUrl() {
+  const platform = getPlatform()
+
   let url
   if (['stable', 'beta', 'dev', 'canary'].includes(this.chromeVersion)) {
     const chromeVersions = await getChromeVersions()
@@ -91,19 +98,27 @@ async function installChrome() {
   })
   await promise
 
-  await extract(filepath, { dir: parentDir })
+  try {
+    await extract(filepath, { dir: parentDir })
+  } catch {
+    await sleep(100)
+    await extract(filepath, { dir: parentDir })
+  }
 }
 
 async function getChromeFilepath() {
+  const platform = getPlatform()
   const url = await getChromeUrl.call(this)
   const filepath = `${this.chromeDir}/${url.replace('https://storage.googleapis.com/chrome-for-testing-public/', '')}`
   const parentDir = `${filepath.split('/').slice(0, -1).join('/')}`
 
-  const googleChromeForTestingFilepath = `${parentDir}`
   try {
     for await (const filepath of walk(parentDir)) {
       console.log(filepath)
-      if (filepath.endsWith('Google Chrome for Testing')) {
+      if (platform.startsWith('mac') && filepath.endsWith('Google Chrome for Testing')) {
+        return filepath
+      }
+      if (platform.startsWith('linux') && filepath.endsWith('chrome')) {
         return filepath
       }
     }
@@ -130,11 +145,51 @@ async function getChromeFilepath() {
  *   headless: boolean,
  *   userDataDir: string,
  *   useMockKeychain: boolean,
- * }) -> GoogleChromeForTesting
+ * }) -> googleChromeForTesting GoogleChromeForTesting
+ * ```
+ *
+ * Presidium GoogleChromeForTesting client for test automation.
+ *
+ * Arguments:
+ *   * `options`
+ *     * `chromeVersion` - the version of Google Chrome for Testing to download. Defaults to `'stable'`.
+ *     * `chromeDir` - the directory that Google Chrome for Testing will install to. Defaults to ``google-chrome-for-testing'`.
+ *     * `remoteDebuggingPort` - the port that the Chrome DevTools Protocol server will listen on. Defaults to `9222`
+ *     * `headless` - whether to run Google Chrome for Testing in headless mode. Defaults to `false`.
+ *     * `userDataDir` - directory for storing user profile data such as history, bookmarks, cookies, and settings. Defaults to `tmp/chrome`.
+ *     * `useMockKeychain` - whether to use a mock keychain instead of the system's real security keychain. Defaults to `true`.
+ *
+ * Returns:
+ *   * `googleChromeForTesting` - an instance of the `GoogleChromeForTesting` client.
+ *
+ * ```javascript
+ * const googleChromeForTesting = new GoogleChromeForTesting({ chromeVersion: 'stable' })
+ * await googleChromeForTesting.init()
  * ```
  *
- * References:
+ * Google Chrome for Testing versions:
  *   * [Chrome for Testing availability](https://googlechromelabs.github.io/chrome-for-testing/)
+ *
+ * Supported platforms:
+ *   * `mac-arm64`
+ *   * `linux64`
+ *
+ * ## Further Installation
+ * Some further installation may be required for Linux platforms.
+ *
+ * ### Install headless dependencies for Amazon Linux 2023 / Red Hat
+ * ```sh
+ * sudo dnf install -y cairo pango nss nspr atk at-spi2-atk cups-libs libdrm libxkbcommon libXcomposite libXdamage libXfixes libXrandr mesa-libgbm alsa-lib
+ * ```
+ *
+ * ### Install headless dependencies for Ubuntu / Debian
+ * ```sh
+ * sudo apt-get update && sudo apt-get install -y libcairo2 libpango-1.0-0 libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libatspi2.0-0 libcups2 libdrm-dev libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm-dev libasound2-dev
+ *
+ * # disable AppArmor unprivileged security restriction
+ * echo "kernel.apparmor_restrict_unprivileged_userns=0" | sudo tee /etc/sysctl.d/60-apparmor-namespace.conf
+ * sudo sysctl -p /etc/sysctl.d/60-apparmor-namespace.conf
+ * ```
  */
 class GoogleChromeForTesting {
   constructor(options = {}) {
@@ -142,8 +197,8 @@ class GoogleChromeForTesting {
     this.chromeDir = options.chromeDir ?? 'google-chrome-for-testing'
     this.remoteDebuggingPort = options.remoteDebuggingPort ?? 9222
     this.headless = options.headless ?? false
-    this.userDataDir = options.userDataDir ?? './tmp/chrome'
-    this.useMockKeychain = options.useMockKeychain ?? false
+    this.userDataDir = options.userDataDir ?? 'tmp/chrome'
+    this.useMockKeychain = options.useMockKeychain ?? true
     this.devtoolsUrl = undefined
   }
 
@@ -154,10 +209,27 @@ class GoogleChromeForTesting {
    * ```coffeescript [specscript]
    * init() -> Promise<>
    * ```
+   *
+   * Initializes the `GoogleChromeForTesting` client.
+   *
+   * Arguments:
+   *   * (none)
+   *
+   * Returns:
+   *   * `promise` - a promise that resolves when the initialization process is done.
+   *
+   * ```javascript
+   * const googleChromeForTesting = new GoogleChromeForTesting()
+   *
+   * await googleChromeForTesting.init()
+   * ```
    */
   async init() {
+    if (this.devtoolsUrl) {
+      return undefined
+    }
+
     const chromeFilepath = await getChromeFilepath.call(this)
-    console.log('spawn', chromeFilepath)
 
     const cmd = spawn(chromeFilepath, [
       `--remote-debugging-port=${this.remoteDebuggingPort}`,
@@ -168,18 +240,24 @@ class GoogleChromeForTesting {
     cmd.stdout.pipe(process.stdout)
     cmd.stderr.pipe(process.stderr)
 
-    const devtoolsUrlPromiseWithResolvers = Promise.withResolvers()
+    let devtoolsUrlResolve
+    const devtoolsUrlPromise = new Promise(_resolve => {
+      devtoolsUrlResolve = _resolve
+    })
     cmd.stderr.on('data', chunk => {
       const line = chunk.toString('utf8').trim()
       if (line.includes('DevTools listening on')) {
         const devtoolsUrl = line.replace('DevTools listening on ', '')
-        devtoolsUrlPromiseWithResolvers.resolve(devtoolsUrl)
+        devtoolsUrlResolve(devtoolsUrl)
       }
     })
 
-    const spawnPromiseWithResolvers = Promise.withResolvers()
+    let spawnResolve
+    const spawnPromise = new Promise(_resolve => {
+      spawnResolve = _resolve
+    })
     cmd.on('spawn', () => {
-      spawnPromiseWithResolvers.resolve()
+      spawnResolve()
     })
 
     cmd.on('error', error => {
@@ -197,8 +275,10 @@ class GoogleChromeForTesting {
 
     this.cmd = cmd
 
-    await spawnPromiseWithResolvers.promise
-    this.devtoolsUrl = await devtoolsUrlPromiseWithResolvers.promise
+    await spawnPromise
+    this.devtoolsUrl = await devtoolsUrlPromise
+
+    return undefined
   }
 
   /**

package/README.md

@@ -28,7 +28,7 @@ const WebSocket = require('presidium/WebSocket')
 const Readable = require('presidium/Readable')
 ```
 
-## Handle HTTP
+## [Handle HTTP](https://presidium.services/docs/HTTP)
 ```javascript
 const HTTP = require('presidium/HTTP')
 
@@ -47,7 +47,7 @@ http.get('/')
   .then(console.log) // { greeting: 'Hello World' }
 ```
 
-## Handle WebSocket
+## [Send messages with WebSocket](https://presidium.services/docs/WebSocket)
 ```javascript
 const WebSocket = require('presidium/WebSocket')
 
@@ -71,7 +71,7 @@ websocket.on('message', message => {
 })
 ```
 
-## CRUD and Query DynamoDB
+## [Create, read, update, delete, and query with AWS DynamoDB](https://presidium.services/docs/DynamoDBTable)
 ```javascript
 const DynamoDBTable = require('presidium/DynamoDBTable')
 const DynamoDBGlobalSecondaryIndex = require('presidium/DynamoDBGlobalSecondaryIndex')
@@ -175,7 +175,7 @@ await myTable.putItemJSON({ id: '3', name: 'Jane', age: 33, type: 'person' })
 }
 ```
 
-## Consume DynamoDB Streams
+## [Consume AWS DynamoDB Streams](https://presidium.services/docs/DynamoDBStream)
 ```javascript
 const DynamoDBTable = require('presidium/DynamoDBTable')
 const DynamoDBStream = require('presidium/DynamoDBStream')
@@ -219,7 +219,7 @@ for await (const record of myStreamJSON) {
 }
 ```
 
-## Upload to S3
+## [Download and upload with AWS S3](https://presidium.services/docs/S3Bucket)
 ```javascript
 const S3Bucket = require('presidium/S3Bucket')
 const AwsCredentials = require('presidium/AwsCredentials')
@@ -245,8 +245,7 @@ await myBucket.deleteAllObjects()
 await myBucket.delete()
 ```
 
-## Build and Push Docker Images
-> No more --build-arg for npm tokens!
+## [Build and push Docker images](https://presidium.services/docs/Docker)
 ```javascript
 const Docker = require('presidium/Docker')
 const NpmToken = require('presidium/NpmToken')
@@ -276,16 +275,18 @@ CMD ["npm", "start"]
 })
 
 buildStream.pipe(process.stdout)
-await new Promise(resolve => buildStream.on('end', resolve))
 
-const pushStream = await docker.pushImage({
-  image: myImage,
-  repository: 'my-registry.io',
+buildStream.on('end', () => {
+  const pushStream = await docker.pushImage({
+    image: myImage,
+    repository: 'my-registry.io',
+  })
+  pushStream.pipe(process.stdout)
 })
-pushStream.pipe(process.stdout)
+
 ```
 
-## Run Docker Containers
+## [Run Docker containers](https://presidium.services/docs/Docker)
 ```javascript
 const Docker = require('presidium/Docker')
 
@@ -301,7 +302,7 @@ const runStream = await docker.runContainer({
 runStream.pipe(process.stdout) // Example
 ```
 
-## Deploy Docker Swarm Services
+## [Deploy Docker Swarm services](https://presidium.services/docs/Docker)
 ```javascript
 const Docker = require('presidium/Docker')
 
@@ -320,5 +321,34 @@ await docker.createService({
 // new nginx service is deploying to the docker swarm
 ```
 
+## [Automate tests with Google Chrome for Testing](https://presidium.services/docs/GoogleChromeDevTools)
+```javascript
+const GoogleChromeForTesting = require('presidium/GoogleChromeForTesting')
+const GoogleChromeDevTools = require('presidium/GoogleChromeDevTools')
+
+const googleChromeForTesting = new GoogleChromeForTesting()
+await googleChromeForTesting.init() // downloads Google Chrome for Testing
+
+const googleChromeDevTools = new GoogleChromeDevTools(googleChromeForTesting)
+await googleChromeDevTools.init() // connects to the DevTools server
+
+// get targets
+const targetsData = await googleChromeDevTools.Target.getTargets()
+const pageTarget = targetsData.result.targetInfos.find(info => info.type == 'page')
+
+// attach to target
+const attachToTargetData = await googleChromeDevTools.Target.attachToTarget({
+  targetId: this.pageTarget.targetId,
+  flatten: true,
+})
+const sessionId = attachToTargetData.result.sessionId
+
+// navigate to the home page
+const data = await googleChromeDevTools.Page.navigate({
+  sessionId: this.sessionId,
+  url: `http://localhost:3000/`,
+})
+```
+
 # Support
  * minimum Node.js version: 16

package/index.js

@@ -6,6 +6,7 @@ module.exports = {
   DynamoDBTable: require('./DynamoDBTable.js'),
   ECR: require('./ECR.js'),
   GoogleChromeDevTools: require('./GoogleChromeDevTools.js'),
+  GoogleChromeForTesting: require('./GoogleChromeForTesting.js'),
   HTTP: require('./HTTP.js'),
   NpmToken: require('./NpmToken.js'),
   OptionalValidator: require('./OptionalValidator.js'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "presidium",
-  "version": "3.0.3",
+  "version": "3.2.0",
   "description": "A library for creating web services",
   "author": "Richard Tong",
   "license": "MIT",
@@ -19,6 +19,7 @@
     "DynamoDBTable.js",
     "ECR.js",
     "GoogleChromeDevTools.js",
+    "GoogleChromeForTesting.js",
     "HTTP.js",
     "index.js",
     "NpmToken.js",
@@ -75,7 +76,7 @@
     "fast-crc32c": "^2.0.0",
     "mocha": "^10.8.2",
     "nyc": "^17.1.0",
-    "thunk-test": "^1.3.1",
+    "thunk-test": "^1.3.9",
     "wavefile": "^11.0.0"
   }
 }

package/internal/GoogleChromeForTesting.test.js

@@ -1,50 +0,0 @@
-const Test = require('thunk-test')
-const assert = require('assert')
-const fs = require('fs')
-const { exec } = require('child_process')
-const Readable = require('../Readable')
-const GoogleChromeForTesting = require('./GoogleChromeForTesting')
-
-const test = new Test('GoogleChromeForTesting', async function integration() {
-  await fs.promises.rm('google-chrome-for-testing', { recursive: true, force: true })
-
-  const cmd = await exec('ps aux | grep "Google Chrome for Testing" | awk \'{print $2}\' | xargs kill', {
-    stdio: 'inherit',
-  })
-
-  {
-    const googleChromeForTesting = new GoogleChromeForTesting({
-      userDataDir: `${__dirname}/tmp/chrome`,
-      useMockKeychain: true,
-    })
-    await googleChromeForTesting.init()
-
-    assert.equal(typeof googleChromeForTesting.devtoolsUrl, 'string')
-    assert(googleChromeForTesting.devtoolsUrl.startsWith('ws://'))
-
-    googleChromeForTesting.close()
-  }
-
-  {
-    const googleChromeForTesting = new GoogleChromeForTesting({
-      userDataDir: `${__dirname}/tmp/chrome`,
-      useMockKeychain: true,
-    })
-    await googleChromeForTesting.init()
-
-    assert.equal(typeof googleChromeForTesting.devtoolsUrl, 'string')
-    assert(googleChromeForTesting.devtoolsUrl.startsWith('ws://'))
-
-    googleChromeForTesting.close()
-  }
-
-  await fs.promises.rm('google-chrome-for-testing', { recursive: true, force: true })
-
-  console.log('Success')
-}).case()
-
-if (process.argv[1] == __filename) {
-  test()
-}
-
-module.exports = test