codeceptjs 3.7.3 → 3.7.5-beta.1

package/README.md

@@ -64,6 +64,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 +235,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

@@ -164,6 +164,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')
@@ -195,6 +197,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,53 @@
+#!/usr/bin/env node
+
+/**
+ * Standalone test server script to replace json-server
+ */
+
+const path = require('path')
+const TestServer = require('../lib/test-server')
+
+// 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'
+
+// 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.startsWith('-')) {
+    dbFile = path.resolve(arg)
+  }
+}
+
+// Create and start server
+const server = new TestServer({ port, host, dbFile })
+
+console.log(`Starting test server with db file: ${dbFile}`)
+
+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/lib/codecept.js

@@ -1,5 +1,6 @@
 const { existsSync, readFileSync } = require('fs')
 const { globSync } = require('glob')
+const shuffle = require('lodash.shuffle')
 const fsPath = require('path')
 const { resolve } = require('path')
 
@@ -110,6 +111,7 @@ class Codecept {
     runHook(require('./listener/helpers'))
     runHook(require('./listener/globalTimeout'))
     runHook(require('./listener/globalRetry'))
+    runHook(require('./listener/retryEnhancer'))
     runHook(require('./listener/exit'))
     runHook(require('./listener/emptyRun'))
 
@@ -180,6 +182,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)
   }
 
   /**

package/lib/command/init.js

@@ -18,6 +18,11 @@ const defaultConfig = {
   output: '',
   helpers: {},
   include: {},
+  plugins: {
+    htmlReporter: {
+      enabled: true,
+    },
+  },
 }
 
 const helpers = ['Playwright', 'WebDriver', 'Puppeteer', 'REST', 'GraphQL', 'Appium', 'TestCafe']

package/lib/command/run-workers.js

@@ -10,7 +10,22 @@ module.exports = async function (workerCount, selectedRuns, options) {
 
   const { config: testConfig, override = '' } = options
   const overrideConfigs = tryOrDefault(() => JSON.parse(override), {})
-  const by = options.suites ? 'suite' : 'test'
+
+  // Determine test split strategy
+  let by = 'test' // default
+  if (options.by) {
+    // Explicit --by option takes precedence
+    by = options.by
+  } else if (options.suites) {
+    // Legacy --suites option
+    by = 'suite'
+  }
+
+  // Validate the by option
+  const validStrategies = ['test', 'suite', 'pool']
+  if (!validStrategies.includes(by)) {
+    throw new Error(`Invalid --by strategy: ${by}. Valid options are: ${validStrategies.join(', ')}`)
+  }
   delete options.parent
   const config = {
     by,

package/lib/command/workers/runTests.js

@@ -20,7 +20,7 @@ const stderr = ''
 // Requiring of Codecept need to be after tty.getWindowSize is available.
 const Codecept = require(process.env.CODECEPT_CLASS_PATH || '../../codecept')
 
-const { options, tests, testRoot, workerIndex } = workerData
+const { options, tests, testRoot, workerIndex, poolMode } = workerData
 
 // hide worker output
 if (!options.debug && !options.verbose)
@@ -39,15 +39,26 @@ const codecept = new Codecept(config, options)
 codecept.init(testRoot)
 codecept.loadTests()
 const mocha = container.mocha()
-filterTests()
+
+if (poolMode) {
+  // In pool mode, don't filter tests upfront - wait for assignments
+  // We'll reload test files fresh for each test request
+} else {
+  // Legacy mode - filter tests upfront
+  filterTests()
+}
 
 // run tests
 ;(async function () {
-  if (mocha.suite.total()) {
+  if (poolMode) {
+    await runPoolTests()
+  } else if (mocha.suite.total()) {
     await runTests()
   }
 })()
 
+let globalStats = { passes: 0, failures: 0, tests: 0, pending: 0, failedHooks: 0 }
+
 async function runTests() {
   try {
     await codecept.bootstrap()
@@ -64,6 +75,192 @@ async function runTests() {
   }
 }
 
+async function runPoolTests() {
+  try {
+    await codecept.bootstrap()
+  } catch (err) {
+    throw new Error(`Error while running bootstrap file :${err}`)
+  }
+
+  initializeListeners()
+  disablePause()
+
+  // Accumulate results across all tests in pool mode
+  let consolidatedStats = { passes: 0, failures: 0, tests: 0, pending: 0, failedHooks: 0 }
+  let allTests = []
+  let allFailures = []
+  let previousStats = { passes: 0, failures: 0, tests: 0, pending: 0, failedHooks: 0 }
+
+  // Keep requesting tests until no more available
+  while (true) {
+    // Request a test assignment
+    sendToParentThread({ type: 'REQUEST_TEST', workerIndex })
+
+    const testResult = await new Promise((resolve, reject) => {
+      // Set up pool mode message handler
+      const messageHandler = async eventData => {
+        if (eventData.type === 'TEST_ASSIGNED') {
+          const testUid = eventData.test
+
+          try {
+            // In pool mode, we need to create a fresh Mocha instance for each test
+            // because Mocha instances become disposed after running tests
+            container.createMocha() // Create fresh Mocha instance
+            filterTestById(testUid)
+            const mocha = container.mocha()
+
+            if (mocha.suite.total() > 0) {
+              // Run the test and complete
+              await codecept.run()
+
+              // Get the results from this specific test run
+              const result = container.result()
+              const currentStats = result.stats || {}
+
+              // Calculate the difference from previous accumulated stats
+              const newPasses = Math.max(0, (currentStats.passes || 0) - previousStats.passes)
+              const newFailures = Math.max(0, (currentStats.failures || 0) - previousStats.failures)
+              const newTests = Math.max(0, (currentStats.tests || 0) - previousStats.tests)
+              const newPending = Math.max(0, (currentStats.pending || 0) - previousStats.pending)
+              const newFailedHooks = Math.max(0, (currentStats.failedHooks || 0) - previousStats.failedHooks)
+
+              // Add only the new results
+              consolidatedStats.passes += newPasses
+              consolidatedStats.failures += newFailures
+              consolidatedStats.tests += newTests
+              consolidatedStats.pending += newPending
+              consolidatedStats.failedHooks += newFailedHooks
+
+              // Update previous stats for next comparison
+              previousStats = { ...currentStats }
+
+              // Add new failures to consolidated collections
+              if (result.failures && result.failures.length > allFailures.length) {
+                const newFailures = result.failures.slice(allFailures.length)
+                allFailures.push(...newFailures)
+              }
+            }
+
+            // Signal test completed and request next
+            parentPort?.off('message', messageHandler)
+            resolve('TEST_COMPLETED')
+          } catch (err) {
+            parentPort?.off('message', messageHandler)
+            reject(err)
+          }
+        } else if (eventData.type === 'NO_MORE_TESTS') {
+          // No tests available, exit worker
+          parentPort?.off('message', messageHandler)
+          resolve('NO_MORE_TESTS')
+        } else {
+          // Handle other message types (support messages, etc.)
+          container.append({ support: eventData.data })
+        }
+      }
+
+      parentPort?.on('message', messageHandler)
+    })
+
+    // Exit if no more tests
+    if (testResult === 'NO_MORE_TESTS') {
+      break
+    }
+  }
+
+  try {
+    await codecept.teardown()
+  } catch (err) {
+    // Log teardown errors but don't fail
+    console.error('Teardown error:', err)
+  }
+
+  // Send final consolidated results for the entire worker
+  const finalResult = {
+    hasFailed: consolidatedStats.failures > 0,
+    stats: consolidatedStats,
+    duration: 0, // Pool mode doesn't track duration per worker
+    tests: [], // Keep tests empty to avoid serialization issues - stats are sufficient
+    failures: allFailures, // Include all failures for error reporting
+  }
+
+  sendToParentThread({ event: event.all.after, workerIndex, data: finalResult })
+  sendToParentThread({ event: event.all.result, workerIndex, data: finalResult })
+
+  // Add longer delay to ensure messages are delivered before closing
+  await new Promise(resolve => setTimeout(resolve, 100))
+
+  // Close worker thread when pool mode is complete
+  parentPort?.close()
+}
+
+function filterTestById(testUid) {
+  // Reload test files fresh for each test in pool mode
+  const files = codecept.testFiles
+
+  // Get the existing mocha instance
+  const mocha = container.mocha()
+
+  // Clear suites and tests but preserve other mocha settings
+  mocha.suite.suites = []
+  mocha.suite.tests = []
+
+  // Clear require cache for test files to ensure fresh loading
+  files.forEach(file => {
+    delete require.cache[require.resolve(file)]
+  })
+
+  // Set files and load them
+  mocha.files = files
+  mocha.loadFiles()
+
+  // Now filter to only the target test - use a more robust approach
+  let foundTest = false
+  for (const suite of mocha.suite.suites) {
+    const originalTests = [...suite.tests]
+    suite.tests = []
+
+    for (const test of originalTests) {
+      if (test.uid === testUid) {
+        suite.tests.push(test)
+        foundTest = true
+        break // Only add one matching test
+      }
+    }
+
+    // If no tests found in this suite, remove it
+    if (suite.tests.length === 0) {
+      suite.parent.suites = suite.parent.suites.filter(s => s !== suite)
+    }
+  }
+
+  // Filter out empty suites from the root
+  mocha.suite.suites = mocha.suite.suites.filter(suite => suite.tests.length > 0)
+
+  if (!foundTest) {
+    // If testUid doesn't match, maybe it's a simple test name - try fallback
+    mocha.suite.suites = []
+    mocha.suite.tests = []
+    mocha.loadFiles()
+
+    // Try matching by title
+    for (const suite of mocha.suite.suites) {
+      const originalTests = [...suite.tests]
+      suite.tests = []
+
+      for (const test of originalTests) {
+        if (test.title === testUid || test.fullTitle() === testUid || test.uid === testUid) {
+          suite.tests.push(test)
+          foundTest = true
+          break
+        }
+      }
+    }
+
+    // Clean up empty suites again
+    mocha.suite.suites = mocha.suite.suites.filter(suite => suite.tests.length > 0)
+  }
+}
+
 function filterTests() {
   const files = codecept.testFiles
   mocha.files = files
@@ -102,14 +299,20 @@ function initializeListeners() {
   event.dispatcher.on(event.hook.passed, hook => sendToParentThread({ event: event.hook.passed, workerIndex, data: hook.simplify() }))
   event.dispatcher.on(event.hook.finished, hook => sendToParentThread({ event: event.hook.finished, workerIndex, data: hook.simplify() }))
 
-  event.dispatcher.once(event.all.after, () => {
-    sendToParentThread({ event: event.all.after, workerIndex, data: container.result().simplify() })
-  })
-  // all
-  event.dispatcher.once(event.all.result, () => {
-    sendToParentThread({ event: event.all.result, workerIndex, data: container.result().simplify() })
-    parentPort?.close()
-  })
+  if (!poolMode) {
+    // In regular mode, close worker after all tests are complete
+    event.dispatcher.once(event.all.after, () => {
+      sendToParentThread({ event: event.all.after, workerIndex, data: container.result().simplify() })
+    })
+    // all
+    event.dispatcher.once(event.all.result, () => {
+      sendToParentThread({ event: event.all.result, workerIndex, data: container.result().simplify() })
+      parentPort?.close()
+    })
+  } else {
+    // In pool mode, don't send result events for individual tests
+    // Results will be sent once when the worker completes all tests
+  }
 }
 
 function disablePause() {
@@ -121,7 +324,10 @@ function sendToParentThread(data) {
 }
 
 function listenToParentThread() {
-  parentPort?.on('message', eventData => {
-    container.append({ support: eventData.data })
-  })
+  if (!poolMode) {
+    parentPort?.on('message', eventData => {
+      container.append({ support: eventData.data })
+    })
+  }
+  // In pool mode, message handling is done in runPoolTests()
 }

package/lib/container.js

@@ -28,6 +28,7 @@ let container = {
   translation: {},
   /** @type {Result | null} */
   result: null,
