Step-by-Step Guide to Capturing Screenshots with Selenium Scripts

Web automation testing enables developers to identify and fix issues in web applications efficiently. A popular open source tool, Selenium WebDriver, can create and execute test cases across various operating systems, browsers, and programming languages.

Importantly, Selenium WebDriver can capture full-page screenshots, allowing you to see how the page looks at various stages of testing. When a test fails, a Selenium screenshot lets the tester see exactly what the browser looked like when the test failed.

Thus, they can quickly identify the source of the issue, for example, a particular element missing or a button that did not fully load. Taking screenshots in Selenium using scripts is easy when you follow the process outlined below.

How to Take Screenshots in Selenium: Step-by-Step Tutorials

Taking Full Page Screenshots With Java

To capture screenshots in Selenium with Java, first, we need to set up Selenium WebDriver. To do this, add Selenium dependencies to your Java project. If you’re using an IDE, you might also need Java extensions.

<dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-java</artifactId>
    <version>4.16.1</version>
</dependency>

You may need to create a pom.xml file to add the dependency. In any case, this step downloads Selenium WebDriver, including browser driver support, and gives you access to key interfaces.

To take a Selenium screenshot of the entire page, we need browser-specific support. In the example below, we use FirefoxDriver to capture screenshots on Firefox.

Create an app.java file in your project structure under src/main/java and add the following code to the file:

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.firefox.FirefoxDriver;
import org.openqa.selenium.TakesScreenshot;
import org.openqa.selenium.OutputType;
import org.openqa.selenium.io.FileHandler;

import java.io.File;
import java.io.IOException;

public class FullPageScreenshotExample {

    public static void main(String[] args) throws IOException {

        WebDriver driver = new FirefoxDriver();
        driver.get("https://example.com");

        if (driver instanceof FirefoxDriver) {

            FirefoxDriver firefoxDriver = (FirefoxDriver) driver;

            File srcFile =
                    firefoxDriver.getFullPageScreenshotAs(OutputType.FILE);

            File destFile = new File("screenshots/fullpage.png");

            FileHandler.createDir(new File("screenshots"));
            FileHandler.copy(srcFile, destFile);
        }

        driver.quit();
    }
}

Without specifying the browser, Selenium WebDriver can only take viewport screenshots using the TakesScreenshot interface. In other words, it will only capture screenshots of the visible part of the browser, not the entire page.

Element Screenshot in Java

The snippet below shows how to capture a Selenium screenshot of a particular element in Java using getScreenshotAs() on the element.

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.By;
import org.openqa.selenium.OutputType;
import org.openqa.selenium.firefox.FirefoxDriver;
import org.openqa.selenium.io.FileHandler;

import java.io.File;
import java.io.IOException;

public class ElementScreenshotExample {

    public static void main(String[] args) throws IOException {

        WebDriver driver = new FirefoxDriver();
        driver.get("https://example.com");

        // Locate the element
        WebElement heading = driver.findElement(By.tagName("h1"));

        // Capture screenshot of the WebElement
        File srcFile = heading.getScreenshotAs(OutputType.FILE);

        // Destination file
        File destFile = new File("screenshots/element.png");

        // Save the screenshot
        FileHandler.createDir(new File("screenshots"));
        FileHandler.copy(srcFile, destFile);

        driver.quit();
    }
}

Once again, in the example, we use Firefox, but Selenium WebDriver supports taking screenshots across multiple browsers and web applications.

Taking Screenshots Using Python

Now, let’s look at different ways to capture screenshots using Python . First, here is an example of taking a viewport screenshot in Selenium using the save_screenshot() method.

from selenium import webdriver
import os

driver = webdriver.Chrome()
driver.get("https://example.com")


os.makedirs("screenshots", exist_ok=True)
driver.save_screenshot("screenshots/viewport.png")

driver.quit()

Note that while the Selenium screenshot captured with this method may be called a full-page screenshot, it does not capture the entire page that a user can scroll through.

Once again, to take a screenshot in Selenium that captures the entire page, we need to use Firefox, as this browser provides a native full-page API.

from selenium import webdriver
import os

driver = webdriver.Firefox()
driver.get("https://example.com")


os.makedirs("screenshots", exist_ok=True)
driver.get_full_page_screenshot_as_file("screenshots/fullpage.png")

driver.quit()

To capture a full-page screenshot of the visible page (viewport screenshot) use the get_screenshot_as_file() method.

from selenium import webdriver
import os

driver = webdriver.Chrome()
driver.get("https://example.com")


os.makedirs("screenshots", exist_ok=True)
driver.get_screenshot_as_file("screenshots/viewport.png")

driver.quit()

However, the method is identical to save_screenshot() as per Selenium source code:

def save_screenshot(self, filename) -> bool: return self.get_screenshot_as_file(filename)

