feat: Automatic TypeScript helper transpilation and arrow function parameter parsing

**TypeScript Helper Auto-Transpilation:**
- Added automatic transpilation of .ts helper files using TypeScript compiler
- Detects ERR_UNKNOWN_FILE_EXTENSION and transpiles to temporary .mjs files
- Cleans up temporary files after import
- No NODE_OPTIONS or ESM loaders needed - just install typescript
- Handles CommonJS interop issues with fallback transform

**Arrow Function Parameter Parsing:**
- Fixed parser to handle arrow functions: ({ I }) => {...}
- Added regex to convert arrow functions to regular functions for parsing
- Handles both async arrow functions and regular arrow functions
- Fixes parameter injection for modern JavaScript/TypeScript syntax

**Async Helper Loading Fix:**
- Fixed race condition where _init() was called before async helpers resolved
- Added await asyncHelperPromise before calling _init() on helpers
- Ensures all helpers are fully loaded before container.started() completes

**Documentation Updates:**
- Updated docs/typescript.md with automatic transpilation info
- Added explanation of why test files use tsx/cjs vs auto-transpilation
- Added TypeScript Files Support Matrix showing what's auto-transpiled
- Added troubleshooting section for common issues
- Clarified hybrid approach design decision

**Test Coverage:**
- Added test/data/typescript-helper-autoload/ with working TypeScript helper
- Test passes without NODE_OPTIONS, confirming automatic transpilation works
- Helper extends @codeceptjs/helper and methods are properly injected into I object

Bump version to 4.0.0-beta.21

Author: kobenguyent

docs/typescript.md