+  sharedKeys: new Set() // Track keys shared via share() function
 }
 
 /**
@@ -174,6 +175,7 @@ class Container {
     container.translation = loadTranslation()
     container.proxySupport = createSupportObjects(newSupport)
     container.plugins = newPlugins
+    container.sharedKeys = new Set() // Clear shared keys
     asyncHelperPromise = Promise.resolve()
     store.actor = null
     debug('container cleared')
@@ -197,7 +199,13 @@ class Container {
    * @param {Object} options - set {local: true} to not share among workers
    */
   static share(data, options = {}) {
-    Container.append({ support: data })
+    // Instead of using append which replaces the entire container,
+    // directly update the support object to maintain proxy references
+    Object.assign(container.support, data)
+    
+    // Track which keys were explicitly shared
+    Object.keys(data).forEach(key => container.sharedKeys.add(key))
+    
     if (!options.local) {
       WorkerStorage.share(data)
     }
@@ -396,10 +404,11 @@ function createSupportObjects(config) {
     {},
     {
       has(target, key) {
-        return keys.includes(key)
+        return keys.includes(key) || container.sharedKeys.has(key)
       },
       ownKeys() {
-        return keys
+        // Return both original config keys and explicitly shared keys
+        return [...new Set([...keys, ...container.sharedKeys])]
       },
       getOwnPropertyDescriptor(target, prop) {
         return {
@@ -409,6 +418,10 @@ function createSupportObjects(config) {
         }
       },
       get(target, key) {
+        // First check if this is an explicitly shared property
+        if (container.sharedKeys.has(key) && key in container.support) {
+          return container.support[key]
+        }
         return lazyLoad(key)
       },
     },