So, just use whichever is more comfortable, as the dual naming is likely a legacy artifact of code.

The easiest way to capture a Selenium screenshot of a particular element in Python is using the save_screenshot() method.

from selenium import webdriver
from selenium.webdriver.common.by import By

driver = webdriver.Chrome()
driver.get("https://example.com")

element = driver.find_element(By.TAG_NAME, "h1")

element.screenshot("screenshots/element.png")

driver.quit()

This method lets you take a screenshot in Selenium with any browser.

Screenshot Capture in Other Languages

Let’s look at how to capture screenshots in a few other popular languages. Below is the code example for taking a viewport screenshot in C# using the ITakeScreenshot interface.

using OpenQA.Selenium;
using OpenQA.Selenium;
using OpenQA.Selenium.Chrome;

IWebDriver driver = new ChromeDriver();
driver.Navigate().GoToUrl("https://example.com");

Screenshot screenshot = ((ITakesScreenshot)driver).GetScreenshot();
screenshot.SaveAsFile("viewport.png");

driver.Quit();

The ITakeScreenshot method is specific to C#, but the underlying concept is the same as in Java's TakesScreenshot. Here is how to capture screenshots of specific elements using this method in C#.

var element = driver.FindElement(By.TagName("h1"));
var elementShot = ((ITakesScreenshot)element).GetScreenshot();
elementShot.SaveAsFile("element.png");

To take a screenshot in Selenium WebDriver using JavaScript, do this.

const { Builder } = require("selenium-webdriver");

(async function example() {
  let driver = await new Builder().forBrowser("chrome").build();
  await driver.get("https://example.com");

  await driver.takeScreenshot()
    .then(data => require("fs").writeFileSync("viewport.png", data, "base64"));

  await driver.quit();
})();

For an element screenshot in Selenium, the code looks like this.

let element = await driver.findElement({ css: "h1" });
await element.takeScreenshot(true)
  .then(data => require("fs").writeFileSync("element.png", data, "base64"));

Finally, here is an example of a screenshot in Selenium WebDriver using the Ruby programming language.

require "selenium-webdriver"

driver = Selenium::WebDriver.for :chrome
driver.navigate.to "https://example.com"

driver.save_screenshot("viewport.png")
driver.quit

As you can see, Ruby code is very concise. Even more so when taking screenshots of a particular element.

element = driver.find_element(tag_name: "h1")
element.save_screenshot("element.png")

Automating Screenshots on Test Failure

The screenshot function in Selenium is most useful when a test fails. It provides the necessary visual context to understand and fix the issue. Thus, the best approach is to automate taking screenshots upon failures to ensure that you are never left without this source of context.

A convenient way to automatically capture screenshots whenever a test fails in Java is to use TestNG, an open-source framework for automation testing. TestNG provides listeners that react to test events. The one we need is onTestFailure(). First, we create a TestNG Listener.

import org.openqa.selenium.*;
import org.testng.ITestListener;
import org.testng.ITestResult;
import org.openqa.selenium.io.FileHandler;

import java.io.File;
import java.io.IOException;

public class ScreenshotListener implements ITestListener {

