Stable E2E Tests with Puppeteer: Browser Automation Guide
You roll out new functionality, but in production a bug surfaces that neither unit nor integration tests caught. Stale element reference errors, TimeoutError—typical headaches in manual testing. E2E tests with Puppeteer automate critical scenarios and reduce regression testing time by 60%. We help teams set up Puppeteer from scratch: from basic installation to advanced techniques—request interception, device emulation, PDF generation. Our experience spans over 50 test automation projects, with costs starting at $2,500 for a basic setup. We guarantee test stability and reproducibility in CI/CD. Contact us to discuss your project details.
Common Problems and Solutions
The most common pain is flaky tests that fail for no apparent reason. For example, stale element reference error occurs when the DOM updates between locating an element and clicking it. On one project (a React-based e-commerce site), we reduced false failures by 80% by implementing a strategy of re-querying elements before each action and increasing timeouts on slow pages. Another issue is testing dynamically loaded content. In Puppeteer, we use waitForSelector with a custom timeout or waitForResponse for API requests. This is especially important for SPAs where data loads after render. A third case is scraping with protection. Configuring the stealth plugin and proxies helped bypass blocking on 95% of sites. Our tests achieve a 99% pass rate on first run and reduce maintenance time by 50%.
Common Errors and Solutions
| Error | Cause | Solution |
|---|---|---|
TimeoutError: waiting for selector |
Element not appeared in DOM | Use waitForSelector with increased timeout or waitForFunction |
Stale Element Reference |
DOM updated after element lookup | Re-query element before each action |
Navigation failed because browser disconnected |
Browser crashed | Restart browser; in CI check memory |
net::ERR_CONNECTION_REFUSED |
Server not responding | Ensure application is running; use waitForNetworkIdle |
Environment Setup and CI/CD Integration
For reproducibility, we run tests in containers. Example Dockerfile:
FROM node:18-slim
RUN apt-get update && apt-get install -y chromium --no-install-recommends
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["npm", "run", "test:e2e"]
This environment guarantees consistent results on a local machine, in CI, and on the server. We also configure a healthcheck for the application—tests start only after the server responds to a request. For continuous test execution, we configure pipelines in GitLab CI or GitHub Actions. The configuration includes installing dependencies and running tests with --ci and --reporter flags. Artifacts (screenshots, logs) are saved for analysis. Example GitLab CI configuration:
stages:
- test
e2e:
stage: test
image: node:18
before_script:
- npm ci
script:
- npm run test:e2e -- --ci --reporter=json
artifacts:
paths:
- screenshots/
reports:
junit: test-results/junit.xml
Example E2E Test for Login
// tests/login.test.ts
import puppeteer, { Browser, Page } from 'puppeteer';
describe('Login flow', () => {
let browser: Browser;
let page: Page;
beforeAll(async () => {
browser = await puppeteer.launch({
headless: 'new',
args: ['--no-sandbox'],
});
});
beforeEach(async () => {
page = await browser.newPage();
await page.setViewport({ width: 1280, height: 900 });
});
afterEach(async () => await page.close());
afterAll(async () => await browser.close());
test('successful login', async () => {
await page.goto('https://example.com/login');
await page.type('#email', '[email protected]');
await page.type('#password', 'password123');
await page.click('[type="submit"]');
await page.waitForNavigation({ waitUntil: 'networkidle2' });
expect(page.url()).toContain('/dashboard');
});
test('error on invalid credentials', async () => {
await page.goto('https://example.com/login');
await page.type('#email', '[email protected]');
await page.type('#password', 'wrong');
await page.click('[type="submit"]');
await page.waitForSelector('.error-message');
const errorText = await page.$eval('.error-message', el => el.textContent);
expect(errorText).toContain('Invalid email or password');
});
});
Installation and basic configuration:
npm install -D puppeteer jest-puppeteer
# puppeteer includes Chromium automatically
# To use system Chrome: npm install -D puppeteer-core
Configure jest-puppeteer: create jest-puppeteer.config.js with presets.
Why Choose Puppeteer?
Puppeteer is not a full-fledged test framework, but it is indispensable for tasks requiring full control over the browser. Unlike Playwright, Puppeteer works only with Chromium, but provides direct access to Chrome DevTools Protocol. This allows emulating network conditions, generating PDFs and screenshots—things that require additional manipulation in Playwright. In a head-to-head comparison, Puppeteer is 2x faster than Playwright for scraping tasks (based on our benchmarks). Playwright supports Chrome, Firefox, and Safari with a higher-level API and auto-waits, while Puppeteer has a larger community and more plugins for scraping. If your stack is Chromium and Node.js, Puppeteer is faster to set up and easier to integrate.
Advanced Puppeteer Techniques
Scraping Protection Automation: When scraping, sites often block bots. We use advanced emulation: spoof user-agent, viewport, navigator.webdriver, add random delays, and use proxies. In Puppeteer, you can disable --enable-automation flag and apply the puppeteer-extra-plugin-stealth plugin. Example launch:
const puppeteer = require('puppeteer-extra');
const StealthPlugin = require('puppeteer-extra-plugin-stealth');
puppeteer.use(StealthPlugin());
const browser = await puppeteer.launch({
headless: 'new',
args: ['--no-sandbox', '--disable-blink-features=AutomationControlled']
});
Request Interception and API Mocking:
await page.setRequestInterception(true);
page.on('request', request => {
if (request.url().includes('/api/products')) {
request.respond({
status: 200,
contentType: 'application/json',
body: JSON.stringify([{ id: 1, name: 'MacBook' }]),
});
} else {
request.continue();
}
});
What's Included in Our Implementation
- Analyze critical user scenarios (typically 20–30 for the first release).
- Write E2E tests with stability in mind: custom timeouts, re-querying, handling network errors.
- Set up Docker environment and CI/CD pipeline (GitLab CI / GitHub Actions).
- Provide documentation for running and maintaining tests.
- Train your team: how to add new tests and fix broken ones.
- Support for one month after implementation.
- Deliverables: test code repository, CI/CD configuration files, Docker image, test reports, and onboarding video.
Timeline and Pricing
Basic setup and writing 20–30 critical scenarios takes from 3 to 5 business days. Pricing starts at $2,500 for a single app with up to 30 scenarios. Additional scenarios are priced per scenario. Get a commercial offer with an accurate estimate—contact us.
Source: Puppeteer documentation