CodeceptJS: a scenario runner on top of Playwright, Puppeteer and WebDriver

The problem CodeceptJS solves for NodeJS E2E suites

Every browser automation library in Node has its own vocabulary. Playwright exposes page and locator objects, Puppeteer exposes page methods, webdriverio exposes a browser object, and Appium adds mobile-specific session handling on top. A test suite that needs two of those, say web plus a React Native app, ends up with two idioms and two sets of helpers.

CodeceptJS puts a scenario runner in front of them. The README describes the framework as abstracting browser interaction into "simple steps that are written from a user's perspective", and the example it gives is three lines long: a Feature, a Scenario, and two calls on an object named I. The audience is anyone writing acceptance tests who wants the test file to describe intent rather than protocol. The README also states the tests are synchronous and that you do not need to care about callbacks or promises, which is a deliberate simplification: the runner sequences the async work underneath.

It is a successor to Codeception, the PHP full-stack testing framework, and the README says so directly. If you have used Codeception, the mental model transfers. If you have not, the value proposition is narrower: one syntax, several backends, and a set of CLI generators for tests, page objects and step objects.

How the I object and helpers actually fit together

The I object is not a browser. It is a facade assembled from the helpers you enable in the config. The README lists Playwright, Puppeteer, WebDriver, Obscura, Appium and Detox as the current helpers, and describes them as the modules that "provide actions to I". So when a test calls I.amOnPage('/'), the call is dispatched to whichever helper is configured, and that helper translates it into the driver's own call.

The README is explicit that CodeceptJS is backend API agnostic: "We don't know which WebDriver implementation is running this test." That is the architectural claim, and it explains the trade-off. Your test file stays portable across drivers, but the exact behaviour of a step is defined by the helper's documentation, not by the driver's. When you need something the helper does not expose, you drop to the underlying library inside a custom step or helper, and at that point you are reading two sets of docs.

The runner itself is built on Mocha, which the README lists under features, and it uses ES6 natively without a transpiler while also working with TypeScript. Locators are resolved by name, label, matching text, CSS or XPath, which the README calls smart locators. There is an interactive debugging shell that pauses a test so you can try commands in the browser, and parallel execution with dynamic test pooling for load balancing.

Installing CodeceptJS and running a first test

The README gives a four-command path from an empty project to a passing run. Install the package into your project first:

npm i codeceptjs --save

Then move into the directory where you want the tests and the config to live and run the initializer. The README notes it is recommended to select WebDriver from the list of helpers if you need to write Selenium WebDriver tests, which implies the prompt offers several:

npx codeceptjs init

The initializer writes a CodeceptJS config file and sets up the test environment. After that, generate a test:

npx codeceptjs generate:test

The generated test follows the shape the README shows at the top of the page. A minimal scenario that checks for text on the root page looks like this:

Feature('CodeceptJS demo')

Scenario('check Welcome page on site', ({ I }) => {
  I.amOnPage('/')
  I.see('Welcome')
})

Run it with the runner command. What you should see is the scenario executed against the helper you selected during init, with the result printed to the terminal:

npx codeceptjs run

If you want TypeScript, the README's last install step is to generate standard type definitions into the current directory:

npx codeceptjs def .

The repository also ships a Dockerfile that builds on mcr.microsoft.com/playwright:v1.61.0-noble, installs xvfb and the usual browser libraries, symlinks the binary to /usr/local/bin/codeceptjs, and sets CODECEPT_DOCKER=1 with HOST=selenium. Treat that image as the maintainers' own CI setup rather than a documented deployment recipe; the README does not walk through it.

Where the abstraction costs you

The same design that makes tests portable makes failures harder to attribute. When a step fails, the stack runs through the helper into the driver, and the helper's documentation is the contract you have to read. The README links a Helpers API reference under docs/helpers, which is where the per-helper method lists live, but a helper's method set is necessarily smaller than the driver's. Anything outside it means a custom step, and a custom step means you are now maintaining code that the framework's own upgrade path does not cover.

