How to Automate Visual Testing With Puppeteer Screenshot

How to Capture a Web Element in Puppeteer Screenshot?

Besides taking screenshots of a specific area or a full page from any chosen webpage, you can also capture images of an element using Puppeteer screenshot functionality. The process for capturing an element on a webpage with Puppeteer is straightforward once you’ve identified the targeted element.

After selecting the targeted element using XPath or CSS Selectors, call the <target_element>.screenshot() method with the correct argument to capture the image.

Example Code Snippet:

page.goto('https://www.lambdatest.com/selenium-playground/table-pagination-demo');
const div = await page.$('#table-id');
await div.screenshot({ path: 'table.png' });

Before you take a screenshot of the element, navigate to the page using the provided URL. The targeted element is selected using the page.$() method, with the CSS Selector supplied as an argument.

Once the element is returned and stored in the div variable, the div.screenshot() method is called with a path argument to save the captured image.

Result:

How to Capture Elements by Class Name With Puppeteer Screenshot?

You can capture images of elements by targeting their class name with Puppeteer screenshot functionality. Oftentimes, the same class names are used for multiple elements, which means that when a class name selector is used, all matching elements are returned.

To take a screenshot of an element by class name, you’ll need to filter the array of elements returned to get the specific one or pick the first element in the array.

• page.$(): Returns the first element that matches the specified selector.
• page.$$(): Returns all elements that match the specified selector.

Example Code Snippet:

await page.goto('https://www.lambdatest.com/selenium-playground/simple-form-demo'); // snap demo form URL
const divs = await page.$$('.h-35');
for (let i = 0; i < divs.length; i++) {
    await divs[i].screenshot({ path: `element${i}.png` });
}

First, navigate to the webpage where you’ll capture the DOM element by class name. Use the CSS class selector to pick out the targeted element or elements.

As seen in the code snippet above, page.$$() returns all elements with the CSS Selector .h-35. There are three such elements on the webpage returned.

A for loop is used to iterate over each of the returned elements, and the screenshot is taken via the divs[i].screenshot({ path:`element${i}.png` }) method call.

See screenshot of elements returned with the same class name below:

Running Puppeteer screenshot tests locally might seem simple at first, but it quickly gets complicated as your testing needs grow. When performing Puppeteer browser automation, you often face challenges with headless testing, where debugging visual issues becomes tedious without a real browser view.

Test execution speed can slow down, especially when handling multiple pages or doing Puppeteer visual testing to validate UI changes. On top of that, keeping track of test reports across local runs can be time-consuming and inconsistent.

That’s where cloud testing platforms make a real difference. They remove setup overhead, boost performance with scalable infrastructure, and provide built-in analytics that make monitoring and debugging Puppeteer tests much easier.

Running Puppeteer Screenshot Tests in Parallel

Using a cloud platform such as LambdaTest, you can run tests in your preferred framework, accelerate execution, and take advantage of advanced features like Puppeteer parallel testing and real device coverage.

LambdaTest is a cloud testing platform that allows you to perform online Puppeteer visual testing to capture and compare screenshots across 3000+ browsers and OS combinations, helping you deliver a seamless user experience.

To get started with Puppeteer automation on LambdaTest, follow the steps below:

• Create .env File: Store your LambdaTest credentials securely by creating a .env file in the root of your Puppeteer project and adding your credentials.

LT_USERNAME="<your_username>"
LT_ACCESS_KEY="<your_access_key>"

• Get LambdaTest Credentials: Go to Account Settings > Password & Security on LambdaTest, copy your Username and Access Key, and add them to the .env file to keep them safe from public exposure.
• Define LambdaTest Capabilities: Set the environment for Puppeteer testing, including browser, version, OS, resolution, and other options, ensuring consistent execution across real browsers in the cloud.

const capabilities = {
       'browserName': 'Chrome',
       'browserVersion': 'latest',
       'LT:Options': {
           'platform': 'Windows 10',
           'build': 'puppeteer-build-1',
           'name': 'My first Puppeteer test',
           'resolution': '1366x768',
           'user': process.env.LT_USERNAME || "Your Username",
           'accessKey': process.env.LT_ACCESS_KEY || "Your Access Key",
           'network': true
       }
   };

• Connect LambdaTest Grid: Use browserWSEndpoint to connect your Puppeteer test to the LambdaTest cloud grid with the defined capabilities.

