codeceptjs 4.2.0 → 4.2.1-beta.1

package/lib/plugin/sitemap.js

@@ -0,0 +1,228 @@
+import fs from 'fs'
+import path from 'path'
+import { isMainThread, threadId } from 'worker_threads'
+import { mkdirp } from 'mkdirp'
+import { DOMImplementation, XMLSerializer } from '@xmldom/xmldom'
+
+import Container from '../container.js'
+import event from '../event.js'
+import recorder from '../recorder.js'
+import store from '../store.js'
+import output from '../output.js'
+import { parsePluginArgs } from '../utils/pluginParser.js'
+
+const defaultConfig = {
+  file: 'sitemap.xml',
+  stripQuery: true,
+}
+
+const SITEMAP_NS = 'http://www.sitemaps.org/schemas/sitemap/0.9'
+const PARTIAL_PREFIX = '.sitemap.'
+
+/**
+ * Collects all pages visited while tests are running and saves them as a [sitemap](https://www.sitemaps.org/protocol.html) XML file.
+ *
+ * The plugin listens to browser navigation events, so it doesn't slow down test steps.
+ * Page loads and SPA route changes (`history.pushState`) of the top-level page are recorded, iframes are ignored.
+ * Every unique `http(s)` URL is added to the sitemap. URL fragments (`#...`) are dropped.
+ *
+ * Supported helpers: Playwright, Puppeteer, and WebDriver with BiDi protocol enabled (default).
+ * The sitemap is written once all tests finish.
+ *
+ * #### Configuration
+ *
+ * ```js
+ * "plugins": {
+ *    "sitemap": {
+ *      "enabled": true
+ *    }
+ *  }
+ * ```
+ *
+ * Possible config options:
+ *
+ * * `file`: path to the sitemap file, relative to the output directory. Default: `sitemap.xml`, saved as `output/sitemap.xml`.
+ * * `stripQuery`: remove query strings so `/posts?page=1` and `/posts?page=2` become one `/posts` entry. Set to `false` to keep them. Default: true.
+ *
+ * CLI examples:
+ *
+ * ```
+ * npx codeceptjs run -p sitemap
+ * npx codeceptjs run -p sitemap:file=visited.xml
+ * npx codeceptjs run -p sitemap:stripQuery=false
+ * ```
+ *
+ * Works with `run-workers`: URLs from all workers are merged into a single sitemap.
+ *
+ * @param {*} config
+ */
+export default function (config = {}) {
+  config = Object.assign({}, defaultConfig, config, parsePluginArgs(config._args))
+
+  const urls = new Set()
+
+  const outputDir = () => store.outputDir || process.cwd()
+
+  const addUrl = url => {
+    if (!url) return
+    let parsed
+    try {
+      parsed = new URL(url)
+    } catch {
+      return
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return
+    parsed.hash = ''
+    if (config.stripQuery) parsed.search = ''
+    urls.add(parsed.toString())
+  }
+
+  const writeSitemap = list => {
+    if (!list.length) return
+
+    const file = path.resolve(outputDir(), config.file)
+    mkdirp.sync(path.dirname(file))
+    fs.writeFileSync(file, buildXml(list.sort()))
+    output.plugin('sitemap', `Sitemap with ${list.length} pages saved to ${file}`)
+  }
+
+  const attached = new WeakSet()
+
+  const onLoad = page => addUrl(page.url())
+
+  const onFrameNavigated = frame => {
+    if (frame.parentFrame()) return
+    addUrl(frame.url())
+  }
+
+  const attachPage = page => {
+    if (!page || attached.has(page)) return
+    attached.add(page)
+    addUrl(page.url())
+    page.on('load', onLoad)
+    page.on('framenavigated', onFrameNavigated)
+  }
+
+  const attachContext = context => {
+    attached.add(context)
+    context.on('page', attachPage)
+    context.pages().forEach(attachPage)
+  }
+
+  const attachPlaywright = browser => {
+    if (!browser.contexts) return attachContext(browser)
+    attached.add(browser)
+    browser.on('context', attachContext)
+    browser.contexts().forEach(attachContext)
+  }
+
+  const attachPuppeteer = async browser => {
+    attached.add(browser)
+    browser.on('targetcreated', async target => {
+      if (target.type() !== 'page') return
+      attachPage(await target.page())
+    })
+    for (const page of await browser.pages()) attachPage(page)
+  }
+
+  const subscribeBidi = async browser => {
+    attached.add(browser)
+    const frames = new Set()
+    const onNavigation = params => {
+      if (frames.has(params.context)) return
+      addUrl(params.url)
+    }
+    browser.on('browsingContext.contextCreated', params => {
+      if (params.parent) frames.add(params.context)
+    })
+    browser.on('browsingContext.load', onNavigation)
+    browser.on('browsingContext.historyUpdated', onNavigation)
+    try {
+      await browser.sessionSubscribe({ events: ['browsingContext.contextCreated', 'browsingContext.load'] })
+    } catch (err) {
+      output.plugin('sitemap', `Can't subscribe to navigation events: ${err.message}`)
+    }
+    try {
+      await browser.sessionSubscribe({ events: ['browsingContext.historyUpdated'] })
+    } catch {}
+  }
+
+  event.dispatcher.on(event.test.started, () => {
+    const helpers = Container.helpers()
+
+    if (helpers.Playwright) {
+      const browser = helpers.Playwright.browser
+      if (browser && !attached.has(browser)) attachPlaywright(browser)
+      return
+    }
+
+    if (helpers.Puppeteer) {
+      const browser = helpers.Puppeteer.browser
+      if (!browser || attached.has(browser)) return
+      recorder.add('sitemap: listen to navigation', () => attachPuppeteer(browser), true)
+      return
+    }
+
+    if (helpers.WebDriver) {
+      const browser = helpers.WebDriver.browser
+      if (!browser || attached.has(browser)) return
+      if (!browser.capabilities || !browser.capabilities.webSocketUrl) {
+        attached.add(browser)
+        output.plugin('sitemap', 'WebDriver BiDi protocol is disabled, visited pages are not collected')
+        return
+      }
+      recorder.add('sitemap: subscribe to navigation', () => subscribeBidi(browser), true)
+    }
+  })
+
+  const partialFiles = dir => {
+    if (!fs.existsSync(dir)) return []
+    return fs
+      .readdirSync(dir)
+      .filter(name => name.startsWith(PARTIAL_PREFIX) && name.endsWith('.json'))
+      .map(name => path.join(dir, name))
+  }
+
+  event.dispatcher.on(event.all.result, () => {
+    if (isMainThread) {
+      if (store.workerMode) return
+      writeSitemap([...urls])
+      return
+    }
+    if (!urls.size) return
+    const dir = outputDir()
+    mkdirp.sync(dir)
+    fs.writeFileSync(path.join(dir, `${PARTIAL_PREFIX}${process.pid}.${threadId}.json`), JSON.stringify([...urls]))
+  })
+
+  event.dispatcher.on(event.workers.before, () => {
+    for (const partial of partialFiles(outputDir())) fs.unlinkSync(partial)
+  })
+
+  event.dispatcher.on(event.workers.result, () => {
+    for (const partial of partialFiles(outputDir())) {
+      try {
+        for (const url of JSON.parse(fs.readFileSync(partial, 'utf8'))) urls.add(url)
+      } catch {}
+      fs.unlinkSync(partial)
+    }
+    writeSitemap([...urls])
+  })
+}
+
+function buildXml(list) {
+  const doc = new DOMImplementation().createDocument(SITEMAP_NS, 'urlset', null)
+  const urlset = doc.documentElement
+  for (const url of list) {
+    const urlEl = doc.createElementNS(SITEMAP_NS, 'url')
+    const locEl = doc.createElementNS(SITEMAP_NS, 'loc')
+    locEl.appendChild(doc.createTextNode(url))
+    urlEl.appendChild(doc.createTextNode('\n    '))
+    urlEl.appendChild(locEl)
+    urlEl.appendChild(doc.createTextNode('\n  '))
+    urlset.appendChild(doc.createTextNode('\n  '))
+    urlset.appendChild(urlEl)
+  }
+  urlset.appendChild(doc.createTextNode('\n'))
+  return `<?xml version="1.0" encoding="UTF-8"?>\n${new XMLSerializer().serializeToString(doc)}\n`
+}

package/lib/recorder.js

@@ -202,34 +202,35 @@ export default {
     debug(chalk.gray(`${currentQueue()} Queued | ${taskName}`))
 
     return (promise = Promise.resolve(promise).then(res => {
-      // prefer options for non-conditional retries
-      const retryOpts = this.retries
-        .sort((r1, r2) => r1.when && !r2.when)
-        .slice(-1)
-        .pop()
-      // no retries or unnamed tasks
       debug(`${currentQueue()} Running | ${taskName} | Timeout: ${timeout || 'None'}`)
-      if (retryOpts) debug(`${currentQueue()} Retry opts`, JSON.stringify(retryOpts))
 
-      if (!retryOpts || !taskName || !retry) {
+      const runTask = () => {
         const [promise, timer] = getTimeoutPromise(timeout, taskName)
         return Promise.race([promise, Promise.resolve(res).then(fn)]).finally(() => clearTimeout(timer))
       }
 
+      // no retries or unnamed tasks
+      if (!this.retries.length || !taskName || !retry) return runTask()
+
       const retryRules = this.retries.slice().reverse()
-      return promiseRetry(Object.assign({}, defaultRetryOptions, retryOpts), (retry, number) => {
-        if (number > 1) output.log(`${currentQueue()}Retrying... Attempt #${number}`)
-        const [promise, timer] = getTimeoutPromise(timeout, taskName)
-        return Promise.race([promise, Promise.resolve(res).then(fn)])
-          .finally(() => clearTimeout(timer))
-          .catch(err => {
+      // prefer options for non-conditional retries, otherwise use the latest rule matching the error
+      const findRetryOpts = err => retryRules.find(r => !r.when) || retryRules.find(r => r.when(err))
+
+      return runTask().catch(firstErr => {
+        if (ignoredErrs.includes(firstErr)) return
+        const retryOpts = findRetryOpts(firstErr)
+        if (!retryOpts) throw firstErr
+        debug(`${currentQueue()} Retry opts`, JSON.stringify(retryOpts))
+
+        return promiseRetry(Object.assign({}, defaultRetryOptions, retryOpts), (retry, number) => {
+          if (number === 1) return retry(firstErr)
+          output.log(`${currentQueue()}Retrying... Attempt #${number}`)
+          return runTask().catch(err => {
             if (ignoredErrs.includes(err)) return
-            for (const retryObj of retryRules) {
-              if (!retryObj.when) return retry(err)
-              if (retryObj.when && retryObj.when(err)) return retry(err)
-            }
+            if (findRetryOpts(err)) return retry(err)
             throw err
           })
+        })
       })
     }))
   },

package/lib/result.js

@@ -216,6 +216,22 @@ class Result {
     fs.writeFileSync(path.join(store.outputDir, fileName), JSON.stringify(this.simplify(), null, 2))
   }
 
+  /**
+   * Loads tests that failed in a result saved by a previous run.
+   *
+   * @param {string} [outputDir] Directory containing the saved result. Defaults to `output_dir`.
+   * @param {string} [fileName] Path to the JSON file, relative to `outputDir`. Defaults to "result.json".
+   * @returns {Array<{uid: string, title: string, state: string}>} Serialized failed tests.
+   */
+  static loadFailedTests(outputDir = store.outputDir, fileName = 'result.json') {
+    const resultFile = path.join(outputDir, fileName)
+    if (!fs.existsSync(resultFile)) {
+      throw new Error(`No previous run found (${resultFile} does not exist), run tests once first`)
+    }
+    const { tests = [] } = JSON.parse(fs.readFileSync(resultFile, 'utf8'))
+    return tests.filter(test => test.state === 'failed')
+  }
+
   /**
    * Adds stats to this result.
    *

package/lib/step/base.js

@@ -52,6 +52,18 @@ class Step {
     this.setTrace()
   }
 
+  /**
+   * Alias of `title`, the name of the helper method this step executes
+   * @type {string}
+   */
+  get name() {
+    return this.title
+  }
+
+  set name(name) {
+    this.title = name
+  }
+
   setMetaStep(metaStep) {
     this.metaStep = metaStep
   }

package/lib/utils.js

@@ -372,11 +372,7 @@ function shouldAppendBaseUrl(url) {
 }
 
 function trimUrl(url) {
-  const firstChar = url.substr(1)
-  if (firstChar === '/') {
-    url = url.slice(1)
-  }
-  return url
+  return url.replace(/^\/+/, '')
 }
 
 function joinUrl(baseUrl, url) {
@@ -390,11 +386,7 @@ export const appendBaseUrl = function (baseUrl = '', oneOrMoreUrls) {
   if (!(typeof oneOrMoreUrls === 'string' || Array.isArray(oneOrMoreUrls))) {
     throw new Error(`Expected type of Urls is 'string' or 'array', Found '${typeof oneOrMoreUrls}'.`)
   }
-  // Remove '/' if it's at the end of baseUrl
-  const lastChar = baseUrl.substr(-1)
-  if (lastChar === '/') {
-    baseUrl = baseUrl.slice(0, -1)
-  }
+  baseUrl = baseUrl.replace(/\/+$/, '')
 
   if (!Array.isArray(oneOrMoreUrls)) {
     return joinUrl(baseUrl, oneOrMoreUrls)

package/lib/webServer.js

@@ -0,0 +1,193 @@
+import { spawn, spawnSync } from 'child_process'
+import path from 'path'
+import output from './output.js'
+import store from './store.js'
+import { isWindows } from './utils.js'
+
+const TAIL_SIZE = 20
+const KILL_TIMEOUT = 5000
+const SIGNALS = ['SIGINT', 'SIGTERM']
+
+class WebServer {
+  static running = []
+
+  static signalHandlers = Object.fromEntries(SIGNALS.map(signal => [signal, () => WebServer.onSignal(signal)]))
+
+  constructor(config) {
+    const { command, url, enabled = true, timeout = 60000, cwd = '.', env = {} } = config
+    if (!command) throw new Error('webServer: "command" is required')
+    if (!url) throw new Error(`webServer: "url" is required for "${command}"`)
+    this.command = command
+    this.url = url
+    this.enabled = enabled
+    this.timeout = timeout
+    this.cwd = cwd
+    this.env = env
+    this.tail = []
+    this.proc = null
+  }
+
+  static async startAll(config) {
+    if (!config) return
+    const configs = Array.isArray(config) ? config : [config]
+    for (const serverConfig of configs) {
+      await new WebServer(serverConfig).start()
+    }
+  }
+
+  static async stopAll() {
+    while (WebServer.running.length) {
+      await WebServer.running[WebServer.running.length - 1].stop()
+      WebServer.running.pop()
+    }
+    WebServer.removeListeners()
+  }
+
+  static killAllSync() {
+    for (const server of WebServer.running) server.kill('SIGKILL')
+  }
+
+  static onSignal(signal) {
+    WebServer.killAllSync()
+    WebServer.removeListeners()
+    if (process.listenerCount(signal) === 0) process.kill(process.pid, signal)
+  }
+
+  static addListeners() {
+    if (WebServer.running.length) return
+    process.on('exit', WebServer.killAllSync)
+    for (const signal of SIGNALS) process.on(signal, WebServer.signalHandlers[signal])
+  }
+
+  static removeListeners() {
+    process.removeListener('exit', WebServer.killAllSync)
+    for (const signal of SIGNALS) process.removeListener(signal, WebServer.signalHandlers[signal])
+  }
+
+  async isUp() {
+    try {
+      const res = await fetch(this.url, { method: 'GET', redirect: 'manual', signal: AbortSignal.timeout(1000) })
+      await res.body?.cancel().catch(() => {})
+      return true
+    } catch (err) {
+      return false
+    }
+  }
+
+  async start() {
+    if (!this.enabled) return
+
+    if (await this.isUp()) {
+      output.print(`Reusing web server at ${this.url}`)
+      return
+    }
+
+    output.print(`Starting web server: ${this.command}`)
+
+    this.proc = spawn(this.command, {
+      shell: true,
+      detached: !isWindows(),
+      cwd: path.resolve(store.codeceptDir || process.cwd(), this.cwd),
+      env: { ...process.env, ...this.env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+
+    this.collect(this.proc.stdout)
+    this.collect(this.proc.stderr)
+
+    WebServer.addListeners()
+    WebServer.running.push(this)
+
+    let exited = null
+    const closed = new Promise(resolve => this.proc.once('close', resolve))
+    this.proc.once('error', err => {
+      exited = `failed to start: ${err.message}`
+    })
+    this.proc.once('exit', (code, signal) => {
+      exited = `exited with ${signal ? `signal ${signal}` : `code ${code}`}`
+    })
+
+    const deadline = Date.now() + this.timeout
+    let delay = 100
+    while (true) {
+      if (exited) {
+        await Promise.race([closed, new Promise(resolve => setTimeout(resolve, 500))])
+        await WebServer.stopAll()
+        throw new Error(`webServer "${this.command}" ${exited} before ${this.url} was ready.${this.formatTail()}`)
+      }
+      if (await this.isUp()) break
+      if (Date.now() >= deadline) {
+        await WebServer.stopAll()
+        throw new Error(`webServer "${this.command}" did not respond at ${this.url} within ${this.timeout}ms.${this.formatTail()}`)
+      }
+      await new Promise(resolve => setTimeout(resolve, delay))
+      delay = Math.min(delay * 2, 1000)
+    }
+  }
+
+  async stop() {
+    if (!this.proc) return
+    this.kill('SIGTERM')
+    await this.waitForExit()
+    this.proc.stdout?.destroy()
+    this.proc.stderr?.destroy()
+  }
+
+  kill(signal) {
+    const { proc } = this
+    if (!proc?.pid) return
+    try {
+      if (isWindows()) {
+        if (proc.exitCode !== null) return
+        spawnSync('taskkill', ['/pid', String(proc.pid), '/T', '/F'])
+      } else {
+        process.kill(-proc.pid, signal)
+      }
+    } catch (err) {
+      try {
+        proc.kill(signal)
+      } catch (e) {}
+    }
+  }
+
+  waitForExit() {
+    const { proc } = this
+    return new Promise(resolve => {
+      if (proc.exitCode !== null || proc.signalCode !== null) return resolve()
+      let killTimer
+      let safetyTimer
+      const finish = () => {
+        clearTimeout(killTimer)
+        clearTimeout(safetyTimer)
+        resolve()
+      }
+      proc.once('exit', finish)
+      killTimer = setTimeout(() => this.kill('SIGKILL'), KILL_TIMEOUT)
+      safetyTimer = setTimeout(finish, KILL_TIMEOUT + 500)
+    })
+  }
+
+  collect(stream) {
+    let rest = ''
+    stream.on('data', chunk => {
+      const lines = (rest + chunk.toString()).split(/\r?\n/)
+      rest = lines.pop()
+      for (const line of lines) this.addLine(line)
+    })
+    stream.on('end', () => this.addLine(rest))
+  }
+
+  addLine(line) {
+    if (!line.trim()) return
+    this.tail.push(line)
+    if (this.tail.length > TAIL_SIZE) this.tail.shift()
+    if (store.debugMode || output.level() >= 2) output.print(output.styles.debug(`[webServer] ${line}`))
+  }
+
+  formatTail() {
+    if (!this.tail.length) return '\n(no output)'
+    return `\nLast output:\n${this.tail.join('\n')}`
+  }
+}
+
+export default WebServer