CodeceptJS docs

CodeceptJS 4.0 is here

CodeceptJS

End-to-end testing, written like prose.

Write less. Test more.
Works with Playwright, WebDriver, Puppeteer, and Appium.

Start Now → Read Docs

v4 · MIT · Node 20+

tests/todo_test.js running…

Migrate from Cypress Migrate from Protractor Migrate from TestCafe Migrate from Java / Selenium

For Humans & Agents

Humans		Agents
Less code written		Less tokens consumed
CodeceptJS reads as actions, not selectors. Where Playwright and WebDriver make you wrangle locators by hand, you describe what the user does — the framework resolves the locator and dispatches it through Playwright, WebDriver, or Puppeteer.
Tests explain themselves		Agents understand intent faster
You write automation the way you'd write a test case: what the user does, what they should see. No tangled selector chains polluting the file. A teammate scanning the scenario — or an agent picking it up — grasps the intent in seconds and can adjust it without reverse-engineering anything.
Declarative actions		Fewer failed tries, faster feedback
`I.selectOption` handles native `<select>`, custom comboboxes, and ARIA listboxes the same way. `I.fillField` works on plain inputs and rich editors alike. CodeceptJS adapts to whatever your page actually uses — fewer flaky retries for humans, fewer HTML dumps and tool calls for agents.
Debug live with `pause()`		Debug live via MCP
Drop `pause()` anywhere in a scenario and you land in an interactive REPL with the page state still warm — try commands, inspect elements, patch the test in place. Agents get the same surface through MCP: they drive the running test, pause on any step, poke at the page, then update the code and rerun in debug mode.
Opinionated by default		Universal skill set
Page objects, data fixtures, mobile and web plugins — the framework ships with strong defaults instead of leaving you to assemble them. Agents inherit the same structure through the official skill set: they know how to write, debug, refactor, and organize tests the way the framework expects.

Simple, yet professional.

Architecture and test design applied by default

codecept.conf.ts

milestones.test.ts

tasks.test.ts

Milestone.ts

Task.ts

heal.ts

steps_file.ts

milestones.test.ts

Feature('Milestones');
Before(({ login }) => {  login();});
Scenario('Create a milestone @smoke', ({ milestonePage }) => {  milestonePage.open();  milestonePage.create({ name: 'Q2 Release', dueDate: '2024-06-30' });  milestonePage.checkVisible('Q2 Release');});
Scenario('Milestone tracks task progress', ({ I, milestonePage }) => {  milestonePage.open();  milestonePage.select('Q2 Release');  I.see('0 / 5 tasks', '.progress');  I.see('0%', '.progress-bar');});
Scenario('Complete a milestone', ({ I, milestonePage }) => {  milestonePage.open();  milestonePage.select('Q2 Release');  I.click('Mark as Complete');  I.see('Completed', '.milestone-status');});

Built to last.

Tests that outlive the framework wars

CodeceptJS started in 2015. We watched Protractor, TestCafe, NightmareJS come and go, how WebDriver and CDP tools evolve. But our tests never changed. A test which was running on Protractor back then runs on Playwright today. Whatever comes next: your tests stay.

Write what, not how

I.click('Login') finds the button — by text, by label, by ARIA role, by CSS — and clicks it. You describe the action. The framework picks the strategy. The test reads like the spec it came from.

The smallest API in browser testing

A dozen commands cover most of what you'll write. Less to learn on day one, a test file a junior can read on the first morning. Simplicity is the feature.

Healing, end to end

React to instability. When a selector breaks, AI can rewrite it on the fly. When the network blips, API calls restart. Tests adapt to environment changes instead of failing on them.

Designed for agentic testing

Claude or Cursor run a test and can control it live via MCP server. No guessing, running, and retrying loop. Agent can set a breakpoint and debug test in realtime in a browser.

Mobile, native, web — one framework

Appium for iOS and Android. The same I.click or I.tap(), I.see, I.swipeLeft you use on the web. Mobile testing works on same princinples.

Page Objects you compose, never import

A page object can use any other page object, custom step, or helper by name. The DI container resolves them at runtime. One page object can reference other and vise versa with no more circular import failure.

Data declared, not scripted

Declare your API endpoints once, use built-in tools to create and clean up date in each test. A new user needed? Declare it: I.have('user', { role: 'admin' }) this creates one, and removes after a test.

Output you can actually read

Steps by step output, useful debug introspections by default. You see how test goes, you see when it goes wrong, screenshots are generated automatically.

No tests yet? Agent can test for you!

Explorbot on GitHub

We also created Explorbot — the world's first open-source self-testing agent. It explores your site, writes tests as it goes, and runs autonomously for hours on CI. Already have a regression suite? Explorbot finds the paths it never touched. Explorbot is powered by CodeceptJS and writes its tests.

Free · Open source · Powered by CodeceptJS