codeceptjs 4.0.0-rc.17 → 4.0.0-rc.19

package/lib/plugin/browser.js

@@ -0,0 +1,77 @@
+import output from '../output.js'
+
+/**
+ * Overrides browser helper config from the command line. Works for all browser helpers
+ * (Playwright, Puppeteer, WebDriver, Appium) without touching `codecept.conf`.
+ *
+ * Enable it via `-p` option with one or more colon-chained args:
+ *
+ * ```
+ * npx codeceptjs run -p browser:show
+ * npx codeceptjs run -p browser:hide
+ * npx codeceptjs run -p browser:browser=firefox
+ * npx codeceptjs run -p browser:windowSize=1024x768:video=false
+ * npx codeceptjs run -p browser:hide:browser=webkit:windowSize=800x600
+ * ```
+ *
+ * #### Args
+ *
+ * * **show** — force visible browser
+ * * **hide** — force headless (also injects `--headless` into WebDriver chrome/firefox capability args)
+ * * **`<key>=<value>`** — set `helpers.<eachBrowserHelper>.<key> = <value>`. Three keys
+ *   get per-helper translation via `setBrowserConfig`:
+ *     * `browser=<name>` — Puppeteer receives `product`, Playwright receives `browser`
+ *     * `windowSize=WxH` — also adds `--window-size=W,H` chromium/chrome args
+ *     * `show=true|false` — toggles `show` on Playwright/Puppeteer; injects/strips
+ *       `--headless` in WebDriver chrome/firefox capability args
+ *
+ * Values stay as strings. `true` / `false` are coerced to booleans.
+ *
+ * Requires `@codeceptjs/configure` to be installed; if missing, the plugin
+ * logs a hint and skips the override.
+ */
+export default async function (config = {}) {
+  const { _args, enabled, ...rest } = config
+  const opts = { ...rest, ...parseArgs(_args || []) }
+  if (Object.keys(opts).length === 0) return
+
+  const configure = await tryImportConfigure()
+  if (!configure) return
+
+  configure.setBrowserConfig(opts)
+  output.debug(`browser plugin: applied ${formatOpts(opts)}`)
+}
+
+async function tryImportConfigure() {
+  try {
+    return await import('@codeceptjs/configure')
+  } catch (err) {
+    output.error("browser plugin: '@codeceptjs/configure' is not installed; CLI overrides are skipped. Run `npm i @codeceptjs/configure` to enable.")
+    return null
+  }
+}
+
+function parseArgs(args) {
+  return args.filter(Boolean).reduce((acc, arg) => Object.assign(acc, parseArg(arg)), {})
+}
+
+function parseArg(arg) {
+  if (arg === 'show') return { show: true }
+  if (arg === 'hide') return { show: false }
+  if (arg.includes('=')) {
+    const [key, ...rest] = arg.split('=')
+    return { [key]: parseValue(rest.join('=')) }
+  }
+  output.error(`browser plugin: unknown arg "${arg}"`)
+  return {}
+}
+
+function parseValue(v) {
+  if (v === 'true') return true
+  if (v === 'false') return false
+  return v
+}
+
+function formatOpts(opts) {
+  return Object.entries(opts).map(([k, v]) => `${k}=${v}`).join(', ')
+}

package/lib/plugin/expose.js

