codeceptjs 4.0.0-beta.6.esm-aria → 4.0.0-beta.8.esm-aria

package/README.md

@@ -10,7 +10,6 @@
 | 🌐 Web    | Playwright | [![Playwright Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/playwright.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/playwright.yml)               |
 | 🌐 Web    | Puppeteer  | [![Puppeteer Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml)                  |
 | 🌐 Web    | WebDriver  | [![WebDriver Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml)                  |
-| 🌐 Web    | TestCafe   | [![TestCafe Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/testcafe.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/testcafe.yml)                     |
 | 📱 Mobile | Appium     | [![Appium Tests - Android](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium_Android.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium_Android.yml) |
 
 # CodeceptJS [![Made in Ukraine](https://img.shields.io/badge/made_in-ukraine-ffd700.svg?labelColor=0057b7)](https://stand-with-ukraine.pp.ua)
@@ -43,7 +42,6 @@ CodeceptJS uses **Helper** modules to provide actions to `I` object. Currently,
 - [**Playwright**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Playwright.md) - is a Node library to automate the Chromium, WebKit and Firefox browsers with a single API.
 - [**Puppeteer**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Puppeteer.md) - uses Google Chrome's Puppeteer for fast headless testing.
 - [**WebDriver**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/WebDriver.md) - uses [webdriverio](http://webdriver.io/) to run tests via WebDriver or Devtools protocol.
-- [**TestCafe**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/TestCafe.md) - cheap and fast cross-browser test automation.
 - [**Appium**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Appium.md) - for **mobile testing** with Appium
 - [**Detox**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Detox.md) - This is a wrapper on top of Detox library, aimed to unify testing experience for CodeceptJS framework. Detox provides a grey box testing for mobile applications, playing especially well for React Native apps.
 
@@ -53,7 +51,7 @@ And more to come...
 
 CodeceptJS is a successor of [Codeception](http://codeception.com), a popular full-stack testing framework for PHP.
 With CodeceptJS your scenario-driven functional and acceptance tests will be as simple and clean as they can be.
-You don't need to worry about asynchronous nature of NodeJS or about various APIs of Playwright, Selenium, Puppeteer, TestCafe, etc. as CodeceptJS unifies them and makes them work as they are synchronous.
+You don't need to worry about asynchronous nature of NodeJS or about various APIs of Playwright, Selenium, Puppeteer, etc. as CodeceptJS unifies them and makes them work as they are synchronous.
 
 ## Features
 
@@ -64,6 +62,8 @@ You don't need to worry about asynchronous nature of NodeJS or about various API
 - Also plays nice with TypeScript.
 - </> Smart locators: use names, labels, matching text, CSS or XPath to locate elements.
 - 🌐 Interactive debugging shell: pause test at any point and try different commands in a browser.
+- ⚡ **Parallel testing** with dynamic test pooling for optimal load balancing and performance.
+- 📊 **Built-in HTML Reporter** with interactive dashboard, step-by-step execution details, and comprehensive test analytics.
 - Easily create tests, pageobjects, stepobjects with CLI generators.
 
 ## Installation
@@ -233,6 +233,49 @@ Scenario('test title', () => {
 })
 ```
 
+## HTML Reporter
+
+CodeceptJS includes a powerful built-in HTML Reporter that generates comprehensive, interactive test reports with detailed information about your test runs. The HTML reporter is **enabled by default** for all new projects and provides:
+
+### Features
+
+- **Interactive Dashboard**: Visual statistics, pie charts, and expandable test details
+- **Step-by-Step Execution**: Shows individual test steps with timing and status indicators
+- **BDD/Gherkin Support**: Full support for feature files with proper scenario formatting
+- **System Information**: Comprehensive environment details including browser versions
+- **Advanced Filtering**: Real-time filtering by status, tags, features, and test types
+- **History Tracking**: Multi-run history with trend visualization
+- **Error Details**: Clean formatting of error messages and stack traces
+- **Artifacts Support**: Display screenshots and other test artifacts
+
+### Visual Examples
+
+#### Interactive Test Dashboard
+
+The main dashboard provides a complete overview with interactive statistics and pie charts:
+
+![HTML Reporter Dashboard](docs/shared/html-reporter-main-dashboard.png)
+
+#### Detailed Test Results
+
+Each test shows comprehensive execution details with expandable step information:
+
+![HTML Reporter Test Details](docs/shared/html-reporter-test-details.png)
+
+#### Advanced Filtering Capabilities
+
+Real-time filtering allows quick navigation through test results:
+
+![HTML Reporter Filtering](docs/shared/html-reporter-filtering.png)
+
+#### BDD/Gherkin Support
+
+Full support for Gherkin scenarios with proper feature formatting:
+
+![HTML Reporter BDD Details](docs/shared/html-reporter-bdd-details.png)
+
+The HTML reporter generates self-contained reports that can be easily shared with your team. Learn more about configuration and features in the [HTML Reporter documentation](https://codecept.io/plugins/#htmlreporter).
+
 ## PageObjects
 
 CodeceptJS provides the most simple way to create and use page objects in your test.

package/bin/codecept.js

@@ -141,6 +141,12 @@ program.command('generate:helper [path]').alias('gh').description('Generates a n
 
 program.command('generate:heal [path]').alias('gr').description('Generates basic heal recipes').action(commandHandlerWithProperty('../lib/command/generate.js', 'heal'))
 
+program
+  .command('generate:prompt <promptName> [path]')
+  .alias('gp')
+  .description('Generates AI prompt template (writeStep, healStep, generatePageObject)')
+  .action(commandHandlerWithProperty('../lib/command/generate.js', 'prompt'))
+
 program
   .command('run [test]')
   .description('Executes tests')
@@ -157,6 +163,8 @@ program
   .option('--tests', 'run only JS test files and skip features')
   .option('--no-timeouts', 'disable all timeouts')
   .option('-p, --plugins <k=v,k2=v2,...>', 'enable plugins, comma-separated')
+  .option('--shuffle', 'Shuffle the order in which test files run')
+  .option('--shard <index/total>', 'run only a fraction of tests (e.g., --shard 1/4)')
 
   // mocha options
   .option('--colors', 'force enabling of colors')
@@ -188,6 +196,7 @@ program
   .option('-i, --invert', 'inverts --grep matches')
   .option('-o, --override [value]', 'override current config options')
   .option('--suites', 'parallel execution of suites not single tests')
+  .option('--by <strategy>', 'test distribution strategy: "test" (pre-assign individual tests), "suite" (pre-assign test suites), or "pool" (dynamic distribution for optimal load balancing, recommended)')
   .option(commandFlags.debug.flag, commandFlags.debug.description)
   .option(commandFlags.verbose.flag, commandFlags.verbose.description)
   .option('--features', 'run only *.feature files and skip tests')

package/bin/test-server.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+/**
+ * Standalone test server script to replace json-server
+ */
+
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { dirname } from 'path'
+import TestServer from '../lib/test-server.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+// Parse command line arguments
+const args = process.argv.slice(2)
+let dbFile = path.join(__dirname, '../test/data/rest/db.json')
+let port = 8010
+let host = '0.0.0.0'
+let readOnly = false
+
+// Simple argument parsing
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i]
+
+  if (arg === '-p' || arg === '--port') {
+    port = parseInt(args[++i])
+  } else if (arg === '--host') {
+    host = args[++i]
+  } else if (arg === '--read-only' || arg === '-r') {
+    readOnly = true
+  } else if (!arg.startsWith('-')) {
+    dbFile = path.resolve(arg)
+  }
+}
+
+// Create and start server
+const server = new TestServer({ port, host, dbFile, readOnly })
+
+console.log(`Starting test server with db file: ${dbFile}`)
+if (readOnly) {
+  console.log('Running in READ-ONLY mode - changes will not be persisted to disk')
+}
+
+server
+  .start()
+  .then(() => {
+    console.log(`Test server is ready and listening on http://${host}:${port}`)
+  })
+  .catch(err => {
+    console.error('Failed to start test server:', err)
+    process.exit(1)
+  })
+
+// Graceful shutdown
+process.on('SIGINT', () => {
+  console.log('\nShutting down test server...')
+  server.stop().then(() => process.exit(0))
+})
+
+process.on('SIGTERM', () => {
+  console.log('\nShutting down test server...')
+  server.stop().then(() => process.exit(0))
+})

package/docs/webapi/click.mustache

@@ -3,9 +3,13 @@ If a fuzzy locator is given, the page will be searched for a button, link, or im
 For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
 For images, the "alt" attribute and inner text of any parent links are searched.
 
+If no locator is provided, defaults to clicking the body element (`'//body'`).
+
 The second parameter is a context (CSS or XPath locator) to narrow the search.
 
 ```js
+// click body element (default)
+I.click();
 // simple link
 I.click('Logout');
 // button of form
@@ -20,6 +24,6 @@ I.click('Logout', '#nav');
 I.click({css: 'nav a.login'});
 ```
 
-@param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+@param {CodeceptJS.LocatorOrString} [locator='//body'] (optional, `'//body'` by default) clickable link or button located by text, or any element located by CSS|XPath|strict locator.
 @param {?CodeceptJS.LocatorOrString | null} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
 @returns {void} automatically synchronized promise through #recorder

package/lib/ai.js

@@ -3,6 +3,12 @@ const debug = debugModule('codeceptjs:ai')
 import output from './output.js'
 import event from './event.js'
 import { removeNonInteractiveElements, minifyHtml, splitByChunks } from './html.js'
+import { generateText } from 'ai'
+import { fileURLToPath } from 'url'
+import path from 'path'
+import { fileExists } from './utils.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 const defaultHtmlConfig = {
   maxLength: 50000,
@@ -11,62 +17,31 @@ const defaultHtmlConfig = {
   html: {},
 }
 
-const defaultPrompts = {
-  writeStep: (html, input) => [
-    {
-      role: 'user',
-      content: `I am test engineer writing test in CodeceptJS
-        I have opened web page and I want to use CodeceptJS to ${input} on this page
-        Provide me valid CodeceptJS code to accomplish it
-        Use only locators from this HTML: \n\n${html}`,
-    },
-  ],
-
-  healStep: (html, { step, error, prevSteps }) => {
-    return [
-      {
-        role: 'user',
-        content: `As a test automation engineer I am testing web application using CodeceptJS.
-        I want to heal a test that fails. Here is the list of executed steps: ${prevSteps.map(s => s.toString()).join(', ')}
-        Propose how to adjust ${step.toCode()} step to fix the test.
-        Use locators in order of preference: semantic locator by text, CSS, XPath. Use codeblocks marked with \`\`\`
-        Here is the error message: ${error.message}
-        Here is HTML code of a page where the failure has happened: \n\n${html}`,
-      },
-    ]
-  },
-
-  generatePageObject: (html, extraPrompt = '', rootLocator = null) => [
-    {
-      role: 'user',
-      content: `As a test automation engineer I am creating a Page Object for a web application using CodeceptJS.
-        Here is an sample page object:
-
-const { I } = inject();
-
-module.exports = {
-
-  // setting locators
-  element1: '#selector',
-  element2: '.selector',
-  element3: locate().withText('text'),
-
-  // seting methods
-  doSomethingOnPage(params) {
-    // ...
-  },  
-}        
-
-        I want to generate a Page Object for the page I provide.
-        Write JavaScript code in similar manner to list all locators on the page.
-        Use locators in order of preference: by text (use locate().withText()), label, CSS, XPath.
-        Avoid TailwindCSS, Bootstrap or React style formatting classes in locators.
-        Add methods to to interact with page when needed.
-        ${extraPrompt}
-        ${rootLocator ? `All provided elements are inside '${rootLocator}'. Declare it as root variable and for every locator use locate(...).inside(root)` : ''}
-        Add only locators from this HTML: \n\n${html}`,
-    },
-  ],
+async function loadPrompts() {
+  const prompts = {}
+  const promptNames = ['writeStep', 'healStep', 'generatePageObject']
+
+  for (const name of promptNames) {
+    let promptPath
+
+    if (global.codecept_dir) {
+      promptPath = path.join(global.codecept_dir, `prompts/${name}.js`)
+    }
+
+    if (!promptPath || !fileExists(promptPath)) {
+      promptPath = path.join(__dirname, `template/prompts/${name}.js`)
+    }
+
+    try {
+      const module = await import(promptPath)
+      prompts[name] = module.default || module
+      debug(`Loaded prompt ${name} from ${promptPath}`)
+    } catch (err) {
+      debug(`Failed to load prompt ${name}:`, err.message)
+    }
+  }
+
+  return prompts
 }
 
 class AiAssistant {
@@ -78,7 +53,7 @@ class AiAssistant {
     this.connectToEvents()
   }
 
-  enable(config = {}) {
+  async enable(config = {}) {
     debug('Enabling AI assistant')
     this.isEnabled = true
 
@@ -86,7 +61,9 @@ class AiAssistant {
 
     this.config = Object.assign(this.config, aiConfig)
     this.htmlConfig = Object.assign(defaultHtmlConfig, html)
-    this.prompts = Object.assign(defaultPrompts, prompts)
+
+    const loadedPrompts = await loadPrompts()
+    this.prompts = Object.assign(loadedPrompts, prompts || {})
 
     debug('Config', this.config)
   }
@@ -96,9 +73,8 @@ class AiAssistant {
     this.isEnabled = false
     this.config = {
       maxTokens: 1000000,
-      request: null,
+      model: null,
       response: parseCodeBlocks,
-      // lets limit token usage to 1M
     }
     this.minifiedHtml = null
     this.response = null
@@ -114,41 +90,44 @@ class AiAssistant {
       if (this.isEnabled && this.numTokens > 0) {
         const numTokensK = Math.ceil(this.numTokens / 1000)
         const maxTokensK = Math.ceil(this.config.maxTokens / 1000)
-        output.print(`AI assistant took ${this.totalTime}s and used ~${numTokensK}K input tokens. Tokens limit: ${maxTokensK}K`)
+        output.print(`AI assistant took ${this.totalTime}s and used ${numTokensK}K tokens. Tokens limit: ${maxTokensK}K`)
       }
     })
   }
 
-  checkRequestFn() {
+  checkModel() {
     if (!this.isEnabled) {
       debug('AI assistant is disabled')
       return
     }
 
-    if (this.config.request) return
+    if (this.config.model) return
 
-    const noRequestErrorMessage = `
-     No request function is set for AI assistant.
+    const noModelErrorMessage = `
+     No model is set for AI assistant.
 
-     [!] AI request was decoupled from CodeceptJS. To connect to OpenAI or other AI service.
-     Please implement your own request function and set it in the config.
+     [!] Please configure AI model using Vercel AI SDK providers.
 
      Example (connect to OpenAI):
 
+     import { openai } from '@ai-sdk/openai';
+
      ai: {
-       request: async (messages) => {
-         const OpenAI = require('openai');
-         const openai = new OpenAI({ apiKey: process.env['OPENAI_API_KEY'] })
-         const response = await openai.chat.completions.create({
-          model: 'gpt-4o-mini',
-          messages,
-         });
-         return response?.data?.choices[0]?.message?.content;
-       }
+       model: openai('gpt-4o-mini')
      }
+
+     Example (connect to Anthropic):
+
+     import { anthropic } from '@ai-sdk/anthropic';
+
+     ai: {
+       model: anthropic('claude-3-5-sonnet-20241022')
+     }
+
+     See https://ai-sdk.dev/docs/foundations/providers-and-models for all providers.
     `.trim()
 
-    throw new Error(noRequestErrorMessage)
+    throw new Error(noModelErrorMessage)
   }
 
   async setHtmlContext(html) {
@@ -172,28 +151,32 @@ class AiAssistant {
     if (!this.isEnabled) return ''
 
     try {
-      this.checkRequestFn()
+      this.checkModel()
       debug('Request', messages)
 
       this.response = null
 
-      this.calculateTokens(messages)
       const startTime = process.hrtime()
-      this.response = await this.config.request(messages)
+      const result = await generateText({
+        model: this.config.model,
+        messages,
+      })
       const endTime = process.hrtime(startTime)
       const executionTimeInSeconds = endTime[0] + endTime[1] / 1e9
 
+      this.response = result.text
+      this.numTokens += result.usage.totalTokens
+
       this.totalTime += Math.round(executionTimeInSeconds)
       debug('AI response time', executionTimeInSeconds)
       debug('Response', this.response)
+      debug('Usage', result.usage)
       this.stopWhenReachingTokensLimit()
       return this.response
     } catch (err) {
-      debug(err.response)
+      debug(err)
       output.print('')
       output.error(`AI service error: ${err.message}`)
-      if (err?.response?.data?.error?.code) output.error(err?.response?.data?.error?.code)
-      if (err?.response?.data?.error?.message) output.error(err?.response?.data?.error?.message)
       this.stopWhenReachingTokensLimit()
       return ''
     }
@@ -232,25 +215,6 @@ class AiAssistant {
     return this.config.response(response)
   }
 
-  calculateTokens(messages) {
-    // we implement naive approach for calculating tokens with no extra requests
-    // this approach was tested via https://platform.openai.com/tokenizer
-    // we need it to display current tokens usage so users could analyze effectiveness of AI
-
-    const inputString = messages
-      .map(m => m.content)
-      .join(' ')
-      .trim()
-    const numWords = (inputString.match(/[^\s\-:=]+/g) || []).length
-
-    // 2.5 token is constant for average HTML input
-    const tokens = numWords * 2.5
-
-    this.numTokens += tokens
-
-    return tokens
-  }
-
   stopWhenReachingTokensLimit() {
     if (this.numTokens < this.config.maxTokens) return
 

package/lib/codecept.js

@@ -1,14 +1,13 @@
 import { existsSync, readFileSync } from 'fs'
 import { globSync } from 'glob'
+import shuffle from 'lodash.shuffle'
 import fsPath from 'path'
 import { resolve } from 'path'
 import { fileURLToPath } from 'url'
 import { dirname } from 'path'
-import { createRequire } from 'module'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
-const require = createRequire(import.meta.url)
 
 import Helper from '@codeceptjs/helper'
 import container from './container.js'
@@ -19,6 +18,7 @@ import ActorFactory from './actor.js'
 import output from './output.js'
 import { emptyFolder } from './utils.js'
 import { initCodeceptGlobals } from './globals.js'
+import recorder from './recorder.js'
 
 import storeListener from './listener/store.js'
 import stepsListener from './listener/steps.js'
@@ -45,7 +45,7 @@ class Codecept {
     this.config = Config.create(config)
     this.opts = opts
     this.testFiles = new Array(0)
-    this.requireModules(config.require)
+    this.requiringModules = config.require
   }
 
   /**
@@ -53,26 +53,36 @@ class Codecept {
    *
    * @param {string[]} requiringModules
    */
-  requireModules(requiringModules) {
+  async requireModules(requiringModules) {
     if (requiringModules) {
-      requiringModules.forEach(requiredModule => {
-        const isLocalFile = existsSync(requiredModule) || existsSync(`${requiredModule}.js`)
+      for (const requiredModule of requiringModules) {
+        let modulePath = requiredModule
+        const isLocalFile = existsSync(modulePath) || existsSync(`${modulePath}.js`)
         if (isLocalFile) {
-          requiredModule = resolve(requiredModule)
+          modulePath = resolve(modulePath)
+          // For ESM, ensure .js extension for local files
+          if (!modulePath.endsWith('.js') && !modulePath.endsWith('.mjs') && !modulePath.endsWith('.cjs')) {
+            if (existsSync(`${modulePath}.js`)) {
+              modulePath = `${modulePath}.js`
+            }
+          }
         }
-        require(requiredModule)
-      })
+        // Use dynamic import for ESM
+        await import(modulePath)
+      }
     }
   }
 
   /**
-   * Initialize CodeceptJS at specific directory.
-   * If async initialization is required, pass callback as second parameter.
+   * Initialize CodeceptJS at specific dir.
+   * Loads config, requires factory methods
    *
    * @param {string} dir
    */
   async init(dir) {
     await this.initGlobals(dir)
+    // Require modules before initializing
+    await this.requireModules(this.requiringModules)
     // initializing listeners
     await container.create(this.config, this.opts)
     // Store container globally for easy access
@@ -93,16 +103,24 @@ class Codecept {
    * Executes hooks.
    */
   async runHooks() {
-    // default hooks
-    runHook(storeListener)
-    runHook(stepsListener)
-    runHook(configListener)
-    runHook(resultListener)
-    runHook(helpersListener)
-    runHook(globalTimeoutListener)
-    runHook(globalRetryListener)
-    runHook(exitListener)
-    runHook(emptyRunListener)
+    // default hooks - dynamic imports for ESM
+    const listenerModules = [
+      './listener/store.js',
+      './listener/steps.js',
+      './listener/config.js',
+      './listener/result.js',
+      './listener/helpers.js',
+      './listener/globalTimeout.js',
+      './listener/globalRetry.js',
+      './listener/retryEnhancer.js',
+      './listener/exit.js',
+      './listener/emptyRun.js',
+    ]
+
+    for (const modulePath of listenerModules) {
+      const module = await import(modulePath)
+      runHook(module.default || module)
+    }
 
     // custom hooks (previous iteration of plugins)
     this.config.hooks.forEach(hook => runHook(hook))
@@ -111,6 +129,7 @@ class Codecept {
   /**
    * Executes bootstrap.
    *
+   * @returns {Promise<void>}
    */
   async bootstrap() {
     return runHook(this.config.bootstrap, 'bootstrap')
@@ -118,7 +137,8 @@ class Codecept {
 
   /**
    * Executes teardown.
-
+   *
+   * @returns {Promise<void>}
    */
   async teardown() {
     return runHook(this.config.teardown, 'teardown')
@@ -171,6 +191,50 @@ class Codecept {
         })
       }
     }
+
+    if (this.opts.shuffle) {
+      this.testFiles = shuffle(this.testFiles)
+    }
+
+    if (this.opts.shard) {
+      this.testFiles = this._applySharding(this.testFiles, this.opts.shard)
+    }
+  }
+
+  /**
+   * Apply sharding to test files based on shard configuration
+   *
+   * @param {Array<string>} testFiles - Array of test file paths
+   * @param {string} shardConfig - Shard configuration in format "index/total" (e.g., "1/4")
+   * @returns {Array<string>} - Filtered array of test files for this shard
+   */
+  _applySharding(testFiles, shardConfig) {
+    const shardMatch = shardConfig.match(/^(\d+)\/(\d+)$/)
+    if (!shardMatch) {
+      throw new Error('Invalid shard format. Expected format: "index/total" (e.g., "1/4")')
+    }
+
+    const shardIndex = parseInt(shardMatch[1], 10)
+    const shardTotal = parseInt(shardMatch[2], 10)
+
+    if (shardTotal < 1) {
+      throw new Error('Shard total must be at least 1')
+    }
+
+    if (shardIndex < 1 || shardIndex > shardTotal) {
+      throw new Error(`Shard index ${shardIndex} must be between 1 and ${shardTotal}`)
+    }
+
+    if (testFiles.length === 0) {
+      return testFiles
+    }
+
+    // Calculate which tests belong to this shard
+    const shardSize = Math.ceil(testFiles.length / shardTotal)
+    const startIndex = (shardIndex - 1) * shardSize
+    const endIndex = Math.min(startIndex + shardSize, testFiles.length)
+
+    return testFiles.slice(startIndex, endIndex)
   }
 
   /**
@@ -205,15 +269,21 @@ class Codecept {
         })
       }
 
-      const done = () => {
+      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(() => done())
+        mocha.run(async (failures) => await done(failures))
       } catch (e) {
         output.error(e.stack)
         reject(e)
@@ -221,6 +291,11 @@ class Codecept {
     })
   }
 
+  /**
+   * Returns the version string of CodeceptJS.
+   *
+   * @returns {string} The version string.
+   */
   static version() {
     return JSON.parse(readFileSync(`${__dirname}/../package.json`, 'utf8')).version
   }