The synchronous style is also a constraint, not just a convenience. The README says tests are synchronous and adds that "your tests should be linear". That is a real boundary: branching logic, loops over dynamic element counts, and complex conditional flows push against the model, and the framework's answer is usually to move that logic into a page object or a custom helper. Teams coming from Playwright's own runner, where async is explicit and the test body is ordinary JavaScript control flow, often find this the hardest adjustment.

Finally, the version story is worth checking before you pin anything. The newest release listed is 4.2.0, published on 2026-09-22, and the default branch is 4.x. The package.json on that branch still declares "version": "4.0.0-rc.1". That mismatch is normal for a repository mid-release, but it means reading the branch's manifest tells you nothing about what npm will install. The last push to the repository was on 2026-09-22, so the project is being worked on; that says nothing about whether any particular helper keeps pace with its upstream driver.

CodeceptJS compared with Playwright's own test runner

The obvious alternative is Playwright's bundled test runner, which is also the helper most CodeceptJS users start with. The difference is where the abstraction sits. Playwright's runner gives you the driver's API directly: pages, locators, fixtures, and explicit async. CodeceptJS gives you a step vocabulary and a runner that can swap the driver underneath.

That swap is the whole point. If your suite is web-only and will stay web-only, Playwright's runner is one less layer to learn and one fewer place for a step's semantics to be redefined. If you also need Appium for a mobile app, or you have existing Selenium infrastructure, the CodeceptJS layer is what lets one scenario style cover both. The README's helper list is the evidence for that claim: Playwright, Puppeteer, WebDriver, Obscura, Appium and Detox all sit behind the same I object.

A second difference is the locator model. CodeceptJS resolves elements by name, label, matching text, CSS or XPath, which the README groups under smart locators. That is friendlier for tests written by people who are not browser specialists, and it is a layer you cannot see through when a locator resolves to the wrong element. Playwright's locator API is more verbose but its resolution rules are the driver's own, documented in one place.

Licence, upgrades and what maintenance actually looks like

CodeceptJS is MIT licensed, stated in both the README badge area and the package.json license field. For most teams that means you can use it commercially, modify it and redistribute it, subject to the usual MIT conditions of keeping the copyright notice and permission notice. That is a description of the licence text, not legal advice; if your organisation has a policy on dependency licences, run it past whoever owns that policy.

The upgrade cost is tied to the helper you pick. Upgrading CodeceptJS itself is an npm operation, but the meaningful risk is the driver underneath: the Dockerfile pins mcr.microsoft.com/playwright:v1.61.0-noble, and the WebDriver helper is described in the README as using webdriverio. When those upstreams move, the helper has to follow, and the framework's own release cadence is not the same thing as the helper's compatibility with the newest driver. The repository's CI runs separate workflows per engine (Playwright, Puppeteer, WebDriver, Obscura, Appium on Android), which is a reasonable signal that each helper is exercised, but it does not tell you how quickly a new upstream major lands.

On activity: the last push was on 2026-09-22 and the repository is not archived, so there is current work. The release list shows 4.2.0 on 2026-09-22, preceded by two betas in the same month. Read the changelog for the specific helper you depend on before upgrading, because a framework-level release note will not enumerate every driver-level change.

Editorial conclusion

Adopt CodeceptJS if you need one scenario syntax across Playwright, Puppeteer, WebDriver, Obscura and Appium, and you accept that the helper layer sits between you and each driver's own API. Do not adopt it if your team is already fluent in Playwright's own test runner and has no mobile or multi-driver requirement, because the abstraction then buys you little and hides the driver docs you will still need. Before committing, run npx codeceptjs init in a scratch directory, pick the helper you actually intend to ship with, and confirm that the locator style and the helper's documented methods cover the assertions your suite depends on. Then check the version you installed: the repository's package.json on the 4.x branch still reads 4.0.0-rc.1 while the newest published release is 4.2.0, so pin the version you test against rather than tracking the branch.

Frequently asked questions

Official sources

1. codeceptjs/CodeceptJS on GitHub
2. License: MIT
3. Project website
4. README
5. Releases