When software testers come across bugs in a web app, they frequently require visual proof to report to the development team. Taking screenshots is one of the most common methods for providing this evidence. Also, as a tester or a developer, there are times you need to automate taking multiple screenshots. As a result, a test automation framework such as Puppeteer must support this functionality—and indeed, it does. In this tutorial, we will discuss how to capture screenshots using the Puppeteer node library.

How to take a screenshot in Puppeteer?

As we mentioned above, capturing a Puppeteer screenshot is a straightforward process that is frequently needed for software testers. In this guide, we assume that you already know how to install Puppeteer in your development environment and you have the knowledge of writing basic Puppeteer codes. If you're unsure how to install it, please refer to the Puppeteer installation page for detailed instructions.

Create a JS file and copy the following basic code for taking a screenshot with Puppeteer.

const puppeteer = require('puppeteer');


(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https:///www.python.org/');
  await page.screenshot({ path: 'pythonorg.png'});
  await browser.close();
})();

In this script, after launching Puppeteer with the `await browser` and creating a new page, we go to the https://python.org web page using page.goto() method. Once the page is loaded, we then take a screenshot using the page.screenshot() method. The screenshot is saved to a file in the current directory named ‘pythonorg.png'. The path option in the screenshot() method specifies the file name and location.

It's important to note that Puppeteer provides various options for screenshots, such as specifying the type (e.g., 'png' or 'jpeg'), quality (for 'jpeg' format), and whether to capture the entire page or just the viewport.

After taking the screenshot, we make sure to close the browser using the browser.close() to free up resources.

How to screenshot the full page?

If you look at the image created from the above code, you'll notice it doesn't capture the entire webpage. By default, without using additional options, the page.screenshot({ path: 'pythonorg.png' }); method captures the 'viewport' area of the page. The viewport refers to the visible part of the webpage as it would appear on your screen in the browser window.

It’s also worth noting that the viewport size in Puppeteer might not match your screen size by default. Puppeteer provides the page.setViewport() method to set the viewport dimensions according to developers' needs. Here is an example of using page.setViewport() method.

await page.setViewport({ width: 1280, height: 720 });

If you want to capture the entire webpage, including the parts that would normally require scrolling, you would set the fullPage option to true in the screenshot method.

await page.screenshot({ path: pythonorg.png', fullPage: true });

How to screenshot a specific area?

With Puppeteer's capture screenshot method, you can define a specific area using coordinates. You must identify the coordinates of the area you want to capture, which are based on the pixel position from the top-left corner of the page. You will need four values:

• x: The horizontal coordinate 
• y: The vertical coordinate
• width: How wide the area should be
• height: How tall the area should be 

Once you have determined these coordinates, you can define the clipping area for the screenshot. Replace the values below with the ones you have determined.

const clip = {
    x: 100,
    y: 200,
    width: 300,
    height: 400
  };

Having defined the clipping area, you can now pass this object to the screenshot() method to capture just the specified region.

await page.screenshot({ path: 'pythonorg.png', clip: clip });

How to screenshot an element?

To capture a particular HTML element, you first need to get the element in Puppeteer. Puppeteer allows you to interact with elements similarly to how you would in a browser with JavaScript. You'll need to identify the selector of the element you wish to capture. This could be an ID, a class, or any selector that uniquely identifies the element.

Here’s how you can take a screenshot of an element.

const element = await page.$('#unique-element-id');
await element.screenshot({ path: 'element.png' });

In this example, page.$ is used to select the first element matching the provided selector, analogous to document.querySelector in the browser. After the element is selected, calling screenshot() on the element object captures it. The screenshot will be saved with the file name 'element.png'.

How to screenshot an element by class name?

The approach remains the same to capture a screenshot of a specific element identified by its class. However, the main difference is classes are not unique like IDs and hence you need to make sure you select the correct class. 

Let's walk through an example. Consider the python.org website, which features a "Donate" button marked with the class .donate-button.

To capture this particular element, you can use the code snippet provided below.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://www.python.org/');
  const donateButtons = await page.$$('.donate-button');
  if (donateButtons.length > 0) {
    const donateButton = donateButtons[0];
    await donateButton.screenshot({ path: 'donate-button.png' });
  } else {
    console.log('No elements with the class .donate-button were found.');
  }
  await browser.close();
})();