@@ -0,0 +1,159 @@
+import Container from '../container.js'
+
+const RESERVED_NAMES = new Set(['I', 'test', 'suite'])
+const SHORTHAND_PROPERTIES = new Set(['page', 'browser', 'browserContext', 'context'])
+
+const defaultConfig = {
+  inject: {},
+}
+
+/**
+ * Exposes properties from helper instances as injectable test arguments.
+ * Use it to access the underlying Playwright/Puppeteer `page`, the wdio `browser` client,
+ * or any other helper internal directly from a Scenario:
+ *
+ * ```js
+ * Scenario('listen for requests', async ({ I, page, browser }) => {
+ *   page.on('request', r => console.log(r.url()))
+ *   await page.evaluate(() => 1 + 1)
+ *   I.amOnPage('/')
+ * })
+ * ```
+ *
+ * The injected value is a live proxy: every property access reads the *current*
+ * helper property, so mid-test reassignments (popups, `switchToNextTab`,
+ * `openNewTab`) are reflected automatically. Calls are not wrapped as
+ * CodeceptJS steps — `await page.evaluate(...)` runs as native Playwright.
+ *
+ * #### Configuration
+ *
+ * `inject` maps an injection name to a `HelperName.propertyName` string. A
+ * value with no dot is shorthand for "first configured browser helper that
+ * exposes this property" (allowed properties: `page`, `browser`,
+ * `browserContext`, `context`).
+ *
+ * ```js
+ * plugins: {
+ *   expose: {
+ *     enabled: true,
+ *     inject: {
+ *       page: 'Playwright.page',
+ *       browser: 'Playwright.browser',
+ *       browserContext: 'Playwright.browserContext',
+ *       frame: 'Playwright.context',  // current frame set by switchTo
+ *       wdio: 'WebDriver.browser',
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Shorthand:
+ *
+ * ```js
+ * plugins: {
+ *   expose: {
+ *     enabled: true,
+ *     inject: {
+ *       page: 'page',  // resolves to Playwright.page or Puppeteer.page
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * #### Caveats
+ *
+ * - The injected value is a `Proxy`, not the actual `Page`/`Browser` instance,
+ *   so `page instanceof Page` is `false`. Use duck typing instead.
+ * - Cached method references lose the live binding. Call `page.click(...)`,
+ *   not `const click = page.click; click(...)`.
+ * - In dry-run mode the underlying helper property is `undefined`; accessing
+ *   any property on the proxy returns `undefined` rather than throwing.
+ */
+export default function (config = {}) {
+  config = { ...defaultConfig, ...config }
+
+  const mappings = parseMappings(config.inject)
+
+  const support = {}
+  for (const [name, { helperName, property }] of Object.entries(mappings)) {
+    support[name] = makeLiveProxy(helperName, property)
+  }
+  Container.append({ support })
+}
+
+function parseMappings(inject) {
+  const out = {}
+  for (const [name, value] of Object.entries(inject || {})) {
+    if (RESERVED_NAMES.has(name)) {
+      throw new Error(`expose plugin: inject name '${name}' is reserved`)
+    }
+    if (typeof value !== 'string' || !value) {
+      throw new Error(`expose plugin: inject value for '${name}' must be a non-empty string`)
+    }
+
+    let helperName
+    let property
+
+    if (value.includes('.')) {
+      const dot = value.indexOf('.')
+      helperName = value.slice(0, dot)
+      property = value.slice(dot + 1)
+      if (!helperName || !property) {
+        throw new Error(`expose plugin: invalid inject value '${value}' for '${name}' (expected 'HelperName.propertyName')`)
+      }
+      if (!Container.helpers(helperName)) {
+        throw new Error(`expose plugin: helper '${helperName}' is not configured (needed for inject '${name}')`)
+      }
+    } else {
+      property = value
+      if (!SHORTHAND_PROPERTIES.has(property)) {
+        throw new Error(`expose plugin: shorthand '${property}' is not a known helper property for '${name}' (use 'HelperName.${property}' instead)`)
+      }
+      helperName = Container.STANDARD_ACTING_HELPERS.find(h => Container.helpers(h))
+      if (!helperName) {
+        throw new Error(`expose plugin: no standard browser helper configured (needed for inject '${name}')`)
+      }
+    }
+
+    out[name] = { helperName, property }
+  }
+  return out
+}
+
+function makeLiveProxy(helperName, property) {
+  const resolve = () => Container.helpers(helperName)?.[property]
+  return new Proxy(function () {}, {
+    get(_, prop) {
+      const target = resolve()
+      if (target == null) return undefined
+      const value = target[prop]
+      if (typeof value === 'function') return value.bind(target)
+      return value
+    },
+    has(_, prop) {
+      const target = resolve()
+      return target != null && prop in target
+    },
+    apply(_, thisArg, args) {
+      const target = resolve()
+      return target?.apply(thisArg, args)
+    },
+    set(_, prop, value) {
+      const target = resolve()
+      if (target != null) target[prop] = value
+      return true
+    },
+    getPrototypeOf() {
+      const target = resolve()
+      return target != null ? Object.getPrototypeOf(target) : null
+    },
+    ownKeys() {
+      const target = resolve()
+      return target != null ? Reflect.ownKeys(target) : []
+    },
+    getOwnPropertyDescriptor(_, prop) {
+      const target = resolve()
+      return target != null ? Object.getOwnPropertyDescriptor(target, prop) : undefined
+    },
+  })
+}