    @Override
    public void onTestFailure(ITestResult result) {
        Object testClass = result.getInstance();
        WebDriver driver =
                ((BaseTest) testClass).driver;

        File src = ((TakesScreenshot) driver)
                .getScreenshotAs(OutputType.FILE);

        try {
            FileHandler.copy(
                src,
                new File("screenshots/" + result.getName() + ".png")
            );
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

Then we need to tell the listener to run by registering it. One approach is using @Listener annotations.

@Listeners(ScreenshotListener.class)
public class LoginTest extends BaseTest {
    // tests
}

TestNG annotations apply only to the specified test class. It might be more convenient to use testng.xml, which applies to all tests in the suite.

<listeners>
    <listener class-name="listeners.ScreenshotListener"/>
</listeners>

To automate taking screenshots in Python, we can use Pytest hooks. The first step is to add a hook to a conftest.py file.

import pytest

@pytest.hookimpl(hookwrapper=True)
def pytest_runtest_makereport(item, call):
    outcome = yield
    report = outcome.get_result()

    if report.when == "call" and report.failed:
        driver = item.funcargs["driver"]
        driver.save_screenshot(
            f"screenshots/{item.name}.png"
        )

Then, we provide the driver fixture to make the WebDriver Instance available to the hook for capturing screenshots upon failure.

from selenium import webdriver
import pytest

@pytest.fixture
def driver():
    driver = webdriver.Chrome()
    yield driver
    driver.quit()

With this setup, Pytest will automatically take a screenshot in Selenium WebDriver if the test fails.

Handling Screenshots in Headless Mode and Remote Drivers

Taking a screenshot in Selenium automatically is more challenging when you use headless browsers. In headless mode, browsers have no physical window; thus, they use the default window size to capture screenshots in all cases. The image can therefore be very small, blurry, or out of scale.

To avoid this, we can set the window size in advance. The outcome will be predictable, and the image will be big enough for most cases. Here is how to do it in Java.

ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new");
options.addArguments("--window-size=1920,1080");

WebDriver driver = new ChromeDriver(options);

The code example for Python would look like this.

options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
options.add_argument("--window-size=1920,1080")

driver = webdriver.Chrome(options=options)

When executing browser automation scripts on a remote machine using Selenium RemoteWebDriver, taking screenshots might fail. This happens because the remote machine needs screenshot capability to be explicitly enabled.

The solution is to add screenshot support to the remote driver at runtime. This is called augmenting RemoteWebDriver.

WebDriver driver = new RemoteWebDriver(gridUrl, capabilities);

WebDriver augmentedDriver =
        new Augmenter().augment(driver);

File screenshot = ((TakesScreenshot) augmentedDriver)
        .getScreenshotAs(OutputType.FILE);

This injects the missing screenshot interface to allow capturing the screenshot in Selenium RemoteWebDriver. Selenium 4 does this automatically in many cases, but older versions usually need it added manually as shown above.

There are also some browser-specific considerations. Only Firefox has native support to take a full-page screenshot, where by full-page we mean the entire scrollable page. Chrome and Edge can still take viewport screenshots. Safari has only limited headless support. Usually, it is better to use a different browser to capture screenshots remotely in Selenium.

Organizing and Managing Screenshot Files

Properly managing your screenshot files is a crucial part of test automation. One key consideration is how you name your image file. Files with generic and nonspecific names will quickly be overwritten.

To make files easier to filter, include the test name and timestamp. Adding a failure type would help to sort through data even more effectively. The recommended timestamp format does not include spaces or colons.

yyyyMMdd_HHmmss

The directory structure that enables easy management is separated by date and grouped by test class.

artifacts/
 └── screenshots/
     └── 2026-01-31/
         └── LoginTest/
             ├── invalidPassword_FAILED_142305.png
             ├── lockedUser_FAILED_142512.png

It is best to store screenshots as build artifacts, not as source files, to avoid bloated repos. To avoid clutter and noise, you also need to clean up or archive files after a set period of days. In most cases, 3-7 days should be enough.

Use Cases for Screenshots in Testing and Debugging

Taking a screenshot in Selenium is especially useful when you are dealing with a flaky test. Flaky tests are the ones that will pass in one WebDriver instance, but fail in another or fail every 10 or so runs.

A Selenium screenshot will help here because flaky tests are state-dependent. Screenshots will show you that state, allowing you to compare the passing and failing runs. For example, you might see pop-ups or cookie banners blocking a button in the failed test and thus easily identify the issue.

Screenshots are also important in validating UI state. For example, test assertions might verify that an HTML element exists and is clickable, implying a correct UI state. However, a screenshot might let you see a visual problem, such as a color contrast that makes an error message unreadable.

Visual differences across web applications and browsers are also exposed in screenshots. Text logic may pass in Chrome, Firefox, and Edge alike. But different browsers might display text or render fonts differently. Screenshots will also allow seeing layout shifts, alignment issues, text clipping, and other browser-specific UI issues.

Common Issues and How to Fix Them

When trying to take a screenshot in Selenium, you may get this error message instead.

java.lang.UnsupportedOperationException: Screenshots not supported

One possible fix is making sure that the driver you are using is the actual WebDriver instance.

TakesScreenshot ts = (TakesScreenshot) driver;
File src = ts.getScreenshotAs(OutputType.FILE);

You might need to enable the capability. This is especially common when using a cloud provider.

caps.setCapability("takesScreenshot", true);

If you are using the RemoteWebDriver, you might need to augment it as shown above.

Many other common issues, such as cropped or too-small images, are due to limitations of the headless driver.

When you are expecting a full-page screenshot to capture the entire page, but get only the visible part, as mentioned, this is because only Firefox can capture a full-page screenshot in Selenium.

Aside from using Firefox for your WebDriver instance, you can use a cross-browser stitching library, like AShot or Selenium-Shutterbug. These libraries will scroll the page, capturing multiple screenshots, and then stitch them together. This will work in remote and headless modes as well.

Finally, if you get an empty or blank element screenshot, it often means that the element is not in the viewport. To fix this, you can implement waiting for visibility.

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(ExpectedConditions.visibilityOf(element));

Summing Up

Screenshots are a crucial part of automating web applications and browsers. Taking a screenshot in Selenium helps identify what caused the test run to fail by showing how the WebDriver instance looked at the time of failure. While you may encounter common challenges when automating screenshot-taking, the fixes above will help you get back on the right track.