feat: add programmatic API with getSuites(), executeSuite(), executeTest()

Add clean programmatic API to Codecept class that wraps Mocha internals,
eliminating duplicated boilerplate across dryRun, workers, and custom scripts.

- getSuites(pattern?) returns parsed suites with tests as plain objects
- executeSuite(suite) runs all tests in a suite
- executeTest(test) runs a single test by fullTitle
- Refactor workers.js to use getSuites() (removes ~30 lines of Mocha boilerplate)
- Refactor dryRun.js to use getSuites() (removes Container.mocha() dependency)
- Export Result class from lib/index.js
- Rewrite docs/internal-api.md with full programmatic API reference

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

Author: DavertMik

docs/internal-api.md

@@ -225,42 +225,143 @@ Step events provide step objects with following fields:
 
 Whenever you execute tests with `--verbose` option you will see registered events and promises executed by a recorder.
 
-## Custom Runner
+## Programmatic API
 
-You can run CodeceptJS tests from your script.
+CodeceptJS can be imported and used programmatically from your scripts. The main entry point is the `Codecept` class, which provides methods to list and execute tests.
+
+### Setup
 
 ```js
-const { codecept: Codecept } = require('codeceptjs');
-
-// define main config
-const config = { 
-  helpers: { 
-    WebDriver: { 
-      browser: 'chrome', 
-      url: 'http://localhost' 
-    }
-  }
+import { Codecept, container } from 'codeceptjs';
+
+const config = {
+  helpers: {
+    Playwright: { browser: 'chromium', url: 'http://localhost' }
+  },
+  tests: './*_test.js',
 };
 
-const opts = { steps: true };
-
-// run CodeceptJS inside async function
-(async () => {
-  const codecept = new Codecept(config, options);
-  codecept.init(__dirname);
-
-  try {
-    await codecept.bootstrap();
-    codecept.loadTests('**_test.js');
-    // run tests
-    await codecept.run(test);
-  } catch (err) {
-    printError(err);
-    process.exitCode = 1;
-  } finally {
-    await codecept.teardown();
-  }    
-})();
+const codecept = new Codecept(config, { steps: true });
+await codecept.init(__dirname);
+```
+
+### Listing Tests
+
+Use `getSuites()` to get all parsed suites with their tests without executing them:
+
+```js
+const suites = codecept.getSuites();
+
+for (const suite of suites) {
+  console.log(suite.title, suite.tags);
+  for (const test of suite.tests) {
+    console.log(' -', test.title, test.tags);
+  }
+}
+```
+
+`getSuites()` accepts an optional glob pattern. If `loadTests()` hasn't been called yet, it will be called internally.
+
+Each suite contains:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `title` | `string` | Feature/suite title |
+| `file` | `string` | Absolute path to the test file |
+| `tags` | `string[]` | Tags (e.g. `@smoke`) |
+| `tests` | `Array` | Tests in this suite |
+
+Each test contains:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `title` | `string` | Scenario title |
+| `uid` | `string` | Unique test identifier |
+| `tags` | `string[]` | Tags from scenario and suite |
+| `fullTitle` | `string` | `"Suite: Test"` format |
+
+### Executing Suites
+
+Use `executeSuite()` to run all tests within a suite:
+
+```js
+await codecept.bootstrap();
+
+const suites = codecept.getSuites();
+for (const suite of suites) {
+  await codecept.executeSuite(suite);
+}
+
+const result = container.result();
+console.log(result.stats);
+console.log(`Passed: ${result.passedTests.length}`);
+console.log(`Failed: ${result.failedTests.length}`);
+
+await codecept.teardown();
+```
+
+### Executing Individual Tests
+
+Use `executeTest()` to run a single test:
+
+```js
+await codecept.bootstrap();
+
+const suites = codecept.getSuites();
+for (const test of suites[0].tests) {
+  await codecept.executeTest(test);
+}
+
+const result = container.result();
+await codecept.teardown();
+```
+
+### Result Object
+
+The `Result` object returned by `container.result()` provides:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `stats` | `object` | `{ passes, failures, tests, pending, failedHooks, duration }` |
+| `tests` | `Test[]` | All collected tests |
+| `passedTests` | `Test[]` | Tests that passed |
+| `failedTests` | `Test[]` | Tests that failed |
+| `skippedTests` | `Test[]` | Tests that were skipped |
+| `hasFailed` | `boolean` | Whether any test failed |
+| `duration` | `number` | Total duration in milliseconds |
+
+### Full Lifecycle (Low-Level)
+
+For full control, you can orchestrate the lifecycle manually:
+
+```js
+const codecept = new Codecept(config, opts);
+await codecept.init(__dirname);
+
+try {
+  await codecept.bootstrap();
+  codecept.loadTests('**_test.js');
+  await codecept.run();
+} catch (err) {
+  console.error(err);
+  process.exitCode = 1;
+} finally {
+  await codecept.teardown();
+}
 ```
 
