A Beginner’s Guide to Fast, Reliable Web Testing with CodeceptJS & Puppeteer 

CodeceptJS Puppeteer Guide

Looking to simplify your UI test automation without compromising on speed or reliability? 

Welcome to CodeceptJS + Puppeteer — a powerful combination that makes browser automation intuitive, maintainable, and lightning-fast. Whether you’re just stepping into test automation or shifting from clunky Selenium scripts, this CodeceptJS Puppeteer Guide will walk you through the essentials to get started with modern JavaScript-based web UI testing. 

Why CodeceptJS + Puppeteer? 

• Beginner-Friendly: Clean, high-level syntax that’s easy to read—even for non-coders. 
• Super-Fast Execution: Puppeteer runs headless Chrome directly, skipping WebDriver overhead. 
• Stable Tests: Auto-waiting eliminates the need for flaky manual waits. 
• Built-in Helpers & Smart Locators: Interact with web elements effortlessly. 
• CI/CD Friendly: Easily integrates into DevOps pipelines. 
• Rich Debugging Tools: Screenshots, videos, and console logs at your fingertips. 

In this blog, you’ll learn: 

• How to install and configure CodeceptJS with Puppeteer 
• Writing your first test using Page Object Model (POM) and Behavior-Driven Development (BDD) 
• Generating Allure Reports for beautiful test results 
• Tips to run, debug, and manage tests like a pro 

Whether you’re testing login pages or building a complete automation framework, this guide has you covered. 

Ready to build your first CodeceptJS-Puppeteer test? Let’s dive in! 

1. Initial Setup 

• Prerequisites 
  • Node.js installed on your system. (Follow below link to Download and Install Node.) 
    • https://nodejs.org/ 
  • Basic knowledge of JavaScript. 
• Installing CodeceptJS 
  Run the following command to install CodeceptJS and its configuration tool: 
  npm install codeceptjs @codeceptjs/configure –save-dev 

2. Initialize CodeceptJS 

• Create a New Project 
  • Initialize a new npm project using following commend: 
  • npm init –y 
• Install Puppeteer 
  Install Puppeteer as the default helper: 
  npm install codeceptjs puppeteer –save-dev 
• Setup CodeceptJS
  Run the following command to set up CodeceptJS: 
  npx codeceptjs init 

As shown below, follow the steps as they are; they will help you build the framework. You can choose Puppeteer, Playwright, or WebDriver—whichever you prefer. Here, I have used Puppeteer to create the framework 

This will guide you through the setup process, including selecting a test directory and a helper (e.g., Puppeteer). 

3. Writing Your First Test  

Example Test Case 

The following example demonstrates a simple test to search “codeceptjs” on Google: 

Dependencies 

Ensure the following dependencies are included in your package.json: 

"devDependencies": { 
    "codeceptjs": "^3.6.10", 
    "puppeteer": "^24.1.0" 
} 

Configuration File 

Update your codecept.conf.js file to specify the base URL and browser settings: 

helpers: { 
    Puppeteer: { 
        url: 'https://www.google.com', 
        show: true, 
        windowSize: '1200x900' 
    } 
} 

A simple test case to perform a Google search is shown below: 

Feature('google_search'); 

Scenario('TC-1 Google Search', ({ I }) => { 
    I.amOnPage('/'); 
    I.seeElement("//textarea[@name='q']"); 
    I.fillField("//textarea[@name='q']", "codeceptjs"); 
    I.click("btnK"); 
    I.wait(5); 
}); 

4. As we have seen how to create a simple test, we will now explore how to create a test in BDD using the POM approach. 

Using Page Object Model (POM) and BDD 

CodeceptJS supports BDD through Gherkin syntax and POM for test modularity. If you want to create a feature file configuration, use this command.  
“npx codeceptjs gherkin:init” 

The setup will be created; however, some configurations still need to be modified, as explained below. You can refer to the details provided. 

After this, the following changes will be displayed in the CodeceptJS configuration file. Ensure that these changes are also reflected in your configuration file. 

