presidium 3.1.0 → 3.3.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,24 +743,40 @@ class GoogleChromeDevToolsRuntime {
  *
  * @docs
  * ```coffeescript [specscript]
+ * 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.
- *     * `headless` - whether to run Google Chrome for Testing in headless mode.
+ *     * `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 `GoogleChromeDevTools` client.
+ *   * `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()
@@ -802,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
@@ -823,26 +842,42 @@ class GoogleChromeDevToolsRuntime {
  * })
  * ```
  *
- * Install 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
- * ```
+ * 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`
+ *   * `win64`
  *
- * 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/)
+ * ## 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
+ * ```
  */
 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
   }
 
   /**
@@ -868,20 +903,25 @@ 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 => {
-      throw error
+      if (this.closed && error.code == 'ECONNRESET') {
+        console.error('Reset after close:', error)
+      } else {
+        throw error
+      }
     })
 
     this.websocket.on('message', message => {
@@ -934,6 +974,58 @@ 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.closed = true
+    this.websocket.sendClose()
+    this.websocket.on('close', () => {
+      this.googleChromeForTesting.cmd.on('close', () => {
+        this.emit('close')
+      })
+      this.googleChromeForTesting.close()
+    })
+  }
+
+  /**
+   * @name Event: close
+   *
+   * @docs
+   * ```coffeescript [specscript]
+   * emit('close')
+   * ```
+   *
+   * The `close` event. Emitted when the websocket connection to the DevTools server is closed and the Google Chrome for Testing process is terminated.
+   *
+   * Event Data:
+   *   * (none)
+   *
+   * ```javascript
+   * googleChromeForTesting.on('close', () => {
+   *   console.log('WebSocket connection closed and Google Chrome for Testing process terminated.')
+   * })
+   * ```
+   */
+
 }
 
+
 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()
@@ -17,7 +18,7 @@ async function getChromeVersions() {
   return data
 }
 
-function updateConsoleLog(message) {
+function updateConsoleLog(message, platform) {
   readline.cursorTo(process.stdout, 0, undefined);
   readline.clearLine(process.stdout, 0);
   process.stdout.write(message);
@@ -32,7 +33,11 @@ function getPlatform() {
 
   if (platform == 'mac') {
     platform = `${platform}-${arch}`
-  } else {
+  }
+  else if (platform == 'win32') {
+    platform = `win${arch.slice(1)}`
+  }
+  else {
     platform = `${platform}${arch.slice(1)}`
   }
 
@@ -57,13 +62,26 @@ async function getChromeUrl() {
 }
 
 async function installChrome() {
+  const platform = getPlatform()
+  const delimiter = platform.startsWith('win') ? '\\' : '/'
   const url = await getChromeUrl.call(this)
-  let filepath = `${this.chromeDir}/${url.replace('https://storage.googleapis.com/chrome-for-testing-public/', '')}`
-  if (!filepath.startsWith('/')) {
+
+  let filepath = `${this.chromeDir}${delimiter}${url.replace('https://storage.googleapis.com/chrome-for-testing-public/', '')}`
+  if (platform.startsWith('win')) {
+    filepath = filepath.replace(/\//g, '\\')
+    if (!filepath.startsWith(`${__dirname[0]}:`)) {
+      filepath = path.join(process.cwd(), filepath)
+    }
+  } else if (!filepath.startsWith('/')) {
     filepath = path.join(process.cwd(), filepath)
   }
-  let parentDir = `${filepath.split('/').slice(0, -1).join('/')}`
-  if (!parentDir.startsWith('/')) {
+
+  let parentDir = `${filepath.split(delimiter).slice(0, -1).join(delimiter)}`
+  if (platform.startsWith('win')) {
+    if (!filepath.startsWith(`${__dirname[0]}:`)) {
+      parentDir = path.join(process.cwd(), parentDir)
+    }
+  } else if (!parentDir.startsWith('/')) {
     parentDir = path.join(process.cwd(), parentDir)
   }
   await fs.promises.mkdir(parentDir, { recursive: true })
@@ -80,9 +98,9 @@ async function installChrome() {
   response.on('data', chunk => {
     downloadedLength += chunk.length
     if (downloadedLength == contentLength) {
-      updateConsoleLog(`Downloading ${url} (${downloadedLength} / ${contentLength} bytes)\n`)
+      updateConsoleLog(`Downloading ${url} (${downloadedLength} / ${contentLength} bytes)\n`, platform)
     } else {
-      updateConsoleLog(`Downloading ${url} (${downloadedLength} / ${contentLength} bytes)`)
+      updateConsoleLog(`Downloading ${url} (${downloadedLength} / ${contentLength} bytes)`, platform)
     }
 
     fileStream.write(chunk)
@@ -97,7 +115,13 @@ async function installChrome() {
   })
   await promise
 
-  await extract(filepath, { dir: parentDir })
+  console.log('Extracting', filepath)
+  try {
+    await extract(filepath, { dir: parentDir })
+  } catch (_error) {
+    await sleep(1000)
+    await extract(filepath, { dir: parentDir })
+  }
 }
 
 async function getChromeFilepath() {
@@ -108,13 +132,15 @@ async function getChromeFilepath() {
 
   try {
     for await (const filepath of walk(parentDir)) {
-      console.log(filepath)
       if (platform.startsWith('mac') && filepath.endsWith('Google Chrome for Testing')) {
         return filepath
       }
       if (platform.startsWith('linux') && filepath.endsWith('chrome')) {
         return filepath
       }
+      if (platform.startsWith('win') && filepath.endsWith('chrome.exe')) {
+        return filepath
+      }
     }
   } catch (error) {
     if (error.code == 'ENOENT') {
@@ -139,11 +165,48 @@ 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`
+ *   * `win64`
+ *
+ * ## 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
+ * ```
  */
 class GoogleChromeForTesting {
   constructor(options = {}) {
@@ -151,8 +214,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
   }
 
@@ -163,8 +226,26 @@ 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)
 
     const cmd = spawn(chromeFilepath, [
@@ -172,22 +253,29 @@ class GoogleChromeForTesting {
       `--user-data-dir=${this.userDataDir}`,
       ...this.headless ? ['--headless'] : [],
       ...this.useMockKeychain ? ['--use-mock-keychain'] : [],
+      '--no-sandbox',
     ])
     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 => {
@@ -205,8 +293,10 @@ class GoogleChromeForTesting {
 
     this.cmd = cmd
 
-    await spawnPromiseWithResolvers.promise
-    this.devtoolsUrl = await devtoolsUrlPromiseWithResolvers.promise
+    await spawnPromise
+    this.devtoolsUrl = await devtoolsUrlPromise
+
+    return undefined
   }
 
   /**
@@ -216,6 +306,18 @@ class GoogleChromeForTesting {
    * ```coffeescript [specscript]
    * close() -> undefined
    * ```
+   *
+   * Terminates the Google Chrome for Testing process.
+   *
+   * Arguments:
+   *   * (none)
+   *
+   * Return:
+   *   * `undefined`
+   *
+   * ```javascript
+   * googleChromeForTesting.close()
+   * ```
    */
   close() {
     this.cmd.kill('SIGKILL')

package/README.md

@@ -323,10 +323,14 @@ await docker.createService({
 
 ## [Automate tests with Google Chrome for Testing](https://presidium.services/docs/GoogleChromeDevTools)
 ```javascript
+const GoogleChromeForTesting = require('presidium/GoogleChromeForTesting')
 const GoogleChromeDevTools = require('presidium/GoogleChromeDevTools')
 
-const googleChromeDevTools = new GoogleChromeDevTools()
-await googleChromeDevTools.init() // downloads Google Chrome for Testing
+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()

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.1.0",
+  "version": "3.3.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",

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