-> Also, you can run tests inside workers in a custom scripts. Please refer to the [parallel execution](/parallel) guide for more details.
+### Codecept Methods Reference
+
+| Method | Description |
+|--------|-------------|
+| `new Codecept(config, opts)` | Create runner instance |
+| `await init(dir)` | Initialize globals, container, helpers, plugins |
+| `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 teardown()` | Execute teardown hook |
+
+> 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,6 +11,7 @@ const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 
 import Helper from '@codeceptjs/helper'
+import MochaFactory from './mocha/factory.js'
 import container from './container.js'
 import Config from './config.js'
 import event from './event.js'
@@ -256,6 +257,98 @@ class Codecept {
     return testFiles.slice(startIndex, endIndex)
   }
 
+  /**
+   * Returns parsed suites with their tests.
+   * Creates a temporary Mocha instance to avoid polluting container state.
+   * Must be called after init(). Calls loadTests() internally if testFiles is empty.
+   *
+   * @param {string} [pattern] - glob pattern for test files
+   * @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
+  }
+
+  /**
+   * Execute 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)
+  }
+
+  /**
+   * Execute 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)
+      }
+    })
+  }
+
   /**
    * Run a specific test or all loaded tests.
    *

lib/command/dryRun.js

@@ -4,7 +4,6 @@ import Codecept from '../codecept.js'
 import output from '../output.js'
 import event from '../event.js'
 import store from '../store.js'
-import Container from '../container.js'
 
 export default async function (test, options) {
   if (options.grep) process.env.grep = options.grep
@@ -35,7 +34,7 @@ export default async function (test, options) {
     store.dryRun = true
 
     if (!options.steps && !options.verbose && !options.debug) {
-      await printTests(codecept.testFiles)
+      await printTests(codecept)
       return
     }
     event.dispatcher.on(event.all.result, printFooter)
@@ -46,16 +45,14 @@ export default async function (test, options) {
   }
 }
 
-async function printTests(files) {
+async function printTests(codecept) {
   const { default: figures } = await import('figures')
   const { default: colors } = await import('chalk')
 
   output.print(output.styles.debug(`Tests from ${store.codeceptDir}:`))
   output.print()
 
-  const mocha = Container.mocha()
-  mocha.files = files
-  mocha.loadFiles()
+  const suites = codecept.getSuites()
 
   let numOfTests = 0
   let numOfSuites = 0
@@ -65,19 +62,19 @@ async function printTests(files) {
   let filterRegex
   if (filterBy) {
     try {
-      filterRegex = new RegExp(filterBy, 'i') // Case-insensitive matching
+      filterRegex = new RegExp(filterBy, 'i')
     } catch (err) {
       console.error(`Invalid grep pattern: ${filterBy}`)
       process.exit(1)
     }
   }
 
-  for (const suite of mocha.suite.suites) {
+  for (const suite of suites) {
     const suiteMatches = filterRegex ? filterRegex.test(suite.title) : true
     let suiteHasMatchingTests = false
 
     if (suiteMatches) {
-      outputString += `${colors.white.bold(suite.title)} -- ${output.styles.log(suite.file || '')}\n`
+      outputString += `${colors.white.bold(suite.title)} -- ${output.styles.log(suite.file)}\n`
       suiteHasMatchingTests = true
       numOfSuites++
     }
@@ -87,7 +84,7 @@ async function printTests(files) {
 
       if (testMatches) {
         if (!suiteMatches && !suiteHasMatchingTests) {
-          outputString += `${colors.white.bold(suite.title)} -- ${output.styles.log(suite.file || '')}\n`
+          outputString += `${colors.white.bold(suite.title)} -- ${output.styles.log(suite.file)}\n`
           suiteHasMatchingTests = true
           numOfSuites++
         }

lib/index.js

@@ -23,6 +23,7 @@ import heal from './heal.js'
 import ai from './ai.js'
 import Workers from './workers.js'
 import Secret, { secret } from './secret.js'
+import Result from './result.js'
 
 export default {
   /** @type {typeof CodeceptJS.Codecept} */
@@ -67,7 +68,10 @@ export default {
   Secret,
   /** @type {typeof CodeceptJS.secret} */
   secret,
+
+  /** @type {typeof Result} */
+  Result,
 }
 
 // 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 }
+export { codecept, output, container, event, recorder, config, actor, helper, pause, within, dataTable, dataTableArgument, store, locator, heal, ai, Workers, Secret, secret, Result }