gherkin: { 
    features: './features/*.feature', 
    steps: ['./step_definitions/steps.js'] 
  }, 

Creating a Feature File 

A Feature file in BDD is a plain-text file written in Gherkin syntax that describes application behavior through scenarios using Given-When-Then steps. 
Example: Orange HRM Login Test 
Feature: Orange HRM 

Scenario: Verify user is able to login with valid credentials 
Given User is on login page 
When User enters username “Admin” and password “admin123” 
When User clicks on login button 
Then User verifies “Dashboard” is displayed on page 

Step Definitions 

A Step Definitions file in BDD maps Gherkin step definitions to executable code, linking test scenarios to automation logic. 
Define test steps in step_definitions/steps.js: 

const { I } = inject(); 
const { LoginPage } = require('../Pages/LoginPage'); 
const login = new LoginPage(); 

Given('User is on login page', async () => { 
    await login.homepage(); 
}); 

When('User enters username {string} and password {string}', async (username, password) => { 
    await login.enterUsername(username); 
    await login.enterPassword(password); 
}); 

When('User clicks on login button', async () => { 
    await login.clickLoginButton(); 
}); 

Then('User verifies {string} is displayed on page', async (text) => { 

    await login.verifyDashboard(text); 
}); 

Page Object Model 

A Page File represents a web page or UI component, encapsulating locators and actions to support maintainable test automation. 
Create a LoginPage class to encapsulate page interactions: 

const { I } = inject(); 
class LoginPage { 
    async homepage() { 
        I.amOnPage('/'); 
        I.wait(5); 
    } 

    async enterUsername(username) { 
        I.waitForElement('//input[@name="username"]', 10); 
        I.fillField('//input[@name="username"]', username); 
    } 

    async enterPassword(password) { 
        I.fillField('//input[@name="password"]', password); 
    } 

    async clickLoginButton() { 
        I.click('//button[@type="submit"]'); 
        I.wait(5); 
    } 

    async verifyDashboard(text) { 
        I.waitForElement(`//h6[normalize-space()='${text}']`, 20); 
        I.see(text, `//h6[normalize-space()='${text}']`); 
    } 
} 

module.exports = { LoginPage }; 

5. Adding Reports with Allure 

Install Allure Plugin

Install the Allure plugin for CodeceptJS:
npm install @codeceptjs/allure-legacy –save-dev

Update Configuration 

Enable the Allure plugin in codecept.conf.js: 

plugins: { 
    allure: { 
        enabled: true, 
        outputDir: './output', 
        require: '@codeceptjs/allure-legacy' 
    } 
} 

Generate Reports 

Run tests and generate reports: 
npx codeceptjs run 
npx allure generate –clean 
npx allure open 

6. Running Tests 

To execute tests, use the following command: 
npx codeceptjs run 

To log the steps of a feature file on the console, use the command below: 

npx codeceptjs run –steps 

The — verbose flag provides comprehensive information about the test execution process, including step-by-step execution logs, detailed error information, configuration details, debugging assistance, and more. 

npx codeceptjs run –verbose 

To target specific tests: 

npx codeceptjs run <test_file> 

npx codeceptjs run –grep @yourTag 

Conclusion: From Clicks to Confidence with CodeceptJS & Puppeteer 

In this guide, we walked through the essentials of setting up and using CodeceptJS with Puppeteer—from writing simple tests to building a modular framework using Page Object Model (POM) and Behavior-Driven Development (BDD). We also explored how to integrate Allure Reports for insightful test reporting and saw how to run and debug tests effectively. 

By leveraging CodeceptJS’s high-level syntax and Puppeteer’s powerful headless automation capabilities, you can build faster, more reliable, and easier-to-maintain test suites that scale well in modern development workflows. 

Whether you’re just starting your test automation journey or refining an existing framework, this stack is a fantastic choice for UI automation in JavaScript—especially when aiming for stability, readability, and speed. 

💡 Want to dig deeper or fork the full framework? 
🔗 Explore the complete CodeceptJS + Puppeteer BDD framework on GitHub 

Happy testing!

Click here to read more blogs like this.

0