codeceptjs 4.0.0-beta.2 → 4.0.0-beta.20

package/bin/codecept.js

@@ -1,26 +1,10 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
-import { version } from '../lib/codecept.js';
-import * as outputLib from '../lib/output.js';
-import { printError } from '../lib/command/utils.js';
-import * as init from '../lib/command/init.js';
-import * as configMigrate from '../lib/command/configMigrate.js';
-import * as interactive from '../lib/command/interactive.js';
-import * as definitions from '../lib/command/definitions.js';
-import * as list from '../lib/command/list.js';
-import * as gherkinInit from '../lib/command/gherkin/init.js';
-import * as gherkinSteps from '../lib/command/gherkin/steps.js';
-import * as gherkinSnippets from '../lib/command/gherkin/snippets.js';
-import * as generate from '../lib/command/generate.js';
-import * as run from '../lib/command/run.js';
-import * as runWorkers from '../lib/command/run-workers.js';
-import * as runMultiple from '../lib/command/run-multiple.js';
-import { runRerun } from '../lib/command/run-rerun.js';
-import * as dryRun from '../lib/command/dryRun.js';
-import * as info from '../lib/command/info.js';
-import { heal } from "../lib/command/generate.js";
-
-const program = new Command();
+import { Command } from 'commander'
+const program = new Command()
+import Codecept from '../lib/codecept.js'
+import output from '../lib/output.js'
+const { print, error } = output
+import { printError } from '../lib/command/utils.js'
 
 const commandFlags = {
   ai: {
@@ -47,104 +31,124 @@ const commandFlags = {
     flag: '--steps',
     description: 'show step-by-step execution',
   },
-};
-
-const errorHandler = (fn) => async (...args) => {
-  try {
-    await fn.default(...args);
-  } catch (e) {
-    printError(e);
-    process.exitCode = 1;
+}
+
+const errorHandler =
+  fn =>
+  async (...args) => {
+    try {
+      await fn(...args)
+    } catch (e) {
+      printError(e)
+      process.exitCode = 1
+    }
   }
-};
+
+const dynamicImport = async modulePath => {
+  const module = await import(modulePath)
+  return module.default || module
+}
+
+const commandHandler = modulePath =>
+  errorHandler(async (...args) => {
+    const handler = await dynamicImport(modulePath)
+    return handler(...args)
+  })
+
+const commandHandlerWithProperty = (modulePath, property) =>
+  errorHandler(async (...args) => {
+    const module = await dynamicImport(modulePath)
+    return module[property](...args)
+  })
 
 if (process.versions.node && process.versions.node.split('.') && process.versions.node.split('.')[0] < 12) {
-  outputLib.output.output.error('NodeJS >= 12 is required to run.');
-  outputLib.print();
-  outputLib.print('Please upgrade your NodeJS engine');
-  outputLib.print(`Current NodeJS version: ${process.version}`);
-  process.exit(1);
+  error('NodeJS >= 12 is required to run.')
+  print()
+  print('Please upgrade your NodeJS engine')
+  print(`Current NodeJS version: ${process.version}`)
+  process.exit(1)
 }
 
-program.usage('<command> [options]');
-program.version(version());
+program.usage('<command> [options]')
+program.version(Codecept.version())
+
+program.command('init [path]').description('Creates dummy config in current dir or [path]').action(commandHandler('../lib/command/init.js'))
 
-program.command('init [path]')
-  .description('Creates dummy config in current dir or [path]')
-  .action(errorHandler(init));
+program
+  .command('check')
+  .option(commandFlags.config.flag, commandFlags.config.description)
+  .description('Checks configuration and environment before running tests')
+  .option('-t, --timeout [ms]', 'timeout for checks in ms, 50000 by default')
+  .action(commandHandler('../lib/command/check.js'))
 
-program.command('migrate [path]')
-  .description('Migrate json config to js config in current dir or [path]')
-  .action(errorHandler(configMigrate));
+program.command('migrate [path]').description('Migrate json config to js config in current dir or [path]').action(commandHandler('../lib/command/configMigrate.js'))
 
-program.command('shell [path]')
+program
+  .command('shell [path]')
   .alias('sh')
   .description('Interactive shell')
   .option(commandFlags.verbose.flag, commandFlags.verbose.description)
   .option(commandFlags.profile.flag, commandFlags.profile.description)
   .option(commandFlags.ai.flag, commandFlags.ai.description)
   .option(commandFlags.config.flag, commandFlags.config.description)
-  .action(errorHandler(interactive));
+  .action(commandHandler('../lib/command/interactive.js'))
 
-program.command('list [path]')
-  .alias('l')
-  .description('List all actions for I.')
-  .action(errorHandler(list));
+program.command('list [path]').alias('l').description('List all actions for I.').action(commandHandler('../lib/command/list.js'))
 
-program.command('def [path]')
+program
+  .command('def [path]')
   .description('Generates TypeScript definitions for all I actions.')
   .option(commandFlags.config.flag, commandFlags.config.description)
   .option('-o, --output [folder]', 'target folder to paste definitions')
-  .action(errorHandler(definitions));
+  .action(commandHandler('../lib/command/definitions.js'))
 
-program.command('gherkin:init [path]')
+program
+  .command('gherkin:init [path]')
   .alias('bdd:init')
   .description('Prepare CodeceptJS to run feature files.')
   .option(commandFlags.config.flag, commandFlags.config.description)
-  .action(errorHandler(gherkinInit));
+  .action(commandHandler('../lib/command/gherkin/init.js'))
 
-program.command('gherkin:steps [path]')
+program
+  .command('gherkin:steps [path]')
   .alias('bdd:steps')
   .description('Prints all defined gherkin steps.')
   .option(commandFlags.config.flag, commandFlags.config.description)
-  .action(errorHandler(gherkinSteps));
+  .action(commandHandler('../lib/command/gherkin/steps.js'))
 
-program.command('gherkin:snippets [path]')
+program
+  .command('gherkin:snippets [path]')
   .alias('bdd:snippets')
   .description('Generate step definitions from steps.')
   .option('--dry-run', "don't save snippets to file")
   .option(commandFlags.config.flag, commandFlags.config.description)
   .option('--feature [file]', 'feature files(s) to scan')
   .option('--path [file]', 'file in which to place the new snippets')
-  .action(errorHandler(gherkinSnippets));
+  .action(commandHandler('../lib/command/gherkin/snippets.js'))
 
-program.command('generate:test [path]')
-  .alias('gt')
-  .description('Generates an empty test')
-  .action(errorHandler(generate.test));
+program.command('generate:test [path]').alias('gt').description('Generates an empty test').action(commandHandlerWithProperty('../lib/command/generate.js', 'test'))
 
-program.command('generate:pageobject [path]')
-  .alias('gpo')
-  .description('Generates an empty page object')
-  .action(errorHandler(generate.pageObject));
+program.command('generate:pageobject [path]').alias('gpo').description('Generates an empty page object').action(commandHandlerWithProperty('../lib/command/generate.js', 'pageObject'))
 
-program.command('generate:object [path]')
+program
+  .command('generate:object [path]')
   .alias('go')
   .option('--type, -t [kind]', 'type of object to be created')
   .description('Generates an empty support object (page/step/fragment)')
-  .action(errorHandler(generate.pageObject));
+  .action(commandHandlerWithProperty('../lib/command/generate.js', 'pageObject'))
+
+program.command('generate:helper [path]').alias('gh').description('Generates a new helper').action(commandHandlerWithProperty('../lib/command/generate.js', 'helper'))
 
-program.command('generate:helper [path]')
-  .alias('gh')
-  .description('Generates a new helper')
-  .action(errorHandler(generate.helper));
+program.command('generate:heal [path]').alias('gr').description('Generates basic heal recipes').action(commandHandlerWithProperty('../lib/command/generate.js', 'heal'))
 
-program.command('generate:heal [path]')
-  .alias('gr')
-  .description('Generates basic heal recipes')
-  .action(errorHandler(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]')
+program
+  .command('run [test]')
   .description('Executes tests')
 
   // codecept-only options
@@ -159,6 +163,8 @@ program.command('run [test]')
   .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')
@@ -180,15 +186,17 @@ program.command('run [test]')
   .option('--recursive', 'include sub directories')
   .option('--trace', 'trace function calls')
   .option('--child <string>', 'option for child processes')
-  .action(errorHandler(run));
+  .action(commandHandler('../lib/command/run.js'))
 
-program.command('run-workers <workers> [selectedRuns...]')
+program
+  .command('run-workers <workers> [selectedRuns...]')
   .description('Executes tests in workers')
   .option(commandFlags.config.flag, commandFlags.config.description)
   .option('-g, --grep <pattern>', 'only run tests matching <pattern>')
   .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')
@@ -198,9 +206,10 @@ program.command('run-workers <workers> [selectedRuns...]')
   .option('-p, --plugins <k=v,k2=v2,...>', 'enable plugins, comma-separated')
   .option('-O, --reporter-options <k=v,k2=v2,...>', 'reporter-specific options')
   .option('-R, --reporter <name>', 'specify the reporter to use')
-  .action(errorHandler(runWorkers));
+  .action(commandHandler('../lib/command/run-workers.js'))
 
-program.command('run-multiple [suites...]')
+program
+  .command('run-multiple [suites...]')
   .description('Executes tests multiple')
   .option(commandFlags.config.flag, commandFlags.config.description)
   .option(commandFlags.profile.flag, commandFlags.profile.description)
@@ -223,14 +232,12 @@ program.command('run-multiple [suites...]')
   // mocha options
   .option('--colors', 'force enabling of colors')
 
-  .action(errorHandler(runMultiple));
+  .action(commandHandler('../lib/command/run-multiple.js'))
 
-program.command('info [path]')
-  .description('Print debugging information concerning the local environment')
-  .option('-c, --config', 'your config file path')
-  .action(errorHandler(info));
+program.command('info [path]').description('Print debugging information concerning the local environment').option('-c, --config', 'your config file path').action(commandHandler('../lib/command/info.js'))
 
-program.command('dry-run [test]')
+program
+  .command('dry-run [test]')
   .description('Prints step-by-step scenario for a test without actually running it')
   .option('-p, --plugins <k=v,k2=v2,...>', 'enable plugins, comma-separated')
   .option('--bootstrap', 'enable bootstrap & teardown scripts for dry-run')
@@ -244,9 +251,10 @@ program.command('dry-run [test]')
   .option(commandFlags.steps.flag, commandFlags.steps.description)
   .option(commandFlags.verbose.flag, commandFlags.verbose.description)
   .option(commandFlags.debug.flag, commandFlags.debug.description)
-  .action(errorHandler(dryRun));
+  .action(commandHandler('../lib/command/dryRun.js'))
 
-program.command('run-rerun [test]')
+program
+  .command('run-rerun [test]')
   .description('Executes tests in more than one test suite run')
 
   // codecept-only options
@@ -281,15 +289,18 @@ program.command('run-rerun [test]')
   .option('--trace', 'trace function calls')
   .option('--child <string>', 'option for child processes')
 
-  .action(runRerun);
+  .action(async (...args) => {
+    const runRerun = await dynamicImport('../lib/command/run-rerun.js')
+    return runRerun(...args)
+  })
 
-program.on('command:*', (cmd) => {
-  console.log(`\nUnknown command ${cmd}\n`);
-  program.outputHelp();
-});
+program.on('command:*', cmd => {
+  console.log(`\nUnknown command ${cmd}\n`)
+  program.outputHelp()
+})
 
 if (process.argv.length <= 2) {
-  program.outputHelp();
+  program.outputHelp()
 } else {
-  program.parse(process.argv);
+  program.parse(process.argv)
 }

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/clearCookie.mustache

@@ -3,7 +3,7 @@ if none provided clears all cookies.
 
 ```js
 I.clearCookie();
-I.clearCookie('test'); // Playwright currently doesn't support clear a particular cookie name
+I.clearCookie('test');
 ```
 
 @param {?string} [cookie=null] (optional, `null` by default) cookie name

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/actor.js

@@ -1,16 +1,18 @@
-import { Step, MetaStep } from './step.js';
-import container from './container.js';
-import { methodsOfObject } from './utils.js';
-import recorder from './recorder.js';
-import * as event from './event.js';
-import { store } from './store.js';
-import * as output from './output.js';
+import Step, { MetaStep } from './step.js'
+import recordStep from './step/record.js'
+import retryStep from './step/retry.js'
+import { methodsOfObject } from './utils.js'
+import { TIMEOUT_ORDER } from './timeout.js'
+import event from './event.js'
+import store from './store.js'
+import output from './output.js'
+import Container from './container.js'
 
 /**
  * @interface
  * @alias ActorStatic
  */
-export class Actor {
+class Actor {
   /**
    * Print the comment on log. Also, adding a step in the `Test.steps` object
    * @param {string} msg
@@ -20,13 +22,13 @@ export class Actor {
    * ⚠️ returns a promise which is synchronized internally by recorder
    */
   async say(msg, color = 'cyan') {
-    const step = new Step('say', 'say');
-    step.status = 'passed';
+    const step = new Step('say', 'say')
+    step.status = 'passed'
     return recordStep(step, [msg]).then(() => {
       // this is backward compatibility as this event may be used somewhere
-      event.emit(event.step.comment, msg);
-      output.say(msg, `${color}`);
-    });
+      event.emit(event.step.comment, msg)
+      output.say(msg, `${color}`)
+    })
   }
 
   /**
@@ -37,14 +39,16 @@ export class Actor {
    * @inner
    */
   limitTime(timeout) {
-    if (!store.timeouts) return this;
+    if (!store.timeouts) return this
 
-    event.dispatcher.prependOnceListener(event.step.before, (step) => {
-      output.output.log(`Timeout to ${step}: ${timeout}s`);
-      step.setTimeout(timeout * 1000, Step.TIMEOUT_ORDER.codeLimitTime);
-    });
+    console.log('I.limitTime() is deprecated, use step.timeout() instead')
 
-    return this;
+    event.dispatcher.prependOnceListener(event.step.before, step => {
+      output.log(`Timeout to ${step}: ${timeout}s`)
+      step.setTimeout(timeout * 1000, TIMEOUT_ORDER.codeLimitTime)
+    })
+
+    return this
   }
 
   /**
@@ -54,11 +58,9 @@ export class Actor {
    * @inner
    */
   retry(opts) {
-    if (opts === undefined) opts = 1;
-    recorder.retry(opts);
-    // remove retry once the step passed
-    recorder.add(() => event.dispatcher.once(event.step.finished, () => recorder.retries.pop()));
-    return this;
+    console.log('I.retry() is deprecated, use step.retry() instead')
+    retryStep(opts)
+    return this
   }
 }
 
@@ -68,94 +70,60 @@ export class Actor {
  * Wraps helper methods into promises.
  * @ignore
  */
-// eslint-disable-next-line import/prefer-default-export
-export function actor(obj = {}) {
-  if (!store.actor) {
-    store.actor = new Actor();
-  }
-  const actor = store.actor;
-
-  const translation = container.translation();
-
-  if (Object.keys(obj).length > 0) {
-    Object.keys(obj)
-      .forEach(action => {
-        const actionAlias = translation.actionAliasFor(action);
-
-        const currentMethod = obj[action];
-        const ms = new MetaStep('I', action);
-        if (translation.loaded) {
-          ms.name = actionAlias;
-          ms.actor = translation.I;
-        }
-        ms.setContext(actor);
-        actor[action] = actor[actionAlias] = ms.run.bind(ms, currentMethod);
-      });
+export default function (obj = {}, container) {
+  // Use global container if none provided
+  if (!container) {
+    container = Container
   }
+  
+  const actor = container.actor() || new Actor()
 
-  const helpers = container.helpers();
+  // load all helpers once container initialized
+  container.started(() => {
+    const translation = container.translation()
+    const helpers = container.helpers()
 
-  // add methods from enabled helpers
-  Object.values(helpers)
-    .forEach((helper) => {
+    // add methods from enabled helpers
+    Object.values(helpers).forEach(helper => {
       methodsOfObject(helper, 'Helper')
         .filter(method => method !== 'constructor' && method[0] !== '_')
-        .forEach((action) => {
-          const actionAlias = translation.actionAliasFor(action);
+        .forEach(action => {
+          const actionAlias = translation.actionAliasFor(action)
           if (!actor[action]) {
             actor[action] = actor[actionAlias] = function () {
-              const step = new Step(helper, action);
+              const step = new Step(helper, action)
               if (translation.loaded) {
-                step.name = actionAlias;
-                step.actor = translation.I;
+                step.name = actionAlias
+                step.actor = translation.I
               }
               // add methods to promise chain
-              return recordStep(step, Array.from(arguments));
-            };
+              return recordStep(step, Array.from(arguments))
+            }
           }
-        });
-    });
-
-  return actor;
-}
-
-export function recordStep(step, args) {
-  step.status = 'queued';
-  step.setArguments(args);
-
-  // run async before step hooks
-  event.emit(event.step.before, step);
-
-  const task = `${step.name}: ${step.humanizeArgs()}`;
-  let val;
-
-  // run step inside promise
-  recorder.add(task, () => {
-    if (!step.startTime) { // step can be retries
-      event.emit(event.step.started, step);
-      step.startTime = Date.now();
-    }
-    return val = step.run(...args);
-  }, false, undefined, step.getTimeout());
-
-  event.emit(event.step.after, step);
-
-  recorder.add('step passed', () => {
-    step.endTime = Date.now();
-    event.emit(event.step.passed, step, val);
-    event.emit(event.step.finished, step);
-  });
-
-  recorder.catchWithoutStop((err) => {
-    step.status = 'failed';
-    step.endTime = Date.now();
-    event.emit(event.step.failed, step);
-    event.emit(event.step.finished, step);
-    throw err;
-  });
-
-  recorder.add('return result', () => val);
-  // run async after step hooks
-
-  return recorder.promise();
+        })
+    })
+
+    // add translated custom steps from actor
+    Object.keys(obj).forEach(key => {
+      const actionAlias = translation.actionAliasFor(key)
+      if (!actor[actionAlias]) {
+        actor[actionAlias] = actor[key]
+      }
+    })
+
+    container.append({
+      support: {
+        I: actor,
+      },
+    })
+  })
+  // store.actor = actor;
+  // add custom steps from actor
+  Object.keys(obj).forEach(key => {
+    const ms = new MetaStep('I', key)
+    ms.setContext(actor)
+    actor[key] = ms.run.bind(ms, obj[key])
+  })
+
+  return actor
 }