In this script, page.$$ is the function used to select all elements with the class ‘.donate-button’. It returns an array of element handles. Since a class can be attributed to multiple elements, we select the first instance in this example, which is likely to be our target button. 

How to manage screenshot quality?

Puppeteer lets you manage the screenshot quality of JPEG images. To adjust the quality, there is a 'quality' option in the screenshot method. You can specify a value between 0 and 100 for the 'quality' option, where 100 is the highest quality.

Let’s look at an example. 

await page.screenshot({ path: 'high-quality.jpg', quality: 100, type: 'jpeg' });

In this example, we save the screenshot with the highest quality possible. Note that the higher the quality, the larger the file size will be. Therefore, you may want to balance quality and file size based on your requirements.

How to manage screenshot resolution?

The resolution of a screenshot in Puppeteer is determined by the viewport size. If you need a higher resolution screenshot, you would first set the viewport to a larger width and height. This simulates a larger screen and captures more pixels.

Here's how you can set the viewport to achieve a higher-resolution screenshot.

await page.setViewport({ width: 1920, height: 1080 });
await page.screenshot({ path: 'high-resolution.png' });

In this example, we have set the viewport to 1920x1080, and therefore the screenshot will be taken at a 1080p resolution. Feel free to change the width and height to parameters to change the resolution of the screenshot you get. 

How to wait before taking a screenshot?

For web pages that include elements like animations or elements that load over time, you might need to delay your screenshot to capture the page in the right state. Puppeteer allows you to insert a wait time with page.waitForTimeout(). This function temporarily halts the script for a set duration that you can specify in milliseconds.

Here's an example of waiting for 3 seconds before taking a screenshot.

await page.waitForTimeout(3000);
await page.screenshot({ path: 'wait-for-time.png' });

Fixing common errors while using page.screenshot method

While using the page.screenshot() method to take puppeteer screenshots, several common errors may occur.

• Invalid Selector Error: If you're capturing a screenshot of an element and the selector does not match any elements on the page, Puppeteer will throw an error. 
• Timeout Error: When using methods like page.waitForSelector() before taking a screenshot, if the element does not appear within the default timeout period (usually 30 seconds), Puppeteer will throw a timeout error.
• File Path Issues: If the file path specified in the path option is invalid or inaccessible, Puppeteer cannot save the screenshot and will throw an error.
• Viewport Not Set Error: Attempting to take a full-page screenshot on a single-page application (SPA) without setting the correct viewport size can lead to errors or incomplete screenshots.
• Resource Load Issues: If the page includes a large number of resources or if there is a slow network, Puppeteer may attempt to take a screenshot before all the resources have finished loading. This can result in screenshots with missing images or styles. It's recommended to wait for all resources to load or for specific elements to become visible before taking the screenshot.

Image not loading

When taking screenshots with Puppeteer, you might come across situations where images on the page have not fully loaded before the screenshot is captured. This issue can result from network latency or lazy-loaded images that only load when scrolled into view. To mitigate this, you can use page.waitForSelector() to wait for specific images to load, or page.waitForFunction() to wait for all images to finish loading.

Slow screenshot times

Slow screenshot times can occur for various reasons, including heavy page content, high-resolution screenshots, or limited system resources. To improve screenshot times, consider the following strategies.

• Reduce Viewport Size: A smaller viewport size means less content to capture, which can speed up the screenshot process. 
• Simplify Page Content: If possible, simplify the page content by disabling animations, hiding non-essential elements, or stopping media playback before taking a screenshot. 
• Increase Resources: If you’re running Puppeteer in a resource-constrained environment, try allocating more CPU or memory to the process.

Conclusion

Puppeteer is a powerful tool for web scraping, and test automation, offering a high degree of flexibility and control over the screenshot-taking process. With the guidance provided in this tutorial, users can go through various screenshot techniques, from capturing an entire page, or a specific element, or even managing screenshot quality and resolution.

For efficient and anonymous scraping, proxies are important. When it comes to proxies for Puppeteer, Webshare stands out as a reliable option. We offer 10 premium proxies for free, which can be especially beneficial for initial testing and understanding the process of web scraping with Puppeteer.