Installation

For the quickest start (CodeceptJS + Playwright) follow the Quickstart. This page covers every browser, mobile, and API helper and what each one needs installed.

Set up a project

npm init -y                  # if you don't have a package.json yet
npm i codeceptjs --save-dev

Install one of the helpers below, then scaffold the config and a sample test:

npx codeceptjs init

init runs a short wizard, writes codecept.conf.js and a sample test, and installs the helper’s driver package if it’s missing. The Quickstart walks through the questions.

Playwright

Fast, modern browser automation — the recommended helper for web testing.

npm i playwright --save-dev
npx playwright install --with-deps

playwright install downloads the browser binaries; --with-deps also installs the Linux system libraries they need (run it with sudo if your user can’t install packages).

Set browser in the helper config to one of:

chromium — default
firefox
webkit — the open-source Safari engine
electron — test an Electron app (set electron.executablePath)

To drive branded Chrome or Edge instead of bundled Chromium, install that channel — npx playwright install chrome (or msedge) — and set channel in the config. See the Playwright helper.

Puppeteer

Chrome/Chromium automation over the DevTools protocol.

npm i puppeteer --save-dev

Puppeteer downloads a matching Chromium when it installs — nothing else to set up. To drive an existing Chrome instead, set chrome.executablePath in the helper config (or install puppeteer-core and point it at your browser). See the Puppeteer helper.

WebDriver

W3C WebDriver — runs Chrome, Firefox, Edge, Safari, and remote or cloud grids.

npm i webdriverio --save-dev

WebdriverIO 9 downloads and starts the matching driver automatically — no Selenium server, ChromeDriver, or GeckoDriver to install or run. Just set browser (chrome, firefox, MicrosoftEdge, safari) in codecept.conf.js — see the WebDriver helper.

To run against a cloud grid (Sauce Labs, BrowserStack, LambdaTest, and so on) instead, set the grid’s host, port, user, and key (or protocol / path) in the helper config. For running this on CI, see Continuous Integration.

Appium (mobile)

Native iOS and Android testing. Appium speaks the WebDriver protocol, so CodeceptJS drives it through webdriverio:

npm i webdriverio --save-dev
npm i -g appium

Install the platform driver(s) and start the server:

appium driver install uiautomator2   # Android
appium driver install xcuitest       # iOS
appium

You’ll also need the Android SDK and an emulator or device, or Xcode and a simulator or device (or a device-cloud account). Set platformName, deviceName, and app in the helper config — see Mobile Testing.

API testing

REST and GraphQL tests need no browser — the helpers are built in (they use axios, already a dependency):

npm i codeceptjs --save-dev

Choose REST or GraphQL when init asks, set endpoint in the config, and add the JSONResponse helper if you want response assertions. See Testing APIs.

ESM

CodeceptJS 4.x uses ECMAScript Modules. A project created by init is set up for it; an existing project needs "type": "module" in package.json and import syntax in the config and tests. Coming from 3.x — see the Migration Guide.

TypeScript

npx codeceptjs init scaffolds a TypeScript project when you answer Yes to “Do you plan to write tests in TypeScript?” — it writes codecept.conf.ts and *_test.ts files.

The config file (codecept.conf.ts) and helpers are transpiled automatically. Test files need a loader; install tsx and add it to require:

npm i tsx --save-dev

export const config = {
  tests: './**/*_test.ts',
  require: ['tsx/cjs'],   // loads the *_test.ts files
  helpers: {
    Playwright: { url: 'http://localhost', browser: 'chromium' },
  },
}

Run tests as usual with npx codeceptjs run. For promise-based typings, types for page objects and custom helpers, and custom locator types, see the TypeScript guide.