const browser = await puppeteer.connect({
    browserWSEndpoint: `wss://cdp.lambdatest.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`,
});

Code Implementation:

The remote connection to the LambdaTest testing platform will be contained in the samples/connector.js. A browser and page instances will be created for testing with Puppeteer.

'use strict';
import { connect } from 'puppeteer';

export async function remoteBrowserPage() {
    const capabilities = {
        browserName: 'Chrome',
        browserVersion: 'latest',
        'LT:Options': {
            platform: 'Windows 10',
            build: 'puppeteer-build-1',
            name: 'My first Puppeteer test',
            resolution: '1366x768',
            user: process.env.LT_USERNAME || "Your Username",
            accessKey: process.env.LT_ACCESS_KEY || "Your Access Key",
            network: true
        }
    };

    let browser;
    let page;

    try {
        browser = await connect({
            browserWSEndpoint: `wss://cdp.lambdatest.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`,
        });

        page = await browser.newPage();
        await page.setViewport({
            width: 1024,
            height: 768,
            deviceScaleFactor: 1,
        });

    } catch (e) {
        console.log("Error - ", e);
        if (browser) {
            page = await browser.newPage();
            await page.evaluate(_ => {}, `lambdatest_action: ${JSON.stringify({ action: 'setTestStatus', arguments: { status: 'failed', remark: "Test Failed" } })}`);
            await browser.close();
        }
    }

    return { page, browser };
}

Code Walkthrough:

• Import and Define Function: Import connect from Puppeteer and create an async function named remoteBrowserPage that returns both the browser and page instances.
• Set Up Capabilities: Use the LambdaTest capabilities generator to create a capabilities object, defining essential parameters such as browserName and browserVersion.
• Connect to LambdaTest Grid: Establish a browser instance using connect() with the WebSocket endpoint, including the generated capabilities within the URL.
• Create a New Page: Use browser.newPage() to open a new tab, and implement a try-catch block to handle exceptions, setting the LambdaTest test status as failed if an error occurs.
• Return Instances: Return both the browser and page instances from the remoteBrowserPage() function.
• Use in screenshot.js: Import the exported remoteBrowserPage() function from connector.js and destructure it to access the browser and page instances.

import { remoteBrowserPage } from "./connector.js";
(async () => {
    let { page, browser } = await remoteBrowserPage();

Test Execution:

Use the command below to execute the code from your terminal:

node samples/screenshot.js

Result:

For screenshot testing using Puppeteer, you can use SmartUI on LambdaTest to perform cloud-based visual regression testing and compare UI changes effortlessly. Follow this support documentation on SmartUI using Puppeteer.

Common Puppeteer Screenshot Errors and How to Fix Them

It’s not unusual to encounter certain errors when using Puppeteer screenshot functionality.

Some of the most common issues and how you can fix them.

• Blank Screenshot: This happens when the screenshot is captured before the webpage finishes loading.

  Solution: Ensure that all content is fully loaded, or scroll through the page to load any lazy-loaded elements before capturing.

• Invalid Selector Error: This error occurs when trying to capture a screenshot of an element with an invalid selector.

  Solution: Double-check that the selector is correct and that the target element exists on the webpage.

• TimeoutError: This occurs when the webpage or targeted element takes longer than expected to load.

  Solution: Increase the default timeout or use Puppeteer’s wait methods to ensure specific elements appear in the DOM before taking the screenshot.

• File Path Error: This happens when the specified file path or directory doesn’t exist.

  Solution: Puppeteer can only create the screenshot file if the target directory already exists.

• Cut-off Content: This issue arises when the viewport size is too small, causing partial or cut-off screenshots.

  Solution: Adjust the viewport size to ensure the entire content is visible before capturing.

While these solutions help during local testing, automated screenshot testing platforms allow you to capture screenshots of your website across a diverse range of real desktop and mobile devices.

This ensures consistent visual validation, helps detect layout shifts or device-specific rendering issues, and reduces manual effort in checking your site’s appearance on multiple browsers and screen sizes.

Conclusion

Puppeteer is a modern browser automation tool that enables capturing screenshots of designated webpages and elements. It provides different options for customization when taking screenshots. Users can capture an element, a full page, a clip of a specific area, etc.

Taking screenshots can prove very helpful to developers for debugging purposes. It saves as a visual reference when performing UI testing.