package/lib/plugin/heal.js

@@ -10,21 +10,30 @@ import output from '../output.js'
 import healModule from '../heal.js'
 const heal = healModule.default || healModule
 import store from '../store.js'
+import {
+  parsePluginArgs,
+  resolveTrigger,
+  matchStepFile,
+  matchUrl,
+  getBrowserHelper,
+} from '../utils/pluginParser.js'
 
 
 const defaultConfig = {
+  on: 'fail',
   healLimit: 2,
 }
 
 /**
  * Self-healing tests with AI.
  *
- * Read more about heaking in [Self-Healing Tests](https://codecept.io/heal/)
+ * Read more about healing in [Self-Healing Tests](https://codecept.io/heal/)
  *
  * ```js
  * plugins: {
  *   heal: {
  *    enabled: true,
+ *    on: 'fail',
  *   }
  * }
  * ```
@@ -32,7 +41,17 @@ const defaultConfig = {
  * More config options are available:
  *
  * * `healLimit` - how many steps can be healed in a single test (default: 2)
+ * * `on` - trigger mode. `fail` (default), `file` (filter to a path), `url` (filter to a URL pattern).
  *
+ * #### `on=` modes
+ *
+ * Heal always runs on step failures; `on=` narrows when it engages.
+ *
+ * * **fail** — heal any failing step (default)
+ * * **file** — heal only failures in `path=...[;line=...]`
+ * * **url** — heal only failures when the current URL matches `pattern=...`
+ *
+ * `on=step` and `on=test` are not supported and are rejected with an error.
  */
 export default function (config = {}) {
   if (store.debugMode && !process.env.DEBUG) {
@@ -42,6 +61,13 @@ export default function (config = {}) {
     return
   }
 
+  const cliArgs = parsePluginArgs(config._args)
+  const trigger = resolveTrigger(cliArgs, config, { on: defaultConfig.on }, {
+    name: 'heal',
+    validModes: ['fail', 'file', 'url'],
+  })
+  if (!trigger) return
+
   let currentTest = null
   let currentStep = null
   let healedSteps = 0
@@ -65,6 +91,8 @@ export default function (config = {}) {
 
     if (!heal.hasCorrespondingRecipes(step)) return
 
+    if (trigger.on === 'file' && !matchStepFile(step, trigger.path, trigger.line)) return
+
     recorder.catchWithoutStop(async err => {
       isHealing = true
       if (caughtError === err) throw err // avoid double handling
@@ -72,6 +100,21 @@ export default function (config = {}) {
 
       const test = currentTest
 
+      if (trigger.on === 'url') {
+        try {
+          const helper = getBrowserHelper()
+          const url = helper && helper.grabCurrentUrl ? await helper.grabCurrentUrl() : null
+          if (!matchUrl(url, trigger.pattern)) {
+            isHealing = false
+            throw err
+          }
+        } catch (e) {
+          if (e === err) throw e
+          isHealing = false
+          throw err
+        }
+      }
+
       recorder.session.start('heal')
 
       debug('Self-healing started', step.toCode())

package/lib/plugin/pageInfo.js

@@ -1,14 +1,15 @@
 import path from 'path'
 import fs from 'fs'
 import Container from '../container.js'
-const supportedHelpers = Container.STANDARD_ACTING_HELPERS
 import recorder from '../recorder.js'
 import event from '../event.js'
 import { scanForErrorMessages } from '../html.js'
+import { captureSnapshot, pickActingHelper } from '../utils/trace.js'
 import { output } from '../index.js'
 import store from '../store.js'
 import { humanizeString, ucfirst } from '../utils.js'
 import { testToFileName } from '../mocha/test.js'
+
 const defaultConfig = {
   errorClasses: ['error', 'warning', 'alert', 'danger'],
   browserLogs: ['error'],
@@ -37,57 +38,58 @@ const defaultConfig = {
  *
  */
 export default function (config = {}) {
-  const helpers = Container.helpers()
-  let helper
-
   config = Object.assign(defaultConfig, config)
 
-  for (const helperName of supportedHelpers) {
-    if (Object.keys(helpers).indexOf(helperName) > -1) {
-      helper = helpers[helperName]
-    }
-  }
-
-  if (!helper) return // no helpers for screenshot
+  const helper = pickActingHelper(Container.helpers())
+  if (!helper) return
 
   event.dispatcher.on(event.test.failed, test => {
     const pageState = {}
 
-    recorder.add('URL of failed test', async () => {
-      try {
-        const url = await helper.grabCurrentUrl()
-        pageState.url = url
-      } catch (err) {
-        // not really needed
-      }
-    })
-    recorder.add('HTML snapshot failed test', async () => {
+    recorder.add('pageInfo capture', async () => {
       try {
-        const html = await helper.grabHTMLFrom('body')
-
-        if (!html) return
-
-        const errors = scanForErrorMessages(html, config.errorClasses)
-        if (errors.length) {
-          output.debug('Detected errors in HTML code')
-          errors.forEach(error => output.debug(error))
-          pageState.htmlErrors = errors
+        const prefix = `${testToFileName(test)}.pageInfo`
+        const captured = await captureSnapshot(helper, {
+          dir: store.outputDir,
+          prefix,
+          captureScreenshot: false,
+        })
+
+        if (captured.url) pageState.url = captured.url
+
+        if (captured.html) {
+          const htmlPath = path.join(store.outputDir, captured.html)
+          pageState.htmlSnapshot = htmlPath
+          // Scan raw HTML (pre-cleanHtml) so error classes containing digits
+          // or trash-class prefixes aren't stripped before detection.
+          const htmlForScan = captured.htmlRaw || (() => {
+            try { return fs.readFileSync(htmlPath, 'utf8') } catch { return '' }
+          })()
+          if (htmlForScan) {
+            try {
+              const errors = scanForErrorMessages(htmlForScan, config.errorClasses)
+              if (errors.length) {
+                output.debug('Detected errors in HTML code')
+                errors.forEach(error => output.debug(error))
+                pageState.htmlErrors = errors
+              }
+            } catch {}
+          }
         }
-      } catch (err) {
-        // not really needed
-      }
-    })
-
-    recorder.add('Browser logs for failed test', async () => {
-      try {
-        const logs = await helper.grabBrowserLogs()
 
-        if (!logs) return
+        if (captured.aria) {
+          pageState.ariaSnapshot = path.join(store.outputDir, captured.aria)
+        }
 
-        pageState.browserErrors = getBrowserErrors(logs, config.browserLogs)
-      } catch (err) {
-        // not really needed
-      }
+        if (captured.console) {
+          const consolePath = path.join(store.outputDir, captured.console)
+          pageState.consoleSnapshot = consolePath
+          try {
+            const logs = JSON.parse(fs.readFileSync(consolePath, 'utf8'))
+            pageState.browserErrors = getBrowserErrors(logs, config.browserLogs)
+          } catch {}
+        }
+      } catch {}
     })
 
     recorder.add('Save page info', () => {
@@ -127,15 +129,16 @@ function pageStateToMarkdown(pageState) {
 }
 
 function getBrowserErrors(logs, type = ['error']) {
-  // Playwright & WebDriver console messages
-  let errors = logs
+  // Accepts Playwright ConsoleMessage objects, normalized {type, text}, or strings
+  return logs
     .map(log => {
       if (typeof log === 'string') return log
-      if (!log.type) return null
-      return { type: log.type(), text: log.text() }
+      if (!log) return null
+      const t = typeof log.type === 'function' ? log.type() : log.type
+      const text = typeof log.text === 'function' ? log.text() : log.text
+      if (!t) return null
+      return { type: t, text }
     })
     .filter(l => l && (typeof l === 'string' || type.includes(l.type)))
     .map(l => (typeof l === 'string' ? l : l.text))
-
-  return errors
 }

package/lib/plugin/pause.js

@@ -0,0 +1,131 @@
+import event from '../event.js'
+import pause from '../pause.js'
+import recorder from '../recorder.js'
+import output from '../output.js'
+import {
+  parsePluginArgs,
+  resolveTrigger,
+  matchStepFile,
+  matchUrl,
+  getBrowserHelper,
+} from '../utils/pluginParser.js'
+
+/**
+ * Pauses test execution interactively. Replaces the legacy `pauseOnFail`
+ * plugin. The default `on=fail` matches the old `pauseOnFail` behavior.
+ *
+ * #### Configuration
+ *
+ * ```js
+ * plugins: {
+ *   pause: {
+ *     enabled: false,
+ *     on: 'fail',
+ *   }
+ * }
+ * ```
+ *
+ * #### `on=` modes
+ *
+ * * **fail** — pause when a step fails (default)
+ * * **test** — pause after each test
+ * * **step** — pause before the first step (interactive walk-through)
+ * * **file** — pause when execution reaches `path=...[;line=...]`
+ * * **url** — pause when the browser URL matches `pattern=...`
+ *
+ * CLI examples:
+ *
+ * ```
+ * npx codeceptjs run -p pause
+ * npx codeceptjs run -p pause:on=step
+ * npx codeceptjs run -p pause:on=file:path=tests/login_test.js;line=43
+ * npx codeceptjs run -p pause:on=url:pattern=/users/*
+ * ```
+ */
+export default function (config = {}) {
+  const cliArgs = parsePluginArgs(config._args)
+  const trigger = resolveTrigger(cliArgs, config, { on: 'fail' }, { name: 'pause' })
+  if (!trigger) return
+
+  switch (trigger.on) {
+    case 'fail':
+      return initFailMode()
+    case 'test':
+      return initTestMode()
+    case 'step':
+      return initStepMode()
+    case 'file':
+      return initFileMode(trigger.path, trigger.line)
+    case 'url':
+      return initUrlMode(trigger.pattern)
+  }
+}
+
+function initFailMode() {
+  let failed = false
+
+  event.dispatcher.on(event.test.started, () => {
+    failed = false
+  })
+
+  event.dispatcher.on(event.step.failed, () => {
+    failed = true
+  })
+
+  event.dispatcher.on(event.test.after, () => {
+    if (failed) pause()
+  })
+}
+
+function initTestMode() {
+  event.dispatcher.on(event.test.after, () => pause())
+}
+
+function initStepMode() {
+  let activated = false
+
+  event.dispatcher.on(event.test.before, () => {
+    if (activated) return
+    activated = true
+    recorder.add('pause:step', () => pause())
+  })
+}
+
+function initFileMode(targetPath, targetLine) {
+  let paused = false
+
+  event.dispatcher.on(event.step.before, step => {
+    if (paused) return
+    if (!matchStepFile(step, targetPath, targetLine)) return
+    paused = true
+    recorder.add('pause:file', () => pause())
+  })
+}
+
+function initUrlMode(pattern) {
+  const helper = getBrowserHelper()
+
+  if (!helper) {
+    output.error('pause:on=url requires a browser helper (Playwright, WebDriver, Puppeteer, Appium)')
+    return
+  }
+
+  let paused = false
+
+  event.dispatcher.on(event.step.after, () => {
+    if (paused) return
+
+    recorder.add('pause:url check', async () => {
+      if (paused) return
+      try {
+        const currentUrl = await helper.grabCurrentUrl()
+        if (matchUrl(currentUrl, pattern)) {
+          paused = true
+          return pause()
+        }
+      } catch (err) {
+        // page may not be loaded yet
+      }
+    })
+  })
+}

package/lib/plugin/pauseOnFail.js

@@ -1,39 +1,15 @@
-import event from '../event.js'
+import output from '../output.js'
+import pause from './pause.js'
 
-import pause from '../pause.js'
+let warned = false
 
 /**
- * Automatically launches [interactive pause](/basics/#pause) when a test fails.
- *
- * Useful for debugging flaky tests on local environment.
- * Add this plugin to config file:
- *
- * ```js
- * plugins: {
- *   pauseOnFail: {},
- * }
- * ```
- *
- * Unlike other plugins, `pauseOnFail` is not recommended to be enabled by default.
- * Enable it manually on each run via `-p` option:
- *
- * ```
- * npx codeceptjs run -p pauseOnFail
- * ```
- *
+ * @deprecated Use the `pause` plugin with `on: 'fail'` (the default).
  */
-export default function() {
-  let failed = false
-
-  event.dispatcher.on(event.test.started, () => {
-    failed = false
-  })
-
-  event.dispatcher.on(event.step.failed, () => {
-    failed = true
-  })
-
-  event.dispatcher.on(event.test.after, () => {
-    if (failed) pause()
-  })
+export default function (config = {}) {
+  if (!warned) {
+    output.error('pauseOnFail is deprecated; use the `pause` plugin (default on=fail).')
+    warned = true
+  }
+  return pause({ ...config, on: 'fail' })
 }