@@ -213,6 +213,138 @@ export const config = {
 4. Change `require: ['ts-node/register']` to `require: ['tsx/cjs']`
 5. Run tests: `npx codeceptjs run`
 
+### TypeScript Custom Helpers <Badge text="Automatic Transpilation" type="tip"/>
+
+Custom helpers written in TypeScript are **automatically transpiled** at runtime in CodeceptJS 4.x! You don't need NODE_OPTIONS or ESM loaders.
+
+#### Requirements
+
+**Install TypeScript and @codeceptjs/helper:**
+```bash
+npm install --save-dev typescript @codeceptjs/helper
+```
+
+That's it! CodeceptJS will automatically detect `.ts` helper files and transpile them on-the-fly using the TypeScript compiler.
+
+#### Example TypeScript Helper
+
+```typescript
+// helpers/material-component.helper.ts
+import { Helper } from '@codeceptjs/helper'
+
+class MaterialComponentHelper extends Helper {
+  async waitForVisibleMaterialSnackbar(sec?: number): Promise<void> {
+    await this.helpers.Playwright.waitForVisible("simple-snack-bar", sec)
+  }
+
+  async waitForTextMaterialSnackbarText(
+    text: string,
+    timeout: number = 10
+  ): Promise<void> {
+    await this.helpers.Playwright.waitForText(
+      text,
+      timeout,
+      "simple-snack-bar"
+    )
+  }
+}
+
+export default MaterialComponentHelper
+```
+
+**Configuration:**
+```typescript
+// codecept.conf.ts
+export const config = {
+  tests: './tests/**/*.spec.ts',
+  require: ['tsx/cjs'],  // For test files
+  helpers: {
+    Playwright: {
+      url: 'http://localhost',
+      browser: 'chromium'
+    },
+    MaterialComponent: {
+      require: "./helpers/material-component.helper.ts"  // TypeScript helper - auto-loaded!
+    }
+  }
+}
+```
+
+**Run tests:**
+```bash
+npx codeceptjs run  # TypeScript helper automatically transpiled!
+```
+
+#### How It Works
+
+When CodeceptJS encounters a `.ts` helper file:
+1. Detects the `.ts` extension and `ERR_UNKNOWN_FILE_EXTENSION` error
+2. Checks if `typescript` package is installed
+3. Transpiles the helper to a temporary `.mjs` file  
+4. Imports the transpiled file
+5. Cleans up temporary files after loading
+
+This happens automatically - no configuration needed!
+
+#### TypeScript Files Support Matrix
+
+| File Type | Auto-Transpiled? | Configuration Required |
+|-----------|------------------|------------------------|
+| Test files (`*_test.ts`) | Via tsx/cjs loader | `require: ['tsx/cjs']` in config |
+| Helper files (`helper.ts`) | ✅ Automatic | `npm install typescript` |
+| Config files (`codecept.conf.ts`) | ✅ Automatic | None (built-in) |
+| Page Objects/Steps (`steps.ts`) | ✅ Automatic | `npm install typescript` |
+
+**Key Points:**
+- **Test files**: Need `tsx/cjs` in `require` array (Mocha uses `require()` internally)
+- **Helper/Page Object files**: Auto-transpiled when loaded via `import()`  
+- **Config files**: Always automatically transpiled (built-in feature)
+
+**Why Different Approaches?**
+
+Test files use a **loader** (`tsx/cjs`) while helpers use **auto-transpilation**. This hybrid approach is optimal because:
+
+1. **Test files are loaded by Mocha** via `require()` - CodeceptJS can't intercept this, so we need a loader like `tsx/cjs` that hooks into Node.js's require system
+2. **Helpers are loaded by CodeceptJS** via `import()` - we can catch the error and transpile on-demand
+3. **Performance** - tsx's optimized loader with caching is faster for many test files
+4. **Simplicity** - Auto-transpilation for helpers means no extra configuration needed
+
+This gives you the best of both worlds: efficient test loading and zero-config helper transpilation!
+
+#### Troubleshooting
+
+**Error: "TypeScript helper detected but could not be loaded"**
+
+Install TypeScript in your project:
+```bash
+npm install --save-dev typescript
+```
+
+**Error: "Cannot find module '@codeceptjs/helper'"**
+
+Install the helper base class:
+```bash
+npm install --save-dev @codeceptjs/helper
+```
+- Config files are always automatically transpiled by CodeceptJS
+
+#### Alternative: Compile TypeScript Helper to JavaScript
+
+If you can't use `NODE_OPTIONS`, compile your helper to JavaScript:
+
+```bash
+npx tsc helpers/material-component.helper.ts --module ES2022 --target ES2022
+```
+
+Then reference the `.js` file:
+```typescript
+helpers: {
+  MaterialComponent: {
+    require: "./helpers/material-component.helper.js"  // Compiled JS
+  }
+}
+```
+
 ## Promise-Based Typings
 
 By default, CodeceptJS tests are written in synchronous mode. This is a regular CodeceptJS test:

lib/actor.js

@@ -7,6 +7,8 @@ import event from './event.js'
 import store from './store.js'
 import output from './output.js'
 import Container from './container.js'
+import debugModule from 'debug'
+const debug = debugModule('codeceptjs:actor')
 
 /**
  * @interface

lib/container.js

@@ -17,6 +17,51 @@ import ai from './ai.js'
 import actorFactory from './actor.js'
 
 let asyncHelperPromise
+let tsxLoaderRegistered = false
+
+/**
+ * Automatically register tsx ESM loader for TypeScript imports
+ * This allows loading .ts files without NODE_OPTIONS
+ */
+async function ensureTsxLoader() {
+  if (tsxLoaderRegistered) return true
+
+  try {
+    // Check if tsx is available
+    const { createRequire } = await import('module')
+    const { pathToFileURL } = await import('url')
+    const userRequire = createRequire(pathToFileURL(path.join(global.codecept_dir || process.cwd(), 'package.json')).href)
+    
+    // Try to resolve tsx from user's project
+    try {
+      userRequire.resolve('tsx')
+    } catch {
+      debug('tsx not found in user project')
+      return false
+    }
+
+    // Register tsx/esm loader dynamically
+    // Use Node.js register() API from node:module (Node 18.19+, 20.6+)
+    try {
+      const { register } = await import('node:module')
+      if (typeof register === 'function') {
+        debug('Registering tsx ESM loader via node:module register()')
+        const tsxPath = userRequire.resolve('tsx/esm')
+        register(tsxPath, import.meta.url)
+        tsxLoaderRegistered = true
+        return true
+      }
+    } catch (registerErr) {
+      debug('node:module register() not available:', registerErr.message)
+    }
+
+    debug('module.register not available, tsx loader must be set via NODE_OPTIONS')
+    return false
+  } catch (err) {
+    debug('Failed to register tsx loader:', err.message)
+    return false
+  }
+}
 
 let container = {
   helpers: {},
@@ -349,6 +394,9 @@ async function createHelpers(config) {
     }
   }
 
+  // Wait for all async helpers to be resolved before calling _init
+  await asyncHelperPromise
+  
   for (const name in helpers) {
     if (helpers[name]._init) await helpers[name]._init()
   }
@@ -392,7 +440,83 @@ async function requireHelperFromModule(helperName, config, HelperClass) {
       }
       HelperClass = mod.default || mod
     } catch (err) {
-      if (err.code === 'ERR_REQUIRE_ESM' || (err.message && err.message.includes('ES module'))) {
+      if (err.code === 'ERR_UNKNOWN_FILE_EXTENSION' || (err.message && err.message.includes('Unknown file extension'))) {
+          // This is likely a TypeScript helper file. Transpile it to a temporary JS file
+          // and import that as a reliable fallback (no NODE_OPTIONS required).
+          try {
+            const pathModule = await import('path')
+            const absolutePath = pathModule.default.resolve(moduleName)
+
+            // Attempt to load local 'typescript' to transpile the helper
+            let typescript
+            try {
+              typescript = await import('typescript')
+            } catch (tsImportErr) {
+              throw new Error(`TypeScript helper detected (${moduleName}). Please install 'typescript' in your project: npm install --save-dev typescript`)
+            }
+
+            const { tempFile, allTempFiles } = await transpileTypeScript(absolutePath, typescript)
+            debug(`Transpiled TypeScript helper: ${moduleName} -> ${tempFile}`)
+
+            try {
+              try {
+                const mod = await import(tempFile)
+                HelperClass = mod.default || mod
+                debug(`helper ${helperName} loaded from transpiled JS: ${tempFile}`)
+              } catch (importTempErr) {
+                // If import fails due to CommonJS named export incompatibility,
+                // try a quick transform: convert named imports from CommonJS packages
+                // into default import + destructuring. This resolves cases like
+                // "Named export 'Helper' not found. The requested module '@codeceptjs/helper' is a CommonJS module"
+                const msg = importTempErr && importTempErr.message || ''
+                const commonJsMatch = msg.match(/The requested module '(.+?)' is a CommonJS module/)
+                if (commonJsMatch) {
+                  // Read the transpiled file, perform heuristic replacement, and import again
+                  const fs = await import('fs')
+                  let content = fs.readFileSync(tempFile, 'utf8')
+                  // Heuristic: replace "import { X, Y } from 'mod'" with default import + destructure
+                  content = content.replace(/import\s+\{([^}]+)\}\s+from\s+(['"])([^'"\)]+)\2/gm, (m, names, q, modName) => {
+                    // Only adjust imports for the module reported in the error or for local modules
+                    if (modName === commonJsMatch[1] || modName.startsWith('.') || !modName.includes('/')) {
+                      const cleanedNames = names.trim()
+                      return `import pkg__interop from ${q}${modName}${q};\nconst { ${cleanedNames} } = pkg__interop`
+                    }
+                    return m
+                  })
+
+                  // Write to a secondary temp file
+                  const os = await import('os')
+                  const path = await import('path')
+                  const fallbackTemp = path.default.join(os.default.tmpdir(), `helper-fallback-${Date.now()}.mjs`)
+                  fs.writeFileSync(fallbackTemp, content, 'utf8')
+                  try {
+                    const mod = await import(fallbackTemp)
+                    HelperClass = mod.default || mod
+                    debug(`helper ${helperName} loaded from transpiled JS after CommonJS interop fix: ${fallbackTemp}`)
+                  } finally {
+                    try { fs.unlinkSync(fallbackTemp) } catch (e) {}
+                  }
+                } else {
+                  throw importTempErr
+                }
+              }
+            } finally {
+              // Cleanup transpiled temporary files
+              const filesToClean = Array.isArray(allTempFiles) ? allTempFiles : [allTempFiles]
+              cleanupTempFiles(filesToClean)
+            }
+          } catch (importErr) {
+            throw new Error(
+              `Helper '${helperName}' is a TypeScript file but could not be loaded.\n` +
+              `Path: ${moduleName}\n` +
+              `Error: ${importErr.message}\n\n` +
+              `To load TypeScript helpers, install 'typescript' in your project or use an ESM loader (e.g. tsx):\n` +
+              `  npm install --save-dev typescript\n` +
+              `  OR run CodeceptJS with an ESM loader: NODE_OPTIONS='--import tsx' npx codeceptjs run\n\n` +
+              `CodeceptJS will transpile TypeScript helpers automatically at runtime if 'typescript' is available.`
+            )
+          }
+      } else if (err.code === 'ERR_REQUIRE_ESM' || (err.message && err.message.includes('ES module'))) {
         // This is an ESM module, use dynamic import
         try {
           const pathModule = await import('path')

lib/parser.js

@@ -17,7 +17,14 @@ export const getParamsToString = function (fn) {
 function getParams(fn) {
   if (fn.isSinonProxy) return []
   try {
-    const reflected = parser.parse(fn)
+    // Convert arrow functions to regular functions for parsing
+    let fnString = fn.toString()
+    // Handle async arrow functions: async (...) => { becomes async function(...) {
+    fnString = fnString.replace(/^async\s*(\([^)]*\))\s*=>/, 'async function$1')
+    // Handle regular arrow functions: (...) => { becomes function(...) {
+    fnString = fnString.replace(/^(\([^)]*\))\s*=>/, 'function$1')
+    
+    const reflected = parser.parse(fnString)
     if (reflected.args.length > 1 || reflected.args[0] === 'I') {
       output.error('Error: old CodeceptJS v2 format detected. Upgrade your project to the new format -> https://bit.ly/codecept3Up')
     }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "4.0.0-beta.20",
+  "version": "4.0.0-beta.21",
   "type": "module",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [

test/data/typescript-helper-autoload/basic_test.ts

@@ -0,0 +1,10 @@
+Feature('TypeScript Helper Auto-load Test');
+
+Scenario('Load TypeScript helper automatically', async ({ I }) => {
+  const greeting = await I.getGreeting('World');
+  console.log('Greeting:', greeting);
+  
+  if (greeting !== 'Hello, World!') {
+    throw new Error(`Expected "Hello, World!" but got "${greeting}"`);
+  }
+});

test/data/typescript-helper-autoload/codecept.conf.ts

@@ -0,0 +1,12 @@
+export const config: CodeceptJS.MainConfig = {
+  tests: './*_test.ts',
+  output: './output',
+  require: ['tsx/cjs'],
+  helpers: {
+    CustomHelper: {
+      require: './helpers/custom.helper.ts'
+    }
+  },
+  include: {},
+  name: 'typescript-helper-autoload'
+};

test/data/typescript-helper-autoload/helpers/custom.helper.ts

@@ -0,0 +1,18 @@
+import Helper from '@codeceptjs/helper';
+
+interface TestData {
+  message: string;
+  count: number;
+}
+
+class CustomHelper extends Helper {
+  async logTestData(data: TestData): Promise<void> {
+    console.log(`Message: ${data.message}, Count: ${data.count}`);
+  }
+
+  getGreeting(name: string): string {
+    return `Hello, ${name}!`;
+  }
+}
+
+export default CustomHelper;

test/data/typescript-helper-autoload/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "typescript-helper-autoload-test",
+  "version": "1.0.0",
+  "type": "module",
+  "dependencies": {
+    "tsx": "^4.20.6"
+  },
+  "devDependencies": {
+    "@codeceptjs/helper": "^2.0.4"
+  }
+}