refactor: extract Runner class from Codecept for all Mocha interactions

- Create lib/runner.js with Runner class that owns all Mocha interactions:
  getSuites(), run(), runSuite(), runTest() backed by a single _execute() core
- Codecept.run/runSuite/runTest/getSuites now delegate to this.runner
- Remove duplicated executeTest() that was copy of run()
- Refactor check.js to use codecept.getSuites() instead of manual Mocha
- Export Runner from lib/index.js

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: DavertMik

docs/internal-api.md

@@ -282,14 +282,14 @@ Each test contains:
 
 ### Executing Suites
 
-Use `executeSuite()` to run all tests within a suite:
+Use `runSuite()` to run all tests within a suite:
 
 ```js
 await codecept.bootstrap();
 
 const suites = codecept.getSuites();
 for (const suite of suites) {
-  await codecept.executeSuite(suite);
+  await codecept.runSuite(suite);
 }
 
 const result = container.result();
@@ -302,14 +302,14 @@ await codecept.teardown();
 
 ### Executing Individual Tests
 
-Use `executeTest()` to run a single test:
+Use `runTest()` to run a single test:
 
 ```js
 await codecept.bootstrap();
 
 const suites = codecept.getSuites();
 for (const test of suites[0].tests) {
-  await codecept.executeTest(test);
+  await codecept.runTest(test);
 }
 
 const result = container.result();
