Configuration

Learn how to configure your CodeceptJS project and extend it with page objects and custom helpers.

Config File

The CLI discovers your config file automatically by looking for:

1. codecept.conf.ts (recommended)
2. codecept.conf.js
3. codecept.conf.mjs
4. codecept.conf.cjs

TIP

You never need to specify the config path manually — ccjs finds it for you.

Basic Structure

// codecept.conf.ts
export const config: CodeceptJS.MainConfig = {
  tests: './tests/**/*.test.ts',
  output: './output',
  helpers: {
    Playwright: {
      browser: 'chromium',
      url: 'http://localhost:3000',
      show: false,
    },
  },
  plugins: {
    screenshotOnFail: { enabled: true },
    retryFailedStep: { enabled: true },
  },
  include: {},
  name: 'my-project',
}

Page Objects

Page objects encapsulate selectors and common actions for a page:

// pages/LoginPage.ts
const { I } = inject()

export = {
  fields: {
    email: '#email',
    password: '#password',
  },
  buttons: {
    submit: 'Sign In',
  },

  login(email: string, password: string) {
    I.amOnPage('/login')
    I.fillField(this.fields.email, email)
    I.fillField(this.fields.password, password)
    I.click(this.buttons.submit)
  },
}

Register in codecept.conf.ts:

include: {
  loginPage: './pages/LoginPage.ts',
},

Use in tests:

Scenario('login via page object', ({ I, loginPage }) => {
  loginPage.login('user@test.com', 'secret123')
  I.see('Dashboard')
})

Generate page objects

Use ccjs generate pageobject to scaffold page objects interactively.

Custom Helpers

Extend the I object with custom methods:

// helpers/ApiHelper.ts
const Helper = require('@codeceptjs/helper')

class ApiHelper extends Helper {
  async createUser(name: string, email: string) {
    const response = await fetch('http://localhost:3000/api/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ name, email }),
    })
    return response.json()
  }

  async cleanupTestData() {
    await fetch('http://localhost:3000/api/test/cleanup', { method: 'DELETE' })
  }
}

export = ApiHelper

Register in codecept.conf.ts:

helpers: {
  Playwright: { /* ... */ },
  ApiHelper: { require: './helpers/ApiHelper.ts' },
},

Generate helpers

Use ccjs generate helper to scaffold helpers interactively.

CI Configuration

For CI environments, use non-interactive mode:

# Initialize without prompts
ccjs init --yes --helper Playwright --test-dir ./e2e

# Run tests in parallel for speed
ccjs run workers --count 4

Recommended CI flags:

Flag	Purpose
--steps	Step-by-step output for debugging
--grep "@smoke"	Run only smoke tests
--override '{"helpers":{"Playwright":{"show":false}}}'	Headless mode