codeceptjs 4.0.3 → 4.0.5

package/bin/codecept.js

@@ -5,6 +5,7 @@ import Codecept from '../lib/codecept.js'
 import output from '../lib/output.js'
 const { print, error } = output
 import { printError } from '../lib/command/utils.js'
+import { resolveImportModulePath } from '../lib/utils.js'
 
 const commandFlags = {
   ai: {
@@ -45,7 +46,8 @@ const errorHandler =
   }
 
 const dynamicImport = async modulePath => {
-  const module = await import(modulePath)
+  const resolvedPath = resolveImportModulePath(modulePath)
+  const module = await import(resolvedPath)
   return module.default || module
 }
 

package/docs/agents.md

@@ -23,6 +23,38 @@ Agents get full control over test and browser execution:
 
 CodeceptJS is token-efficient: it stores HTML, ARIA, logs, and HTTP request data as files instead of streaming them through MCP. Agents read these files with their native shell tools—no extra API calls, no redundant context.
 
+## Essential Setup
+
+Two things make agent testing work: the **skills** that teach the agent CodeceptJS, and the **MCP server** that lets it drive the browser. Set both up once, from your project directory.
+
+Install the skills:
+
+```bash
+npx skills add codeceptjs/skills
+```
+
+Connect the MCP server (`npx codeceptjs-mcp`).
+
+**Claude Code:**
+
+```bash
+claude mcp add codeceptjs -- npx codeceptjs-mcp
+```
+
+**Codex:**
+
+```bash
+codex mcp add codeceptjs -- npx codeceptjs-mcp
+```
+
+**Cursor** — add to `.cursor/mcp.json`:
+
+```json
+{ "mcpServers": { "codeceptjs": { "command": "npx", "args": ["codeceptjs-mcp"] } } }
+```
+
+See [/mcp](/mcp) for full client setup. Now the agent is ready to run the loop.
+
 ## The loop
 
 Whether the agent is writing a new test or fixing an old one, it follows the same cycle.
@@ -96,31 +128,6 @@ Only `url` is inline. The rest are paths the agent opens with the right tool:
 
 Saved HTML is formatted, with non-semantic elements stripped out: `<style>`, `<script>`, Tailwind-style trash classes, and inline `style=""` attributes. `grep` can then effectively find the correct tree branch in raw page source. ARIA snapshots are smaller and more structured than HTML, which is why the agent prefers them when picking locators.
 
-## Setup
-
-When CodeceptJS is installed, the MCP server can be launched with this command:
-
-```bash
-npx codeceptjs-mcp
-```
-
-> See [/mcp](/mcp) for detailed client setup.
-
-We recommend pairing CodeceptJS MCP with the skills bundle.
-
-Install for any agent:
-
-```bash
-npx skills add codeceptjs/skills
-```
-
-Or, in Claude Code:
-
-```text
-/plugin marketplace add codeceptjs/skills
-/plugin install codeceptjs@codeceptjs-skills
-```
-
 ## Usage Examples
 
 When MCP and skills are connected, the agent receives predefined workflows and can act effectively for testing purposes. Common scenarios it handles:

package/lib/ai.js

@@ -6,7 +6,7 @@ import { removeNonInteractiveElements, minifyHtml, splitByChunks } from './html.
 import { generateText } from 'ai'
 import { fileURLToPath } from 'url'
 import path from 'path'
-import { fileExists } from './utils.js'
+import { fileExists, resolveImportModulePath } from './utils.js'
 import store from './store.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -34,7 +34,8 @@ async function loadPrompts() {
     }
 
     try {
-      const module = await import(promptPath)
+      const resolvedPath = resolveImportModulePath(promptPath)
+      const module = await import(resolvedPath)
       prompts[name] = module.default || module
       debug(`Loaded prompt ${name} from ${promptPath}`)
     } catch (err) {

package/lib/codecept.js

@@ -17,7 +17,7 @@ import event from './event.js'
 import runHook from './hooks.js'
 import ActorFactory from './actor.js'
 import output from './output.js'
-import { emptyFolder } from './utils.js'
+import { emptyFolder, resolveImportModulePath } from './utils.js'
 import { initCodeceptGlobals } from './globals.js'
 import { validateTypeScriptSetup, getTSNodeESMWarning } from './utils/loaderCheck.js'
 import recorder from './recorder.js'
@@ -73,7 +73,7 @@ class Codecept {
           // For npm packages, resolve from the user's directory
           // This ensures packages like tsx are found in user's node_modules
           const userDir = store.codeceptDir || process.cwd()
-          
+
           try {
             // Use createRequire to resolve from user's directory
             const userRequire = createRequire(pathToFileURL(resolve(userDir, 'package.json')).href)
@@ -86,7 +86,8 @@ class Codecept {
           }
         }
         // Use dynamic import for ESM
-        await import(modulePath)
+        const resolvedPath = resolveImportModulePath(modulePath)
+        await import(resolvedPath)
       }
     }
   }
