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.
- Node.js installed on your system. (Follow below link to Download and Install Node.)
- 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.
Harish is an SDET with expertise in API, web, and mobile testing. He has worked on multiple Web and mobile automation tools including Cypress with JavaScript, Appium, and Selenium with Python and Java. He is very keen to learn new Technologies and Tools for test automation. His latest stint was in TestProject.io. He loves to read books when he has spare time.