Generate and Maintain CodeceptJS End-to-End Tests

CodeceptJS Test Expert is a skill for writing maintainable, readable end-to-end test suites in CodeceptJS, a behavior-driven-development (BDD) testing framework. It covers test structure and organization (descriptive scenario names that explain business value, feature files grouped by functionality, the Page Object Model for maintainable UI interactions, separating test data from test logic via data tables/external files, and tags for selective execution), plus core best practices: semantic methods (I.see, I.click, I.fillField) over brittle selectors, custom steps and page objects to cut duplication, proper waiting strategies for dynamic content, and configuring multiple helpers (Playwright, WebDriver, REST) as needed.

Use it when building or maintaining a CodeceptJS end-to-end suite that needs to stay readable and stable as the app grows - Page Objects, tagged scenarios, and semantic waits are all aimed at that. It explicitly warns against several anti-patterns: hardcoded waits like I.wait(5) instead of semantic waits, XPath selectors when data-testid attributes are available, cramming multiple user journeys into one scenario, coupling tests to UI implementation details, and ignoring flaky tests instead of investigating root causes. If your suite is fighting these patterns, that is itself the signal to apply this skill.

Input is the application under test (its UI and/or API) plus the test scenarios to cover. Output is a CodeceptJS test suite: a codecept.conf.js configuration, Page Object modules encapsulating locators and actions, tagged Scenario test files (including data-driven scenarios via Data([...]).Scenario), and custom step definitions in steps_file.js for reusable actions like logging in as a role or waiting on a specific API response. A base configuration looks like this:

const { setHeadlessWhen, setCommonPlugins } = require('@codeceptjs/configure');

setHeadlessWhen(process.env.HEADLESS);
setCommonPlugins();

exports.config = {
  tests: './tests/*_test.js',
  output: './output',
  helpers: {
    Playwright: {
      url: process.env.BASE_URL || 'http://localhost:3000',
      show: process.env.HEADLESS !== 'true',
      browser: 'chromium',
      waitForTimeout: 10000,
      waitForAction: 1000
    },
    REST: {
      endpoint: process.env.API_URL || 'http://localhost:3001/api'
    }
  },
  include: {
    I: './steps_file.js',
    loginPage: './pages/LoginPage.js',
    dashboardPage: './pages/DashboardPage.js'
  },
  plugins: {
    screenshotOnFail: {
      enabled: true
    },
    retryFailedStep: {
      enabled: true,
      retries: 2
    }
  },
  mocha: {
    reporterOptions: {
      'codeceptjs-cli-reporter': {
        stdout: '-',
        options: { verbose: true }
      }
    }
  }
};

Debugging support includes pause() for interactive debugging, I.say() for step documentation and logging, and I.saveScreenshot() at critical points; performance guidance covers minimizing page reloads between related scenarios, using I.executeScript() for direct DOM manipulation, keeping test isolation lean, running independent suites in parallel, and caching authentication state with I.saveStorageState().

It combines the Playwright and WebDriver helpers for browser automation with the REST helper for API calls in the same suite, and integrates with the Mocha test runner via the codeceptjs-cli-reporter, so a single scenario can mix I.sendGetRequest/I.seeResponseCodeIsSuccessful API assertions with UI checks like I.see and I.seeAttributesOnElements.

QA engineers and developers who want failures to be diagnosable at a glance - custom screenshot naming on failed scenarios, retryFailedStep tuned per-suite rather than left at a default retry count, and I.say() narration baked into the scenario itself - instead of scrolling raw stack traces to figure out what a CodeceptJS run actually did.