codeceptjs 4.0.1-beta.9 → 4.0.1

package/lib/plugin/screenshotOnFail.js

@@ -1,178 +1,17 @@
-import fs from 'fs'
-import path from 'path'
-
-import Container from '../container.js'
-
-import recorder from '../recorder.js'
-
-import event from '../event.js'
-
 import output from '../output.js'
+import screenshot from './screenshot.js'
 
-import { fileExists } from '../utils.js'
-import Codeceptjs from '../index.js'
-import { testToFileName } from '../mocha/test.js'
-
-const defaultConfig = {
-  uniqueScreenshotNames: false,
-  disableScreenshots: false,
-  fullPageScreenshots: false,
-}
-
-const supportedHelpers = Container.STANDARD_ACTING_HELPERS
+let warned = false
 
 /**
- * Creates screenshot on failure. Screenshot is saved into `output` directory.
- *
- * Initially this functionality was part of corresponding helper but has been moved into plugin since 1.4
- *
- * This plugin is **enabled by default**.
- *
- * #### Configuration
- *
- * Configuration can either be taken from a corresponding helper (deprecated) or a from plugin config (recommended).
- *
- * ```js
- * plugins: {
- *    screenshotOnFail: {
- *      enabled: true
- *    }
- * }
- * ```
- *
- * Possible config options:
- *
- * * `uniqueScreenshotNames`: use unique names for screenshot. Default: false.
- * * `fullPageScreenshots`: make full page screenshots. Default: false.
- *
+ * Saves a screenshot when a test fails.
  *
+ * **Deprecated:** use the `screenshot` plugin with `on: 'fail'`, which is the default behavior.
  */