@@ -137,7 +138,8 @@ class Codecept {
       ]
 
       for (const modulePath of listenerModules) {
-        const module = await import(modulePath)
+        const resolvedPath = resolveImportModulePath(modulePath)
+        const module = await import(resolvedPath)
         runHook(module.default || module)
       }
     }
@@ -287,6 +289,9 @@ class Codecept {
       // Ignore if gherkin module not available
     }
 
+    // Sort test files alphabetically for consistent execution order
+    this.testFiles.sort()
+
     return new Promise((resolve, reject) => {
       const mocha = container.mocha()
       mocha.files = this.testFiles

package/lib/command/info.js

@@ -5,22 +5,26 @@ import Codecept from '../codecept.js'
 import output from '../output.js'
 import { execSync } from 'child_process'
 
+// Unified regex for both formats (excludes chromium-headless-shell):
+// - 1.58+: "Firefox 146.0.1 (playwright firefox v1509)"
+// - 1.57:  "browser: firefox version 144.0.2"
+const playwrightBrowserRegex = /(?:([\d.]+)\s+\(playwright\s+(chromium|firefox|webkit)\s)|(?:browser:\s*(chromium|firefox|webkit)\s+version\s+([\d.]+))/gi
+
+function parsePlaywrightBrowsers(output) {
+  const versions = []
+  const matches = [...output.matchAll(playwrightBrowserRegex)]
+  matches.forEach(match => {
+    const browser = match[2] || match[3]
+    const version = match[1] || match[4]
+    versions.push(`${browser}: ${version}`)
+  })
+  return versions.join(', ')
+}
+
 async function getPlaywrightBrowsers() {
   try {
-    const regex = /(chromium|firefox|webkit)\s+version\s+([\d.]+)/gi
-    let versions = []
-
     const info = execSync('npx playwright install --dry-run').toString().trim()
-
-    const matches = [...info.matchAll(regex)]
-
-    matches.forEach(match => {
-      const browser = match[1]
-      const version = match[2]
-      versions.push(`${browser}: ${version}`)
-    })
-
-    return versions.join(', ')
+    return parsePlaywrightBrowsers(info)
   } catch (err) {
     return 'Playwright not installed'
   }
@@ -73,6 +77,8 @@ export default async function (path) {
   output.print('***************************************')
 }
 
+export { parsePlaywrightBrowsers }
+
 export const getMachineInfo = async () => {
   const info = {
     nodeInfo: await envinfo.helpers.getNodeInfo(),

package/lib/command/init.js

@@ -245,14 +245,12 @@ export default async function (initPath, options = {}) {
     }
 
     const tsconfig = {
-      'ts-node': {
-        files: true,
-      },
       compilerOptions: {
-        target: 'es2018',
-        lib: ['es2018', 'DOM'],
+        target: 'ES2022',
+        lib: ['ES2022', 'DOM'],
         esModuleInterop: true,
-        module: 'commonjs',
+        module: 'ESNext',
+        moduleResolution: 'bundler',
         strictNullChecks: false,
         types: ['codeceptjs', 'node'],
         declaration: true,

package/lib/command/run-rerun.js

@@ -5,6 +5,7 @@ import Codecept from '../rerun.js'
 export default async function (test, options) {
   // registering options globally to use in config
   // Backward compatibility for --profile
+
   process.profile = options.profile
   process.env.profile = options.profile
   const configFile = options.config

package/lib/config.js

@@ -1,7 +1,7 @@
 import fs from 'fs'
 import path from 'path'
 import { createRequire } from 'module'
-import { fileExists, isFile, deepMerge, deepClone } from './utils.js'
+import { fileExists, isFile, deepMerge, deepClone, resolveImportModulePath } from './utils.js'
 import { transpileTypeScript, cleanupTempFiles, fixErrorStack } from './utils/typescript.js'
 
 const defaultConfig = {
@@ -96,7 +96,7 @@ class Config {
       // Try different extensions if the file doesn't exist
       const extensions = ['.ts', '.cjs', '.mjs']
       let found = false
-      
+
       for (const ext of extensions) {
         const altConfig = configFile.replace(/\.js$/, ext)
         if (fileExists(altConfig)) {
@@ -105,7 +105,7 @@ class Config {
           break
         }
       }
-      
+
       if (!found) {
         throw new Error(`Config file ${configFile} does not exist. Execute 'codeceptjs init' to create config`)
       }
@@ -242,7 +242,8 @@ async function loadConfigFile(configFile) {
           allTempFiles = result.allTempFiles
           fileMapping = result.fileMapping
 
-          configModule = await import(tempFile)
+          const resolvedPath = resolveImportModulePath(tempFile)
+          configModule = await import(resolvedPath)
           cleanupTempFiles(allTempFiles)
         } catch (err) {
           transpileError = err
@@ -258,7 +259,8 @@ async function loadConfigFile(configFile) {
         }
       } else {
         // Try ESM import first for JS files
-        configModule = await import(configFile)
+        const resolvedPath = resolveImportModulePath(configFile)
+        configModule = await import(resolvedPath)
       }
     } catch (importError) {
       try {

package/lib/container.js

@@ -5,7 +5,15 @@ import { isMainThread } from 'worker_threads'
 import debugModule from 'debug'
 const debug = debugModule('codeceptjs:container')
 import { MetaStep } from './step.js'
-import { methodsOfObject, fileExists, isFunction, isAsyncFunction, installedLocally, deepMerge } from './utils.js'
+import {
+  methodsOfObject,
+  fileExists,
+  isFunction,
+  isAsyncFunction,
+  installedLocally,
+  deepMerge,
+  resolveImportModulePath,
+} from './utils.js'
 import { transpileTypeScript, cleanupTempFiles, fixErrorStack } from './utils/typescript.js'
 import Translation from './translation.js'
 import MochaFactory from './mocha/factory.js'
@@ -434,7 +442,9 @@ async function requireHelperFromModule(helperName, config, HelperClass) {
     try {
       // For built-in helpers, use direct relative import with .js extension
       const helperPath = `${moduleName}.js`
-      const mod = await import(helperPath)
+
+      const resolvedPath = resolveImportModulePath(helperPath)
+      const mod = await import(resolvedPath)
       HelperClass = mod.default || mod
     } catch (err) {
       throw err
@@ -449,7 +459,7 @@ async function requireHelperFromModule(helperName, config, HelperClass) {
     if (ext === '.ts') {
       try {
         // Use the TypeScript transpilation utility
-        const typescript = await import('typescript')
+        const typescript = ((await import('typescript')).default || (await import('typescript')))
         const { tempFile, allTempFiles, fileMapping: mapping } = await transpileTypeScript(importPath, typescript)
 
         debug(`Transpiled TypeScript helper: ${importPath} -> ${tempFile}`)
@@ -472,7 +482,9 @@ async function requireHelperFromModule(helperName, config, HelperClass) {
     // check if the new syntax export default HelperName is used and loads the Helper, otherwise loads the module that used old syntax export = HelperName.
     try {
       // Try dynamic import for both CommonJS and ESM modules
-      const mod = await import(importPath)
+      const resolvedPath = resolveImportModulePath(importPath)
+      const mod = await import(resolvedPath)
+
       if (!mod && !mod.default) {
         throw new Error(`Helper module '${moduleName}' was not found. Make sure you have installed the package correctly.`)
       }
@@ -488,7 +500,7 @@ async function requireHelperFromModule(helperName, config, HelperClass) {
       if (fileMapping) {
         fixErrorStack(err, fileMapping)
       }
-      
+
       // Clean up temp files before rethrowing
       if (tempJsFile) {
         const filesToClean = Array.isArray(tempJsFile) ? tempJsFile : [tempJsFile]
@@ -683,7 +695,8 @@ async function loadPluginAsync(modulePath, config) {
   let pluginMod
   try {
     // Try dynamic import first (works for both ESM and CJS)
-    pluginMod = await import(modulePath)
+    const resolvedPath = resolveImportModulePath(modulePath)
+    pluginMod = await import(resolvedPath)
   } catch (err) {
     throw new Error(`Could not load plugin from '${modulePath}': ${err.message}`)
   }
@@ -862,7 +875,7 @@ async function loadSupportObject(modulePath, supportObjectName) {
       if (ext === '.ts') {
         try {
           // Use the TypeScript transpilation utility
-          const typescript = await import('typescript')
+          const typescript = ((await import('typescript')).default || (await import('typescript')))
           const { tempFile, allTempFiles, fileMapping: mapping } = await transpileTypeScript(importPath, typescript)
 
           debug(`Transpiled TypeScript file: ${importPath} -> ${tempFile}`)
@@ -890,21 +903,19 @@ async function loadSupportObject(modulePath, supportObjectName) {
 
     let obj
     try {
-      obj = await import(importPath)
+      const resolvedPath = resolveImportModulePath(importPath)
+      obj = await import(resolvedPath)
     } catch (importError) {
-      // Fix error stack to point to original .ts files
       if (fileMapping) {
         fixErrorStack(importError, fileMapping)
       }
-      
-      // Clean up temp files if created before rethrowing
+
       if (tempJsFile) {
         const filesToClean = Array.isArray(tempJsFile) ? tempJsFile : [tempJsFile]
         cleanupTempFiles(filesToClean)
       }
       throw importError
     } finally {
-      // Clean up temp files if created
       if (tempJsFile) {
         const filesToClean = Array.isArray(tempJsFile) ? tempJsFile : [tempJsFile]
         cleanupTempFiles(filesToClean)

package/lib/helper/ApiDataFactory.js

@@ -2,6 +2,7 @@ import path from 'path'
 import Helper from '@codeceptjs/helper'
 import REST from './REST.js'
 import store from '../store.js'
+import { resolveImportModulePath } from '../utils.js'
 
 /**
  * Helper for managing remote data using REST API.
@@ -328,7 +329,8 @@ class ApiDataFactory extends Helper {
         modulePath = path.join(store.codeceptDir, modulePath)
       }
       // check if the new syntax `export default new Factory()` is used and loads the builder, otherwise loads the module that used old syntax `module.exports = new Factory()`.
-      const module = await import(modulePath)
+      const resolvedPath = resolveImportModulePath(modulePath)
+      const module = await import(resolvedPath)
       const builder = module.default || module
       return builder.build(data, options)
     } catch (err) {

package/lib/pause.js

@@ -105,7 +105,7 @@ async function parseInput(cmd) {
   recorder.session.start('pause')
   if (cmd === '') next = true
   if (!cmd || cmd === 'resume' || cmd === 'exit') {
-    finish()
+    if (typeof finish === 'function') finish()
     recorder.session.restore('pause')
     rl.close()
     history.save()

package/lib/rerun.js

@@ -5,6 +5,7 @@ import event from './event.js'
 import BaseCodecept from './codecept.js'
 import output from './output.js'
 import { createRequire } from 'module'
+import { resolveImportModulePath } from './utils.js'
 
 const require = createRequire(import.meta.url)
 
@@ -50,8 +51,9 @@ class CodeceptRerunner extends BaseCodecept {
             }
 
             // Force reload the module by using a cache-busting query parameter
-            const fileUrl = `${fsPath.resolve(file)}?t=${Date.now()}`
-            await import(fileUrl)
+            const fileUrl = `${fsPath.resolve(file)}`
+            const resolvedPath = resolveImportModulePath(fileUrl)
+            await import(resolvedPath)
           } catch (e) {
             console.error(`Error loading test file ${file}:`, e)
           }

package/lib/translation.js

@@ -16,7 +16,13 @@ class Translation {
 
   loadVocabulary(vocabularyFile) {
     if (!vocabularyFile) return
-    const filePath = path.join(store.codeceptDir, vocabularyFile)
+
+    let filePath;
+    if (path.isAbsolute(vocabularyFile)) {
+      filePath = vocabularyFile;
+    } else {
+      filePath = path.join(store.codeceptDir, vocabularyFile);
+    }
 
     try {
       const require = createRequire(import.meta.url)

package/lib/utils.js

@@ -1,6 +1,7 @@
 import fs from 'fs'
 import os from 'os'
 import path from 'path'
+import { pathToFileURL } from 'url'
 import { createRequire } from 'module'
 import chalk from 'chalk'
 import getFunctionArguments from 'fn-args'
@@ -38,6 +39,22 @@ export const isAsyncFunction = function (fn) {
   return fn[Symbol.toStringTag] === 'AsyncFunction'
 }
 
+export const resolveImportModulePath = function (modulePath) {
+  // 1. If it's an absolute path, convert to a file:// URL
+  if (path.isAbsolute(modulePath)) {
+    return pathToFileURL(modulePath).href;
+  }
+
+  // 2. If it's a relative path (starts with ./ or ../), resolve it fully
+  if (modulePath.startsWith('./') || modulePath.startsWith('../')) {
+    return modulePath
+  }
+
+  // 3. Otherwise, it's likely a bare NPM module (e.g., 'chai', 'codeceptjs')
+  // Let Node.js resolve it natively from node_modules
+  return modulePath;
+}
+
 export const fileExists = function (filePath) {
   return fs.existsSync(filePath)
 }
@@ -229,7 +246,7 @@ export const test = {
           // Use Node.js child_process.spawnSync with platform-specific sleep commands
           // This avoids busy waiting and allows other processes to run
           try {
-            if (os.platform() === 'win32') {
+            if (isWindows()) {
               // Windows: use ping with precise timing (ping waits exactly the specified ms)
               spawnSync('ping', ['-n', '1', '-w', pollInterval.toString(), '127.0.0.1'], { stdio: 'ignore' })
             } else {
@@ -735,3 +752,7 @@ export const markdownToAnsi = function (markdown) {
       })
   )
 }
+
+export function isWindows() {
+  return os.platform() === 'win32'
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "4.0.3",
+  "version": "4.0.5",
   "type": "module",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
@@ -64,6 +64,7 @@
     "prettier": "prettier --config prettier.config.js --write bin/**/*.js lib/**/*.js test/**/*.js translations/**/*.js runok.cjs",
     "docs": "./runok.cjs docs",
     "test:unit": "mocha test/unit --recursive --timeout 10000 --reporter @testomatio/reporter/mocha",
+    "test:unit:windows": "mocha test/unit/container_test.js --recursive --timeout 10000 --reporter @testomatio/reporter/mocha",
     "test:rest": "mocha test/rest --recursive --timeout 20000 --reporter @testomatio/reporter/mocha",
     "test:runner": "mocha test/runner --recursive --timeout 10000 --reporter @testomatio/reporter/mocha",
     "test": "npm run test:unit && npm run test:rest && npm run test:runner",
@@ -94,7 +95,7 @@
     "@codeceptjs/helper": "2.0.4",
     "@cucumber/cucumber-expressions": "18",
     "@cucumber/gherkin": "38.0.0",
-    "@cucumber/messages": "32.0.1",
+    "@cucumber/messages": "32.3.1",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@xmldom/xmldom": "0.9.8",
     "acorn": "8.15.0",
@@ -104,7 +105,7 @@
     "chalk": "4.1.2",
     "cheerio": "^1.0.0",
     "chokidar": "^5.0.0",
-    "commander": "14.0.3",
+    "commander": "15.0.0",
     "cross-spawn": "7.0.6",
     "css-to-xpath": "0.1.0",
     "csstoxpath": "1.6.0",
@@ -182,15 +183,15 @@
     "rosie": "2.1.1",
     "runok": "^0.9.3",
     "semver": "7.7.3",
-    "sinon": "21.0.1",
+    "sinon": "22.0.0",
     "sinon-chai": "^4.0.1",
-    "ts-morph": "27.0.2",
+    "ts-morph": "28.0.0",
     "ts-node": "10.9.2",
     "tsd": "^0.33.0",
     "tsd-jsdoc": "2.5.0",
     "tsx": "^4.19.2",
     "typedoc": "0.28.16",
-    "typedoc-plugin-markdown": "4.9.0",
+    "typedoc-plugin-markdown": "4.12.0",
     "typescript": "5.9.3",
     "wdio-docker-service": "3.2.1",
     "webdriverio": "9.23.0",

package/typings/index.d.ts

@@ -524,24 +524,11 @@ type RetryTo = (fn: (tries: number) => Promise<void> | void, maxTries: number, p
 // Globals
 declare const codecept_dir: string
 declare const output_dir: string
-declare const tryTo: TryTo
-declare const retryTo: RetryTo
-declare const hopeThat: HopeThat
-
-declare const actor: CodeceptJS.actor
-declare const codecept_actor: CodeceptJS.actor
-declare const Helper: typeof CodeceptJS.Helper
-declare const codecept_helper: typeof CodeceptJS.Helper
+
 declare const pause: typeof CodeceptJS.pause
-declare const within: typeof CodeceptJS.within
-declare const session: typeof CodeceptJS.session
-declare const DataTable: typeof CodeceptJS.DataTable
-declare const DataTableArgument: typeof CodeceptJS.DataTableArgument
 declare const codeceptjs: typeof CodeceptJS
-declare const locate: typeof CodeceptJS.Locator.build
 declare function inject(): CodeceptJS.SupportObject
 declare function inject<T extends keyof CodeceptJS.SupportObject>(name: T): CodeceptJS.SupportObject[T]
-declare const secret: typeof CodeceptJS.Secret.secret
 
 // BDD
 declare const Given: typeof CodeceptJS.addStep
@@ -579,21 +566,8 @@ declare namespace NodeJS {
     codecept_dir: typeof codecept_dir
     output_dir: typeof output_dir
 
-    actor: typeof actor
-    codecept_actor: typeof codecept_actor
-    Helper: typeof Helper
-    codecept_helper: typeof codecept_helper
     pause: typeof pause
-    within: typeof within
-    session: typeof session
-    DataTable: typeof DataTable
-    DataTableArgument: typeof DataTableArgument
-    locate: typeof locate
     inject: typeof inject
-    secret: typeof secret
-    // plugins
-    tryTo: typeof tryTo
-    retryTo: typeof retryTo
 
     // BDD
     Given: typeof Given
@@ -729,6 +703,12 @@ declare module 'codeceptjs' {
    * Create a secret value
    */
   export const secret: typeof CodeceptJS.Secret.secret
+
+  export const session: typeof CodeceptJS.session
+
+  export const inject: typeof globalThis.inject
+
+  export const locate: typeof CodeceptJS.Locator.build
 }
 
 declare module '@codeceptjs/helper' {