CodeceptJS

Common errors

• ReferenceError: I is not defined

  cause Attempting to run a CodeceptJS test file directly via Node.js (e.g., `node my_test.js`) instead of through the CodeceptJS runner.
  fix Always execute CodeceptJS tests using the CodeceptJS CLI: `npx codeceptjs run` or `npx codeceptjs run --steps`.

• Error: Helper 'Playwright' is not defined in config.

  cause The specified helper (e.g., Playwright, Puppeteer, WebDriver) is not correctly configured in your `codecept.conf.js` (or `.ts`) file, or the corresponding npm package is not installed.
  fix Ensure your `codecept.conf.js` has an entry in the `helpers` section for the desired helper (e.g., `Playwright: { url: '...', browser: 'chromium' }`) and that the helper package is installed (e.g., `npm install --save-dev playwright`).

• MultipleElementsFound: Multiple elements found by selector "//button". Specify a more precise selector or use elementIndex option.

  cause A selector used in an `I` action (e.g., `I.click('//button')`) matched more than one element on the page, and the helper is in strict mode (default in v4.x).
  fix Refine your selector to be more specific (e.g., `I.click('//button[contains(., "Submit")]')` or `I.click({ css: 'div.form button.submit' })`), or use the `elementIndex` option if you intentionally want to target a specific one among multiple matches (e.g., `I.click('//button', null, 1)` to click the second matching button).

Warnings

• breaking CodeceptJS v4.x introduces significant internal refactorings, including the elimination of internal globals in favor of a store singleton, which can break existing plugins or custom code relying on these internals. The 'auth' plugin's `loginAs` injection method is known to be broken in v4.x. Additionally, the built-in HTML reporter has been removed, recommending `@testomatio/reporter` as an alternative.
  Fix: Review the v4.x changelog and migration guide carefully. Update custom plugins and code to use the new store singleton or recommended APIs. Replace the built-in HTML reporter with `@testomatio/reporter` or another compatible reporter. Test thoroughly when upgrading.
• breaking Version 4.x introduces 'strict mode' for all helpers by default, which improves error reporting but can lead to new 'MultipleElementsFound' errors where previously the first matching element might have been implicitly chosen. Furthermore, there's a fix for `cheerio` ESM import issues in v4.x, indicating a broader shift towards ESM compatibility that might require adjustments in user environments or plugins.
  Fix: For 'MultipleElementsFound' errors, use more specific selectors or the `elementIndex` option to target the intended element. Ensure your project and any custom modules are configured correctly for ESM, especially if using Node.js v16+ and encountering import errors.
• gotcha CodeceptJS tests are designed to be synchronous in their syntax, which abstracts away promises and `async/await` for typical `I` actions. While this simplifies test writing, users accustomed to explicit asynchronous patterns in JavaScript might mistakenly add `async/await` to `I` actions, which is generally not needed and can sometimes interfere with CodeceptJS's internal promise chain management, particularly when dealing with helper method returns.
  Fix: Avoid using `await` directly before `I` methods unless you are explicitly awaiting a value returned by an `I` method that is documented to return a promise, or within custom helper methods. Let CodeceptJS manage the asynchronous flow for standard `I` actions.
• security Several security issues were fixed in version 3.7.8. Running older versions, particularly prior to 3.7.8, could expose your test environment or application under test to known vulnerabilities. It is crucial to keep CodeceptJS and its dependencies updated.
  Fix: Upgrade to the latest stable version of CodeceptJS (3.7.8 or newer) to patch known security vulnerabilities. Regularly update all project dependencies to mitigate supply chain risks.

Install

• npm install codeceptjs npm
• yarn add codeceptjs yarn
• pnpm add codeceptjs pnpm

Imports

• container
  wrong:

  const { container } = require('codeceptjs')

  correct:

  import { container } from 'codeceptjs'

  Used for programmatic access to CodeceptJS core, such as retrieving configured helpers or support objects, typically within custom helpers or plugins. Supports both ESM (Node 16+) and CJS (older Node versions) in v3.x, but v4.x leans heavily towards ESM.
• event
  wrong:

  const { event } = require('codeceptjs')

  correct:

  import { event } from 'codeceptjs'

  Provides an EventEmitter instance for hooking into various test lifecycle events (e.g., `test.before`, `test.failed`), crucial for plugin development. Supports both ESM and CJS in v3.x, with v4.x preferring ESM.
• I

  import type { I } from 'codeceptjs'

  This is a TypeScript type import for the `I` object (or `actor`), which contains all helper methods. The `I` object itself is globally provided to scenario functions at runtime, so it's not imported as a value. Provides type safety for custom steps and page objects.

Quickstart

Demonstrates setting up a basic CodeceptJS configuration with Playwright and writing two end-to-end scenarios for user authentication, including successful login and an invalid attempt.

import { config } from './codecept.conf';

// codecept.conf.ts (or .js)
// This file defines your CodeceptJS configuration, including helpers.
export const config: CodeceptJS.MainConfig = {
  tests: './*_test.ts',
  output: './output',
  helpers: {
    Playwright: {
      url: 'http://localhost:8080', // Your application's base URL
      show: true,                   // Show browser UI during tests
      browser: 'chromium'           // Specify browser (chromium, firefox, webkit)
    }
  },
  bootstrap: null,
  mocha: {},
  name: 'my-codeceptjs-tests',
  plugins: {
    pauseOnFail: {},
    retryFailedStep: { enabled: true },
    tryTo: { enabled: true },
    screenshotOnFail: { enabled: true }
  }
};

// my_first_test.ts (or .js)
// This file contains your actual test scenarios.
// To run:
// 1. Make sure 'playwright' is installed: `npm i --save-dev playwright`
// 2. Run CodeceptJS: `npx codeceptjs run --steps`

Feature('User Authentication Flow');

Scenario('Verify successful login', async ({ I }) => {
  I.amOnPage('/');
  I.see('Welcome to My App'); // Assert initial text
  I.click('Sign In');
  I.seeCurrentUrlEquals('/login');
  I.fillField('Username', 'testuser');
  I.fillField('Password', 'correctpassword');
  I.click('Login Button');
  I.see('Welcome, testuser!'); // Assert post-login message
  I.seeCurrentUrlEquals('/dashboard');
}).tag('smoke');

Scenario('Verify invalid login attempt', async ({ I }) => {
  I.amOnPage('/login');
  I.fillField('Username', 'invaliduser');
  I.fillField('Password', 'wrongpassword');
  I.click('Login Button');
  I.see('Invalid credentials'); // Assert error message
  I.seeCurrentUrlEquals('/login');
}).tag('negative');