Update TypeScript ESM documentation with correct guidance

Co-authored-by: kobenguyent <7845001+kobenguyent@users.noreply.github.com>

Author: Copilot

docs/typescript.md

@@ -121,12 +121,39 @@ export const config = {
     "esModuleInterop": true
   },
   "ts-node": {
-    "esm": true,
-    "experimentalSpecifierResolution": "node"
+    "esm": true
   }
 }
 ```
 
+**Required package.json:**
+```json
+{
+  "name": "your-project",
+  "version": "1.0.0"
+  // ⚠️ DO NOT include "type": "module" when using ts-node/esm
+  // ts-node/esm works with CommonJS-style loading
+}
+```
+
+**⚠️ Important Notes:**
+
+1. **Do not use `"type": "module"`** in your package.json when using `ts-node/esm`. The ts-node/esm loader uses CommonJS-style module loading internally and is incompatible with `"type": "module"`.
+
+2. **Use `.js` extensions in imports**: When writing TypeScript code for ESM, you must use `.js` extensions in your imports, even when importing TypeScript files:
+
+```typescript
+// ❌ Wrong - will cause "Cannot find module" error
+import loginPage from "./pages/Login"
+
+// ✅ Correct - use .js extension
+import loginPage from "./pages/Login.js"
+```
+
+TypeScript will automatically resolve `.js` imports to `.ts` files during type-checking. This is the standard approach for ESM + TypeScript projects as documented in the [TypeScript handbook](https://www.typescriptlang.org/docs/handbook/modules/theory.html#typescript-imitates-the-hosts-module-resolution-but-with-types).
+
+3. **For `"type": "module"` projects, use `tsx` instead**: If you need `"type": "module"` in your package.json, use `tsx/cjs` which is designed to work in both CommonJS and ESM contexts.
+
 ### Full TypeScript Features in Tests
 
 With tsx or ts-node/esm, you can use complete TypeScript syntax including imports, enums, interfaces, and types:
@@ -174,7 +201,19 @@ This means the TypeScript loader isn't configured. Make sure:
 
 **Error: Module not found when importing from `.ts` files**
 
-Make sure you're using a proper TypeScript loader (`tsx/cjs` or `ts-node/esm`).
+When using `ts-node/esm` with ESM, you need to use `.js` extensions in imports:
+
+```typescript
+// This will cause an error in ESM mode:
+import loginPage from "./pages/Login"
+
+// Use .js extension instead:
+import loginPage from "./pages/Login.js"
+```
+
+TypeScript will resolve the `.js` import to your `.ts` file during compilation. This is the standard behavior for ESM + TypeScript.
+
+Alternatively, use `tsx/cjs` which doesn't require explicit extensions.
 
 **TypeScript config files vs test files**
 

lib/mocha/factory.js

@@ -62,34 +62,9 @@ class MochaFactory {
         const jsFiles = this.files.filter(file => !file.match(/\.feature$/))
         this.files = this.files.filter(file => !file.match(/\.feature$/))
 
-        // Load JavaScript test files using ESM imports
+        // Load JavaScript test files using original loadFiles
         if (jsFiles.length > 0) {
-          try {
-            // Try original loadFiles first for compatibility
-            originalLoadFiles.call(this, fn)
-          } catch (e) {
-            // If original loadFiles fails, load ESM files manually
-            if (e.message.includes('not in cache') || e.message.includes('ESM') || e.message.includes('getStatus')) {
-              // Load ESM files by importing them synchronously using top-level await workaround
-              for (const file of jsFiles) {
-                try {
-                  // Convert file path to file:// URL for dynamic import
-                  const fileUrl = `file://${file}`
-                  // Use import() but don't await it - let it load in the background
-                  import(fileUrl).catch(importErr => {
-                    // If dynamic import fails, the file may have syntax errors or other issues
-                    console.error(`Failed to load test file ${file}:`, importErr.message)
-                  })
-                  if (fn) fn()
-                } catch (fileErr) {
-                  console.error(`Error processing test file ${file}:`, fileErr.message)
-                  if (fn) fn(fileErr)
-                }
-              }
-            } else {
-              throw e
-            }
-          }
+          originalLoadFiles.call(this, fn)
         }
 
         // add ids for each test and check uniqueness

lib/utils/loaderCheck.js

@@ -84,11 +84,23 @@ 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. In package.json, DO NOT include "type": "module"
+       ts-node/esm is incompatible with "type": "module"
+       
+       If you need "type": "module", use tsx/cjs instead.
+
+  ⚠️  Important: When using ESM with TypeScript, use .js extensions in imports:
+      
+      ❌ Wrong:   import loginPage from "./pages/Login"
+      ✅ Correct: import loginPage from "./pages/Login.js"
+      
+      TypeScript will resolve .js imports to .ts files during type-checking.
+      This is the recommended approach for ESM + TypeScript projects.
+
 📚 Documentation: https://codecept.io/typescript
 
 Note: TypeScript config files (codecept.conf.ts) and helpers are automatically

test/data/typescript-esm-imports/codecept.conf.ts

@@ -0,0 +1,11 @@
+export const config: CodeceptJS.MainConfig = {
+  tests: "./*_test.ts",
+  output: "./output",
+  helpers: {
+    CustomHelper: {
+      require: "../helper.js"
+    }
+  },
+  name: "typescript-esm-imports-test",
+  require: ["ts-node/esm"]
+};

test/data/typescript-esm-imports/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "typescript-esm-imports",
+  "version": "1.0.0",
+  "devDependencies": {
+    "ts-node": "^10.9.2"
+  }
+}

test/data/typescript-esm-imports/pages/Login.ts

@@ -0,0 +1,11 @@
+const { I } = inject();
+
+export default {
+  login(username: string) {
+    I.say(`Logging in with user: ${username}`);
+  },
+  
+  logout() {
+    I.say('Logging out');
+  }
+};

test/data/typescript-esm-imports/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "lib": ["es2022", "DOM"],
+    "esModuleInterop": true,
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strictNullChecks": false,
+    "types": ["codeceptjs", "node"],
+    "declaration": true,
+    "skipLibCheck": true
+  },
+  "ts-node": {
+    "esm": true,
+    "transpileOnly": true
+  },
+  "exclude": ["node_modules"]
+}

test/data/typescript-esm-imports/typescript_esm_test.ts

@@ -0,0 +1,13 @@
+// Test using .js extension to import .ts file (ESM + TypeScript best practice)
+import loginPage from "./pages/Login.js";
+
+Feature("TypeScript ESM Imports");
+
+Scenario("Import page object with .js extension", () => {
+  loginPage.login("testuser");
+});
+
+Scenario("Page object methods work correctly", () => {
+  loginPage.login("admin");
+  loginPage.logout();
+});