-export default function (config) {
-  const helpers = Container.helpers()
-  let helper
-
-  for (const helperName of supportedHelpers) {
-    if (Object.keys(helpers).indexOf(helperName) > -1) {
-      helper = helpers[helperName]
-    }
-  }
-
-  if (!helper) return // no helpers for screenshot
-
-  const options = Object.assign(defaultConfig, helper.options, config)
-
-  if (helpers.Mochawesome) {
-    if (helpers.Mochawesome.config) {
-      options.uniqueScreenshotNames = helpers.Mochawesome.config.uniqueScreenshotNames
-    }
-  }
-
-  if (Codeceptjs.container.mocha()) {
-    options.reportDir = Codeceptjs.container.mocha()?.options?.reporterOptions && Codeceptjs.container.mocha()?.options?.reporterOptions?.reportDir
+export default function (config = {}) {
+  if (!warned) {
+    output.error('screenshotOnFail is deprecated; use the `screenshot` plugin (default on=fail).')
+    warned = true
   }
-
-  if (options.disableScreenshots) {
-    // old version of disabling screenshots
-    return
-  }
-
-  event.dispatcher.on(event.test.failed, (test, _err, hookName) => {
-    if (hookName === 'BeforeSuite' || hookName === 'AfterSuite') {
-      // no browser here
-      return
-    }
-
-    recorder.add(
-      'screenshot of failed test',
-      async () => {
-        const dataType = 'image/png'
-        // This prevents data driven to be included in the failed screenshot file name
-        let fileName
-
-        if (options.uniqueScreenshotNames && test) {
-          fileName = `${testToFileName(test, { suffix: '', unique: true })}.failed.png`
-        } else {
-          fileName = `${testToFileName(test, { suffix: '', unique: false })}.failed.png`
-        }
-        const quietMode = !('output_dir' in global) || !global.output_dir
-        if (!quietMode) {
-          output.plugin('screenshotOnFail', 'Test failed, try to save a screenshot')
-        }
-
-        // Re-check helpers at runtime in case they weren't ready during plugin init
-        const runtimeHelpers = Container.helpers()
-        let runtimeHelper = null
-        for (const helperName of supportedHelpers) {
-          if (Object.keys(runtimeHelpers).indexOf(helperName) > -1) {
-            runtimeHelper = runtimeHelpers[helperName]
-            break
-          }
-        }
-
-        if (runtimeHelper && typeof runtimeHelper.saveScreenshot === 'function') {
-          helper = runtimeHelper
-        }
-
-        try {
-          if (options.reportDir) {
-            fileName = path.join(options.reportDir, fileName)
-            const mochaReportDir = path.resolve(process.cwd(), options.reportDir)
-            if (!fileExists(mochaReportDir)) {
-              fs.mkdirSync(mochaReportDir)
-            }
-          }
-
-          // Check if browser/page is still available before attempting screenshot
-          if (helper.page && helper.page.isClosed && helper.page.isClosed()) {
-            throw new Error('Browser page has been closed')
-          }
-          if (helper.browser && helper.browser.isConnected && !helper.browser.isConnected()) {
-            throw new Error('Browser has been disconnected')
-          }
-
-          // Add timeout wrapper to prevent hanging with shorter timeout for ESM
-          const screenshotPromise = helper.saveScreenshot(fileName, options.fullPageScreenshots)
-          const timeoutPromise = new Promise((_, reject) => {
-            setTimeout(() => reject(new Error('Screenshot timeout after 5 seconds')), 5000)
-          })
-
-          await Promise.race([screenshotPromise, timeoutPromise])
-
-          if (!test.artifacts) test.artifacts = {}
-          // Some unit tests may not define global.output_dir; avoid throwing when it is undefined
-          // Detect output directory safely (may not be initialized in narrow unit tests)
-          const baseOutputDir = 'output_dir' in global && typeof global.output_dir === 'string' && global.output_dir ? global.output_dir : null
-          if (baseOutputDir) {
-            test.artifacts.screenshot = path.join(baseOutputDir, fileName)
-            if (Container.mocha().options.reporterOptions['mocha-junit-reporter'] && Container.mocha().options.reporterOptions['mocha-junit-reporter'].options.attachments) {
-              test.attachments = [path.join(baseOutputDir, fileName)]
-            }
-          } else {
-            // Fallback: just store the file name to keep tests stable without triggering path errors
-            test.artifacts.screenshot = fileName
-          }
-        } catch (err) {
-          if (!quietMode) {
-            output.plugin('screenshotOnFail', `Failed to save screenshot: ${err.message}`)
-          }
-          // Enhanced error handling for browser closed scenarios
-          if (
-            err &&
-            ((err.message &&
-              (err.message.includes('Target page, context or browser has been closed') ||
-                err.message.includes('Browser page has been closed') ||
-                err.message.includes('Browser has been disconnected') ||
-                err.message.includes('was terminated due to') ||
-                err.message.includes('no such window: target window already closed') ||
-                err.message.includes('Screenshot timeout after'))) ||
-              (err.type && err.type === 'RuntimeError'))
-          ) {
-            output.log(`Can't make screenshot, ${err.message}`)
-            helper.isRunning = false
-          }
-        }
-      },
-      true,
-    )
-  })
+  return screenshot({ ...config, on: 'fail' })
 }

package/lib/plugin/stepTimeout.js

@@ -32,7 +32,7 @@ const defaultConfig = {
  * #### Configuration:
  *
  * * `timeout` - global step timeout, default 150 seconds
- * * `overrideStepLimits` - whether to use timeouts set in plugin config to override step timeouts set in code with I.limitTime(x).action(...), default false
+ * * `overrideStepLimits` - whether to use timeouts set in plugin config to override step timeouts set in code with `I.action(..., step.timeout(x))`, default false
  * * `noTimeoutSteps` - an array of steps with no timeout. Default:
  *     * `amOnPage`
  *     * `wait*`
@@ -68,6 +68,7 @@ export default function(config) {
   config.customTimeoutSteps = config.customTimeoutSteps.concat(config.noTimeoutSteps).concat(config.customTimeoutSteps)
 
   event.dispatcher.on(event.step.before, step => {
+    if (!step.title) return
     let stepTimeout
     for (let stepRule of config.customTimeoutSteps) {
       let customTimeout = 0
@@ -75,7 +76,7 @@ export default function(config) {
         if (stepRule.length > 1) customTimeout = stepRule[1]
         stepRule = stepRule[0]
       }
-      if (stepRule instanceof RegExp ? step.name.match(stepRule) : step.name === stepRule || (stepRule.indexOf('*') && step.name.startsWith(stepRule.slice(0, -1)))) {
+      if (stepRule instanceof RegExp ? step.title.match(stepRule) : step.title === stepRule || (stepRule.indexOf('*') && step.title.startsWith(stepRule.slice(0, -1)))) {
         stepTimeout = customTimeout
         break
       }

package/lib/recorder.js

@@ -217,7 +217,7 @@ export default {
       }
 
       const retryRules = this.retries.slice().reverse()
-      return promiseRetry(Object.assign(defaultRetryOptions, retryOpts), (retry, number) => {
+      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)])

package/lib/rerun.js

@@ -1,4 +1,5 @@
 import fsPath from 'path'
+import store from './store.js'
 import container from './container.js'
 import event from './event.js'
 import BaseCodecept from './codecept.js'
@@ -29,7 +30,7 @@ class CodeceptRerunner extends BaseCodecept {
         let filesToRun = this.testFiles
         if (test) {
           if (!fsPath.isAbsolute(test)) {
-            test = fsPath.join(global.codecept_dir, test)
+            test = fsPath.join(store.codeceptDir, test)
           }
           filesToRun = this.testFiles.filter(t => fsPath.basename(t, '.js') === test || t === test)
         }

package/lib/result.js

@@ -1,6 +1,7 @@
 import fs from 'fs'
 import path from 'path'
 import { serializeTest } from './mocha/test.js'
+import store from './store.js'
 
 /**
  * @typedef {Object} Stats Statistics for a test result.
@@ -212,7 +213,7 @@ class Result {
    */
   save(fileName) {
     if (!fileName) fileName = 'result.json'
-    fs.writeFileSync(path.join(global.output_dir, fileName), JSON.stringify(this.simplify(), null, 2))
+    fs.writeFileSync(path.join(store.outputDir, fileName), JSON.stringify(this.simplify(), null, 2))
   }
 
   /**

package/lib/step/base.js

@@ -3,18 +3,19 @@ import Secret from '../secret.js'
 import { getCurrentTimeout } from '../timeout.js'
 import { ucfirst, humanizeString, serializeError } from '../utils.js'
 import recordStep from './record.js'
+import store from '../store.js'
 
 const STACK_LINE = 5
 
 /**
  * Each command in test executed through `I.` object is wrapped in Step.
  * Step allows logging executed commands and triggers hook before and after step execution.
- * @param {string} name
+ * @param {string} title
  */
 class Step {
-  constructor(name) {
+  constructor(title) {
     /** @member {string} */
-    this.name = name
+    this.title = title
     /** @member {Map<number, number>} */
     this.timeouts = new Map()
 
@@ -42,7 +43,7 @@ class Step {
     /** @member {any} */
     this.helper = null
     /** @member {string} */
-    this.helperMethod = name
+    this.helperMethod = title
 
     this.startTime = 0
     this.endTime = 0
@@ -102,7 +103,7 @@ class Step {
 
   /** @return {string} */
   humanize() {
-    return humanizeString(this.name)
+    return humanizeString(this.title)
   }
 
   /** @return {string} */
@@ -147,9 +148,22 @@ class Step {
   line() {
     const lines = this.stack.split('\n')
     if (lines[STACK_LINE]) {
-      return lines[STACK_LINE].trim()
-        .replace(global.codecept_dir || '', '.')
+      let line = lines[STACK_LINE].trim()
+        .replace(store.codeceptDir || '', '.')
         .trim()
+
+      // Map .temp.mjs back to original .ts files using container's tsFileMapping
+      const fileMapping = store.tsFileMapping
+      if (line.includes('.temp.mjs') && fileMapping) {
+        for (const [tsFile, mjsFile] of fileMapping.entries()) {
+          if (line.includes(mjsFile)) {
+            line = line.replace(mjsFile, tsFile)
+            break
+          }
+        }
+      }
+
+      return line
     }
     return ''
   }
@@ -166,7 +180,7 @@ class Step {
 
   /** @return {string} */
   toCode() {
-    return `${this.prefix}${this.actor}.${this.name}(${this.humanizeArgs()})${this.suffix}`
+    return `${this.prefix}${this.actor}.${this.title}(${this.humanizeArgs()})${this.suffix}`
   }
 
   isMetaStep() {
@@ -209,7 +223,7 @@ class Step {
 
     return {
       opts: step.opts || {},
-      title: step.name,
+      title: step.title,
       args: args,
       status: step.status,
       startTime: step.startTime,

package/lib/step/comment.js

@@ -1,8 +1,8 @@
 import FuncStep from './func.js'
 
 class CommentStep extends FuncStep {
-  constructor(name, comment) {
-    super(name)
+  constructor(title, comment) {
+    super(title)
     this.fn = () => {}
   }
 }

package/lib/step/config.js

@@ -1,20 +1,33 @@
+/**
+ * @typedef {Object} StepOptions
+ * @property {number|'first'|'last'} [elementIndex] - Select a specific element when multiple match. 1-based positive index, negative from end, or 'first'/'last'.
+ * @property {boolean} [exact] - Enable strict mode for this step. Throws if multiple elements match.
+ * @property {boolean} [strictMode] - Alias for exact.
+ * @property {boolean} [ignoreCase] - Perform case-insensitive text matching.
+ */
+
 /**
  * StepConfig is a configuration object for a step.
  * It is used to create a new step that is a combination of other steps.
  */
 class StepConfig {
   constructor(opts = {}) {
-    /** @member {{ opts: Record<string, any>, timeout: number|undefined, retry: number|undefined }} */
+    /** @member {{ opts: StepOptions, timeout: number|undefined, retry: number|undefined }} */
     this.config = {
       opts,
       timeout: undefined,
       retry: undefined,
     }
+    this.__isStepConfig = true
+  }
+
+  static isStepConfig(obj) {
+    return obj && (obj instanceof StepConfig || obj.__isStepConfig === true)
   }
 
   /**
    * Set the options for the step.
-   * @param {object} opts - The options for the step.
+   * @param {StepOptions} opts - The options for the step.
    * @returns {StepConfig} - The step configuration object.
    */
   opts(opts) {

package/lib/step/helper.js

@@ -2,12 +2,12 @@ import Step from './base.js'
 import store from '../store.js'
 
 class HelperStep extends Step {
-  constructor(helper, name) {
-    super(name)
+  constructor(helper, title) {
+    super(title)
     /** @member {CodeceptJS.Helper} helper corresponding helper */
     this.helper = helper
-    /** @member {string} helperMethod name of method to be executed */
-    this.helperMethod = name
+    /** @member {string} helperMethod title of method to be executed */
+    this.helperMethod = title
   }
 
   /**

package/lib/step/meta.js

@@ -29,7 +29,7 @@ class MetaStep extends Step {
     const actorText = this.actor
 
     if (this.isBDD()) {
-      return `${this.prefix}${actorText} ${this.name} "${this.humanizeArgs()}${this.suffix}"`
+      return `${this.prefix}${actorText} ${this.title} "${this.humanizeArgs()}${this.suffix}"`
     }
 
     if (actorText === 'I') {
@@ -37,14 +37,14 @@ class MetaStep extends Step {
     }
 
     if (!this.actor) {
-      return `${this.name} ${this.humanizeArgs()}${this.suffix}`.trim()
+      return `${this.title} ${this.humanizeArgs()}${this.suffix}`.trim()
     }
 
     return `On ${this.prefix}${actorText}: ${this.humanize()} ${this.humanizeArgs()}${this.suffix}`.trim()
   }
 
   humanize() {
-    return humanizeString(this.name)
+    return humanizeString(this.title)
   }
 
   setTrace() {}

package/lib/step/record.js

@@ -5,22 +5,23 @@ import output from '../output.js'
 import store from '../store.js'
 import { TIMEOUT_ORDER } from '../timeout.js'
 import retryStep from './retry.js'
+import { fixErrorStack } from '../utils/typescript.js'
 function recordStep(step, args) {
   step.status = 'queued'
 
   // apply step configuration
   const lastArg = args[args.length - 1]
-  if (lastArg instanceof StepConfig) {
+  if (StepConfig.isStepConfig(lastArg)) {
     const stepConfig = args.pop()
     const { opts, timeout, retry } = stepConfig.getConfig()
 
     if (opts) {
-      output.debug(`Step ${step.name}: options applied ${JSON.stringify(opts)}`)
+      output.debug(`Step ${step.title}: options applied ${JSON.stringify(opts)}`)
       store.stepOptions = opts
       step.opts = opts
     }
     if (timeout) {
-      output.debug(`Step ${step.name} timeout ${timeout}s`)
+      output.debug(`Step ${step.title} timeout ${timeout}s`)
       step.setTimeout(timeout * 1000, TIMEOUT_ORDER.codeLimitTime)
     }
     if (retry) retryStep(retry)
@@ -30,7 +31,7 @@ function recordStep(step, args) {
   // run async before step hooks
   event.emit(event.step.before, step)
 
-  const task = `${step.name}: ${step.humanizeArgs()}`
+  const task = `${step.title}: ${step.humanizeArgs()}`
   let val
 
   // run step inside promise
@@ -60,6 +61,13 @@ function recordStep(step, args) {
   recorder.catch(err => {
     step.status = 'failed'
     step.endTime = +Date.now()
+    
+    // Fix error stack to point to original .ts files (lazy import to avoid circular dependency)
+    const fileMapping = store.tsFileMapping
+    if (fileMapping) {
+      fixErrorStack(err, fileMapping)
+    }
+    
     event.emit(event.step.failed, step, err)
     event.emit(event.step.finished, step)
     throw err

package/lib/store.js

@@ -1,8 +1,34 @@
 /**
- * global values for current session
+ * Global store for current session
  * @namespace
  */
 const store = {
+  // --- Required (set once via initialize(), immutable after) ---
+
+  /** @type {string | null} */
+  _codeceptDir: null,
+  /** @type {string | null} */
+  _outputDir: null,
+
+  get codeceptDir() {
+    return this._codeceptDir || global.codecept_dir || null
+  },
+  set codeceptDir(val) {
+    this._codeceptDir = val
+  },
+
+  get outputDir() {
+    return this._outputDir || global.output_dir || null
+  },
+  set outputDir(val) {
+    this._outputDir = val
+  },
+
+  /** @type {boolean} */
+  workerMode: false,
+
+  // --- Session config (per-session, mutable, set at session start) ---
+
   /**
    * If we are in --debug mode
    * @type {boolean}
@@ -27,20 +53,63 @@ const store = {
    * @type {boolean}
    */
   dryRun: false,
+
+  /**
+   * Feature.only() was used
+   * @type {boolean}
+   */
+  featureOnly: false,
+
+  /**
+   * Scenario.only() was used
+   * @type {boolean}
+   */
+  scenarioOnly: false,
+
+  /**
+   * Mask sensitive data config
+   * @type {boolean|object}
+   */
+  maskSensitiveData: false,
+
+  /**
+   * noGlobals mode — user imports everything
+   * @type {boolean}
+   */
+  noGlobals: false,
+
+  // --- State (tracks current execution, changes constantly) ---
+
   /**
    * If we are in pause mode
    * @type {boolean}
    */
   onPause: false,
 
-  // current object states
-
   /** @type {CodeceptJS.Test | null} */
   currentTest: null,
   /** @type {CodeceptJS.Step | null} */
   currentStep: null,
   /** @type {CodeceptJS.Suite | null} */
   currentSuite: null,
+
+  /** @type {Map<string, string> | null} */
+  tsFileMapping: null,
+
+  /**
+   * Initialize required store fields.
+   * These values cannot be overwritten after initialization.
+   * @param {object} opts
+   * @param {string} opts.codeceptDir - root directory of tests
+   * @param {string} opts.outputDir - resolved output directory
+   */
+  initialize(opts) {
+    if (!opts.codeceptDir) throw new Error('codeceptDir is required')
+    if (!opts.outputDir) throw new Error('outputDir is required')
+
+    this._codeceptDir = opts.codeceptDir
+    this._outputDir = opts.outputDir
+  },
 }
 
 export default store

package/lib/translation.js

@@ -1,6 +1,7 @@
 import merge from 'lodash.merge'
 import path from 'path'
 import { createRequire } from 'module'
+import store from './store.js'
 
 const defaultVocabulary = {
   I: 'I',
@@ -15,7 +16,7 @@ class Translation {
 
   loadVocabulary(vocabularyFile) {
     if (!vocabularyFile) return
-    const filePath = path.join(global.codecept_dir, vocabularyFile)
+    const filePath = path.join(store.codeceptDir, vocabularyFile)
 
     try {
       const require = createRequire(import.meta.url)

package/lib/utils/loaderCheck.js

@@ -65,9 +65,18 @@ CodeceptJS 4.x uses ES Modules (ESM) and requires a loader to run TypeScript tes
     ✅ Complete: Handles all TypeScript features
 
 ┌─────────────────────────────────────────────────────────────────────────────┐
-│ Option 2: ts-node/esm (Alternative - Established, Requires Config)         │
+│ Option 2: ts-node/esm (Not Recommended - Has Module Resolution Issues)     │
 └─────────────────────────────────────────────────────────────────────────────┘
 
+  ⚠️  ts-node/esm has significant limitations and is not recommended:
+      - Doesn't work with "type": "module" in package.json
+      - Module resolution doesn't work like standard TypeScript ESM
+      - Import statements must use explicit file paths
+  
+  We strongly recommend using tsx/cjs instead.
+  
+  If you still want to use ts-node/esm:
+
   Installation:
     npm install --save-dev ts-node
 
@@ -84,11 +93,12 @@ CodeceptJS 4.x uses ES Modules (ESM) and requires a loader to run TypeScript tes
            "esModuleInterop": true
          },
          "ts-node": {
-           "esm": true,
-           "experimentalSpecifierResolution": "node"
+           "esm": true
          }
        }
 
+    3. Do NOT use "type": "module" in package.json
+
 📚 Documentation: https://codecept.io/typescript
 
 Note: TypeScript config files (codecept.conf.ts) and helpers are automatically
@@ -96,6 +106,34 @@ Note: TypeScript config files (codecept.conf.ts) and helpers are automatically
 `
 }
 
+/**
+ * Get warning message if ts-node/esm is being used
+ * @param {string[]} requiredModules - Array of required modules from config
+ * @returns {string|null} Warning message or null
+ */
+export function getTSNodeESMWarning(requiredModules = []) {
+  if (!requiredModules.includes('ts-node/esm')) {
+    return null
+  }
+
+  return `
+⚠️  Warning: ts-node/esm with "module": "esnext" requires explicit file extensions in all imports.
+
+This is a known limitation. Use tsx/cjs instead to write imports without extensions.
+
+Examples:
+
+  ❌ Incorrect (will fail):
+     import loginPage from "./pages/Login";
+
+  ✅ Correct (must include .ts extension):
+     import loginPage from "./pages/Login.ts";
+
+📚 Documentation: https://codecept.io/typescript
+
+`
+}
+
 /**
  * Check if user is trying to run TypeScript tests without proper loader
  * @param {string[]} testFiles - Array of test file paths