CodeceptJS Fundamentals

Two jobs: teach the concepts you need to read CodeceptJS code without making things up, and report what this project has configured. Do both, in order.

Concepts

Module system

CodeceptJS 4 is ESM and TypeScript only. Tests, configs, page objects, and helpers use import/export; package.json must have "type": "module" — if it isn't there yet, add it before doing anything else (without it, every .js file is parsed as CommonJS and imports fail). TypeScript is first-class: name the config codecept.conf.ts, add a loader entry like require: ['tsx/cjs'] (or ts-node/register), and write tests as .ts files.

If the project is on CodeceptJS 3.x or still uses CommonJS (require() / module.exports, no "type": "module", removed helpers/plugins like autoLogin or Nightmare), stop here and run the migrate-codeceptjs-4 skill — it walks the full upgrade path (Node bump, ESM conversion, helper/plugin replacements, AI/Zod/effects API changes, noGlobals, dependency bumps, verify). Don't try to half-fix individual files; the migration is a whole-project change.

Configuration

codecept.conf.{js,ts,mjs,cjs} at the repo root. Top-level keys: helpers, plugins, include, ai, bootstrap/teardown, tests, output, timeout. TypeScript configs declare a loader in require: [...] (tsx/cjs, ts-node/register, ts-node/esm). Multiple env-specific files (codecept.ci.conf.js, …) are selected via --config <file>. The @codeceptjs/configure package mutates the resolved config at load time (setHeadlessWhen, setBrowser, setCommonPlugins, setWindowSize) — static fields can lie until you grep for that import.

I and helpers

I is the actor. Every I.<method>(...) is dispatched to whichever active helper provides that method. Built-in helpers contribute different surfaces: web (Playwright, Puppeteer, WebDriver — overlapping core actions plus helper-specific extras), API (REST, GraphQL), AI, mobile (Appium), utility (FileSystem). The active helpers are exactly the keys under helpers in config.