{"id":10645,"library":"codeceptjs","title":"CodeceptJS","description":"CodeceptJS is an open-source, full-featured End-to-End (E2E) testing framework for Node.js, designed to make acceptance tests human-readable and maintainable. It currently offers a stable version 3.7.8, with version 4.x actively under development as Release Candidates, indicating a continuous release cadence with frequent updates and significant upcoming changes. A key differentiator is its synchronous test syntax, which allows test scenarios to be written linearly without explicit handling of promises or async/await, greatly simplifying test authoring from a user's perspective. It abstracts away the underlying browser automation drivers, supporting various helpers like Playwright, Puppeteer, WebDriver, TestCafe, and Appium, enabling testers to choose their preferred backend while keeping test scripts consistent. This framework focuses on behavioral-driven development (BDD) by providing a natural language API via the `I` object (or `actor`), making tests accessible even to non-technical stakeholders.","status":"active","version":"3.7.8","language":"javascript","source_language":"en","source_url":"https://github.com/Codeception/codeceptjs","tags":["javascript","acceptance","end2end","end 2 end","puppeteer","webdriver","testcafe","playwright","bdd","typescript"],"install":[{"cmd":"npm install codeceptjs","lang":"bash","label":"npm"},{"cmd":"yarn add codeceptjs","lang":"bash","label":"yarn"},{"cmd":"pnpm add codeceptjs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"One of several optional browser automation helpers required to execute web/mobile tests. Users install the specific helper they choose.","package":"playwright","optional":true},{"reason":"One of several optional browser automation helpers required to execute web/mobile tests. Users install the specific helper they choose.","package":"puppeteer","optional":true},{"reason":"One of several optional browser automation helpers (via WebDriver) required to execute web/mobile tests. Users install the specific helper they choose.","package":"selenium-webdriver","optional":true}],"imports":[{"note":"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.","wrong":"const { container } = require('codeceptjs')","symbol":"container","correct":"import { container } from 'codeceptjs'"},{"note":"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.","wrong":"const { event } = require('codeceptjs')","symbol":"event","correct":"import { event } from 'codeceptjs'"},{"note":"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.","symbol":"I","correct":"import type { I } from 'codeceptjs'"}],"quickstart":{"code":"import { config } from './codecept.conf';\n\n// codecept.conf.ts (or .js)\n// This file defines your CodeceptJS configuration, including helpers.\nexport const config: CodeceptJS.MainConfig = {\n  tests: './*_test.ts',\n  output: './output',\n  helpers: {\n    Playwright: {\n      url: 'http://localhost:8080', // Your application's base URL\n      show: true,                   // Show browser UI during tests\n      browser: 'chromium'           // Specify browser (chromium, firefox, webkit)\n    }\n  },\n  bootstrap: null,\n  mocha: {},\n  name: 'my-codeceptjs-tests',\n  plugins: {\n    pauseOnFail: {},\n    retryFailedStep: { enabled: true },\n    tryTo: { enabled: true },\n    screenshotOnFail: { enabled: true }\n  }\n};\n\n// my_first_test.ts (or .js)\n// This file contains your actual test scenarios.\n// To run:\n// 1. Make sure 'playwright' is installed: `npm i --save-dev playwright`\n// 2. Run CodeceptJS: `npx codeceptjs run --steps`\n\nFeature('User Authentication Flow');\n\nScenario('Verify successful login', async ({ I }) => {\n  I.amOnPage('/');\n  I.see('Welcome to My App'); // Assert initial text\n  I.click('Sign In');\n  I.seeCurrentUrlEquals('/login');\n  I.fillField('Username', 'testuser');\n  I.fillField('Password', 'correctpassword');\n  I.click('Login Button');\n  I.see('Welcome, testuser!'); // Assert post-login message\n  I.seeCurrentUrlEquals('/dashboard');\n}).tag('smoke');\n\nScenario('Verify invalid login attempt', async ({ I }) => {\n  I.amOnPage('/login');\n  I.fillField('Username', 'invaliduser');\n  I.fillField('Password', 'wrongpassword');\n  I.click('Login Button');\n  I.see('Invalid credentials'); // Assert error message\n  I.seeCurrentUrlEquals('/login');\n}).tag('negative');\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0-rc.1"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0-rc.8"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0"},{"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.","message":"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.","severity":"security","affected_versions":"<3.7.8"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Always execute CodeceptJS tests using the CodeceptJS CLI: `npx codeceptjs run` or `npx codeceptjs run --steps`.","cause":"Attempting to run a CodeceptJS test file directly via Node.js (e.g., `node my_test.js`) instead of through the CodeceptJS runner.","error":"ReferenceError: I is not defined"},{"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`).","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.","error":"Error: Helper 'Playwright' is not defined in config."},{"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).","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).","error":"MultipleElementsFound: Multiple elements found by selector \"//button\". Specify a more precise selector or use elementIndex option."}],"ecosystem":"npm"}