@@ -350,18 +350,42 @@ try {
 }
 ```
 
+### Runner
+
+All Mocha interactions are handled by the `Runner` class (`lib/runner.js`). After calling `init()`, it's available as `codecept.runner`:
+
+```js
+const runner = codecept.runner;
+
+// Same as codecept.getSuites() / runSuite() / runTest()
+const suites = runner.getSuites();
+await runner.runSuite(suites[0]);
+await runner.runTest(suites[0].tests[0]);
+```
+
+The `Codecept` methods (`getSuites`, `runSuite`, `runTest`, `run`) delegate to the Runner.
+
 ### Codecept Methods Reference
 
 | Method | Description |
 |--------|-------------|
-| `new Codecept(config, opts)` | Create runner instance |
-| `await init(dir)` | Initialize globals, container, helpers, plugins |
+| `new Codecept(config, opts)` | Create codecept instance |
+| `await init(dir)` | Initialize globals, container, helpers, plugins, runner |
 | `loadTests(pattern?)` | Find test files by glob pattern |
 | `getSuites(pattern?)` | Load and return parsed suites with tests |
 | `await bootstrap()` | Execute bootstrap hook |
 | `await run(test?)` | Run all loaded tests (or filter by file path) |
-| `await executeSuite(suite)` | Run a specific suite from `getSuites()` |
-| `await executeTest(test)` | Run a specific test from `getSuites()` |
+| `await runSuite(suite)` | Run a specific suite from `getSuites()` |
+| `await runTest(test)` | Run a specific test from `getSuites()` |
 | `await teardown()` | Execute teardown hook |
 
+### Runner Methods Reference
+
+| Method | Description |
+|--------|-------------|
+| `getSuites(pattern?)` | Parse suites using a temporary Mocha instance |
+| `run(test?)` | Run tests, optionally filtering by file path |
+| `runSuite(suite)` | Run all tests in a suite |
+| `runTest(test)` | Run a single test by fullTitle |
+
 > Also, you can run tests inside workers in a custom script. Please refer to the [parallel execution](/parallel) guide for more details.

lib/codecept.js

@@ -11,17 +11,13 @@ const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 
 import Helper from '@codeceptjs/helper'
-import MochaFactory from './mocha/factory.js'
+import Runner from './runner.js'
 import container from './container.js'
 import Config from './config.js'
-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 { initCodeceptGlobals } from './globals.js'
-import { validateTypeScriptSetup, getTSNodeESMWarning } from './utils/loaderCheck.js'
-import recorder from './recorder.js'
 import store from './store.js'
 
 import storeListener from './listener/store.js'
@@ -104,6 +100,7 @@ class Codecept {
     await this.requireModules(this.requiringModules)
     // initializing listeners
     await container.create(this.config, this.opts)
+    this.runner = new Runner(this)
     await this.runHooks()
   }
 
@@ -266,87 +263,29 @@ class Codecept {
    * @returns {Array<{title: string, file: string, tags: string[], tests: Array<{title: string, uid: string, tags: string[], fullTitle: string}>}>}
    */
   getSuites(pattern) {
-    if (this.testFiles.length === 0) {
-      this.loadTests(pattern)
-    }
-
-    const tempMocha = MochaFactory.create(this.config.mocha || {}, this.opts || {})
-    tempMocha.files = this.testFiles
-    tempMocha.loadFiles()
-
-    const suites = []
-    for (const suite of tempMocha.suite.suites) {
-      suites.push({
-        ...suite.simplify(),
-        file: suite.file || '',
-        tests: suite.tests.map(test => ({
-          ...test.simplify(),
-          fullTitle: test.fullTitle(),
-        })),
-      })
-    }
-
-    tempMocha.unloadFiles()
-    return suites
+    return this.runner.getSuites(pattern)
   }
 
   /**
-   * Execute all tests in a suite.
+   * Run all tests in a suite.
    * Must be called after init() and bootstrap().
    *
    * @param {{file: string}} suite - suite object returned by getSuites()
    * @returns {Promise<void>}
    */
-  async executeSuite(suite) {
-    return this.run(suite.file)
+  async runSuite(suite) {
+    return this.runner.runSuite(suite)
   }
 
   /**
-   * Execute a single test by its fullTitle.
+   * Run a single test by its fullTitle.
    * Must be called after init() and bootstrap().
    *
    * @param {{fullTitle: string}} test - test object returned by getSuites()
    * @returns {Promise<void>}
    */
-  async executeTest(test) {
-    await container.started()
-
-    const tsValidation = validateTypeScriptSetup(this.testFiles, this.requiringModules || [])
-    if (tsValidation.hasError) {
-      output.error(tsValidation.message)
-      process.exit(1)
-    }
-
-    try {
-      const { loadTranslations } = await import('./mocha/gherkin.js')
-      await loadTranslations()
-    } catch (e) {
-      // Ignore if gherkin module not available
-    }
-
-    return new Promise((resolve, reject) => {
-      const mocha = container.mocha()
-      mocha.files = this.testFiles
-      mocha.grep(test.fullTitle)
-
-      const done = async (failures) => {
-        event.emit(event.all.result, container.result())
-        event.emit(event.all.after, this)
-        await recorder.promise()
-        if (failures) {
-          process.exitCode = 1
-        }
-        resolve()
-      }
-
-      try {
-        event.emit(event.all.before, this)
-        mocha.run(async (failures) => await done(failures))
-      } catch (e) {
-        output.error(e.stack)
-        reject(e)
-      }
-    })
+  async runTest(test) {
+    return this.runner.runTest(test)
   }
 
   /**
@@ -356,64 +295,7 @@ class Codecept {
    * @returns {Promise<void>}
    */
   async run(test) {
-    await container.started()
-
-    // Check TypeScript loader configuration before running tests
-    const tsValidation = validateTypeScriptSetup(this.testFiles, this.requiringModules || [])
-    if (tsValidation.hasError) {
-      output.error(tsValidation.message)
-      process.exit(1)
-    }
-
-    // Show warning if ts-node/esm is being used
-    const tsWarning = getTSNodeESMWarning(this.requiringModules || [])
-    if (tsWarning) {
-      output.print(output.colors.yellow(tsWarning))
-    }
-
-    // Ensure translations are loaded for Gherkin features
-    try {
-      const { loadTranslations } = await import('./mocha/gherkin.js')
-      await loadTranslations()
-    } catch (e) {
-      // Ignore if gherkin module not available
-    }
-
-    return new Promise((resolve, reject) => {
-      const mocha = container.mocha()
-      mocha.files = this.testFiles
-
-      if (test) {
-        if (!fsPath.isAbsolute(test)) {
-          test = fsPath.join(store.codeceptDir, test)
-        }
-        const testBasename = fsPath.basename(test, '.js')
-        const testFeatureBasename = fsPath.basename(test, '.feature')
-        mocha.files = mocha.files.filter(t => {
-          return fsPath.basename(t, '.js') === testBasename || fsPath.basename(t, '.feature') === testFeatureBasename || t === test
-        })
-      }
-
-      const done = async (failures) => {
-        event.emit(event.all.result, container.result())
-        event.emit(event.all.after, this)
-        // Wait for any recorder tasks added by event.all.after handlers
-        await recorder.promise()
-        // Set exit code based on test failures
-        if (failures) {
-          process.exitCode = 1
-        }
-        resolve()
-      }
-
-      try {
-        event.emit(event.all.before, this)
-        mocha.run(async (failures) => await done(failures))
-      } catch (e) {
-        output.error(e.stack)
-        reject(e)
-      }
-    })
+    return this.runner.run(test)
   }
 
   /**

lib/command/check.js

@@ -70,15 +70,10 @@ export default async function (options) {
   if (codecept) {
     try {
       codecept.loadTests()
-      const files = codecept.testFiles
-      const mocha = Container.mocha()
-      mocha.files = files
-      mocha.loadFiles()
-
-      for (const suite of mocha.suite.suites) {
-        if (suite && suite.tests) {
-          numTests += suite.tests.length
-        }
+      const suites = codecept.getSuites()
+
+      for (const suite of suites) {
+        numTests += suite.tests.length
       }
 
       if (numTests > 0) {

lib/index.js

@@ -24,6 +24,7 @@ import ai from './ai.js'
 import Workers from './workers.js'
 import Secret, { secret } from './secret.js'
 import Result from './result.js'
+import Runner from './runner.js'
 
 export default {
   /** @type {typeof CodeceptJS.Codecept} */
@@ -71,7 +72,9 @@ export default {
 
   /** @type {typeof Result} */
   Result,
+
+  Runner,
 }
 
 // Named exports for ESM compatibility
-export { codecept, output, container, event, recorder, config, actor, helper, pause, within, dataTable, dataTableArgument, store, locator, heal, ai, Workers, Secret, secret, Result }
+export { codecept, output, container, event, recorder, config, actor, helper, pause, within, dataTable, dataTableArgument, store, locator, heal, ai, Workers, Secret, secret, Result, Runner }