Failure Screenshots are screenshots captured automatically when a Selenium automation test fails. They provide visual evidence of the browser state at the time of failure and help testers understand what was displayed on the screen when an assertion, element interaction, navigation, synchronization, or other test step failed.
In Selenium TestNG frameworks, failure screenshots are commonly implemented using Selenium's TakesScreenshot interface together with TestNG's ITestListener. The listener can capture the browser state inside onTestFailure() before the WebDriver session is closed.
Failure screenshots are especially useful in CI/CD environments because the tester may not have direct access to the browser that executed the test. A screenshot saved as a test artifact can provide immediate visual evidence of the failed state.
Course Resource: Selenium Training | Register for Course Demo
A failure screenshot is an image captured from the browser when an automated test fails. It records the visible browser state at or near the time the failure is detected.
For example, suppose a Selenium test expects a successful login but the application displays an error message. The test may fail because the expected dashboard is not displayed. A failure screenshot can show the actual page, error message, popup, or other visible state.
Instead of investigating the failure only from logs, the QA engineer can inspect the screenshot and understand what the browser displayed.
Failure screenshots provide visual evidence that complements test logs, stack traces, assertions, and reports.
The basic failure screenshot workflow is:
TestNG starts test
|
v
Selenium executes test steps
|
v
Assertion / WebDriver operation fails
|
v
TestNG marks test as failed
|
v
ITestListener.onTestFailure()
|
v
Get WebDriver instance
|
v
TakesScreenshot
|
v
Capture screenshot
|
v
Save PNG file
|
v
Attach / publish screenshot
|
v
Test Report
Selenium provides the TakesScreenshot interface for screenshot capture. A WebDriver implementation that supports screenshot capture can be cast to this interface and used with getScreenshotAs().
import org.openqa.selenium.OutputType;
import org.openqa.selenium.TakesScreenshot;
import org.openqa.selenium.WebDriver;
TakesScreenshot screenshot = (TakesScreenshot) driver;
File source = screenshot.getScreenshotAs(OutputType.FILE);
The captured result can be returned as a file, byte array, or Base64 representation depending on the selected Selenium output type.
The simplest approach is to capture a screenshot manually inside a test or utility method.
File source = ((TakesScreenshot) driver)
.getScreenshotAs(OutputType.FILE);
The returned file should then be copied to a permanent destination if it needs to be retained after the test execution.
A screenshot should normally be stored in a dedicated directory such as screenshots, test-output/screenshots, or test-artifacts/screenshots.
File source = ((TakesScreenshot) driver)
.getScreenshotAs(OutputType.FILE);
File destination = new File(
"screenshots/failure.png"
);
FileUtils.copyFile(source, destination);
In production frameworks, use a unique filename so that one failed test does not overwrite the screenshot produced by another test.
Apache Commons IO is commonly used in Java Selenium projects to copy the temporary screenshot file to a permanent location.
import org.apache.commons.io.FileUtils;
import org.openqa.selenium.OutputType;
import org.openqa.selenium.TakesScreenshot;
File source = ((TakesScreenshot) driver)
.getScreenshotAs(OutputType.FILE);
FileUtils.copyFile(
source,
new File("screenshots/failure.png")
);
A timestamp can be included in the filename to prevent screenshots from being overwritten.
String timestamp = new SimpleDateFormat(
"yyyyMMdd_HHmmss"
).format(new Date());
File source = ((TakesScreenshot) driver)
.getScreenshotAs(OutputType.FILE);
File destination = new File(
"screenshots/failure_" + timestamp + ".png"
);
FileUtils.copyFile(source, destination);
A timestamp is especially useful when the same test is executed repeatedly.
Including the test method name makes it easier to identify which test generated the screenshot.
String methodName = result.getName();
String timestamp = new SimpleDateFormat(
"yyyyMMdd_HHmmss"
).format(new Date());
String fileName = methodName
+ "_" + timestamp
+ ".png";
A typical filename might look like:
loginTest_20261001_132100.pngITestListener is a TestNG listener interface that provides callback methods for different test execution events.
One of its most useful methods for screenshot automation is onTestFailure().
public class FailureScreenshotListener
implements ITestListener {
@Override
public void onTestFailure(ITestResult result) {
System.out.println("Test failed");
}
}
The listener can be used to automatically execute screenshot logic whenever a test fails.
The onTestFailure() callback is invoked when TestNG reports a failed test result. It receives an ITestResult object containing information about the failed test.
@Override
public void onTestFailure(ITestResult result) {
System.out.println(
"Failed Test: " + result.getName()
);
}
The result object can be used to obtain the test method name, test class, parameters, and other execution information.
import java.io.File;
import org.apache.commons.io.FileUtils;
import org.openqa.selenium.OutputType;
import org.openqa.selenium.TakesScreenshot;
import org.openqa.selenium.WebDriver;
import org.testng.ITestListener;
import org.testng.ITestResult;
public class FailureScreenshotListener
implements ITestListener {
private WebDriver driver;
@Override
public void onTestFailure(ITestResult result) {
System.out.println(
"Test Failed: " + result.getName()
);
if (driver instanceof TakesScreenshot) {
File source =
((TakesScreenshot) driver)
.getScreenshotAs(OutputType.FILE);
try {
FileUtils.copyFile(
source,
new File(
"screenshots/"
+ result.getName()
+ ".png"
)
);
} catch (Exception e) {
e.printStackTrace();
}
}
}
}
In a real framework, the listener should obtain the correct WebDriver instance associated with the failed test rather than maintaining an unsafe shared driver field.
The screenshot should be captured while the WebDriver session is still active. If the browser has already been closed using driver.quit(), the listener may no longer be able to capture the browser state.
Test fails
|
v
onTestFailure()
|
v
Capture Screenshot
|
v
Save Screenshot
|
v
@AfterMethod
|
v
driver.quit()
This ordering is important for reliable failure evidence.
TestNG frameworks commonly use @AfterMethod for browser cleanup.
@AfterMethod(alwaysRun = true)
public void tearDown() {
if (driver != null) {
driver.quit();
}
}
The failure listener should capture the screenshot while the browser is still available, and teardown should perform cleanup afterward.
| Manual Screenshot | Automatic Failure Screenshot |
|---|---|
| Developer explicitly calls screenshot method | Listener captures screenshot automatically |
| Useful at selected checkpoints | Useful for failed tests |
| Requires code inside test flow | Centralized implementation |
| Can capture successful states | Usually captures failure states |
| More repetitive | More reusable |
TestNG allows listeners to be registered using the @Listeners annotation.
import org.testng.annotations.Listeners;
@Listeners(FailureScreenshotListener.class)
public class LoginTest {
@Test
public void loginTest() {
// Test steps
}
}
The listener can also be placed on a shared base class when the project architecture is designed to apply the listener to the relevant test classes.
A listener can also be registered in the TestNG XML suite configuration.
<suite name="Automation Suite">
<listeners>
<listener
class-name="listeners.FailureScreenshotListener"/>
</listeners>
<test name="UI Tests">
<classes>
<class name="tests.LoginTest"/>
</classes>
</test>
</suite>
XML registration is useful when the same listener should apply across many test classes.
Instead of writing screenshot code repeatedly, create a reusable utility class.
public class ScreenshotUtil {
public static void capture(
WebDriver driver,
String fileName) {
try {
File source =
((TakesScreenshot) driver)
.getScreenshotAs(OutputType.FILE);
File destination =
new File(
"screenshots/" + fileName
);
FileUtils.copyFile(
source,
destination
);
} catch (Exception e) {
e.printStackTrace();
}
}
}
@Test
public void loginTest() {
driver.get(
"https://example.com/login"
);
try {
driver.findElement(
By.id("username")
).sendKeys("admin");
driver.findElement(
By.id("password")
).sendKeys("wrong");
driver.findElement(
By.id("loginButton")
).click();
} catch (Exception e) {
ScreenshotUtil.capture(
driver,
"login_failure.png"
);
throw e;
}
}
Although this approach works, a listener is usually more convenient for framework-wide automatic failure screenshots.
The ITestResult object can provide the failed test's method name.
@Override
public void onTestFailure(ITestResult result) {
String testName =
result.getMethod()
.getMethodName();
System.out.println(
"Failed Test: " + testName
);
}
This value can be incorporated into the screenshot filename.
Screenshot filenames should be unique, especially when tests run in parallel.
String className =
result.getTestClass()
.getName();
String methodName =
result.getMethod()
.getMethodName();
String fileName =
className.replace(".", "_")
+ "_"
+ methodName
+ "_"
+ System.currentTimeMillis()
+ ".png";
A robust filename can contain the class name, method name, timestamp, thread ID, and retry information when required.
Parallel test execution can cause multiple tests to fail at approximately the same time. A thread ID can help create unique filenames.
long threadId =
Thread.currentThread().getId();
String fileName =
result.getName()
+ "_thread_"
+ threadId
+ "_"
+ System.currentTimeMillis()
+ ".png";
A clean directory structure makes screenshots easier to locate.
test-artifacts
|
|-- screenshots
| |-- LoginTest
| | |-- loginTest_001.png
| | |-- loginTest_002.png
| |
| |-- SearchTest
| |-- searchTest_001.png
| |-- searchTest_002.png
|
|-- reports
| |-- testng-results.xml
| |-- index.html
A screenshot file and a test report are separate artifacts. Capturing a PNG does not automatically mean that every report format will embed that image.
A reporting framework can provide an attachment mechanism, or a custom HTML report can create a relative link to the screenshot.
Test Result
|
+-- PASS
|
+-- FAIL
|
+-- Error Message
+-- Stack Trace
+-- Screenshot
+-- Test Data
A simple HTML report can link to a screenshot using a relative path.
<a href="screenshots/loginTest_failure.png"
target="_blank">
View Failure Screenshot
</a>
The screenshot and report should be published together so that the relative path remains valid.
Selenium can also return a screenshot as Base64 data.
String screenshot =
((TakesScreenshot) driver)
.getScreenshotAs(
OutputType.BASE64
);
Base64 can be useful when a reporting library accepts encoded image data directly.
Another option is to obtain the screenshot as bytes.
byte[] screenshot =
((TakesScreenshot) driver)
.getScreenshotAs(
OutputType.BYTES
);
Byte arrays can be useful for APIs or reporting systems that accept image data without requiring a temporary file.
| Output Type | Purpose |
|---|---|
| OutputType.FILE | Returns screenshot as a file |
| OutputType.BYTES | Returns screenshot as byte data |
| OutputType.BASE64 | Returns screenshot as Base64 encoded data |
import java.io.File;
import java.text.SimpleDateFormat;
import java.util.Date;
import org.apache.commons.io.FileUtils;
import org.openqa.selenium.OutputType;
import org.openqa.selenium.TakesScreenshot;
import org.openqa.selenium.WebDriver;
import org.testng.ITestListener;
import org.testng.ITestResult;
public class FailureScreenshotListener
implements ITestListener {
@Override
public void onTestFailure(
ITestResult result) {
Object testInstance =
result.getInstance();
if (!(testInstance
instanceof BaseTest)) {
return;
}
WebDriver driver =
((BaseTest) testInstance)
.getDriver();
if (!(driver instanceof TakesScreenshot)) {
return;
}
try {
String timestamp =
new SimpleDateFormat(
"yyyyMMdd_HHmmss"
).format(new Date());
String methodName =
result.getMethod()
.getMethodName();
File source =
((TakesScreenshot) driver)
.getScreenshotAs(
OutputType.FILE
);
File destination =
new File(
"test-artifacts/screenshots/"
+ methodName
+ "_"
+ timestamp
+ ".png"
);
FileUtils.copyFile(
source,
destination
);
System.out.println(
"Screenshot saved: "
+ destination.getAbsolutePath()
);
} catch (Exception e) {
System.err.println(
"Screenshot capture failed: "
+ e.getMessage()
);
}
}
}
A base test class can expose the WebDriver instance to the listener.
public class BaseTest {
protected WebDriver driver;
public WebDriver getDriver() {
return driver;
}
@BeforeMethod
public void setUp() {
driver = new ChromeDriver();
driver.manage()
.window()
.maximize();
}
@AfterMethod(alwaysRun = true)
public void tearDown() {
if (driver != null) {
driver.quit();
driver = null;
}
}
}
@Listeners(FailureScreenshotListener.class)
public class LoginTest extends BaseTest {
@Test
public void loginTest() {
driver.get(
"https://example.com/login"
);
driver.findElement(
By.id("username")
).sendKeys("admin");
driver.findElement(
By.id("password")
).sendKeys("wrong");
driver.findElement(
By.id("loginButton")
).click();
Assert.assertTrue(
driver.getTitle()
.contains("Dashboard")
);
}
}
If the assertion fails, the listener can capture the browser state before the driver is closed by teardown.
Failure screenshots are particularly useful when assertions fail.
String actualTitle =
driver.getTitle();
Assert.assertEquals(
actualTitle,
"Dashboard"
);
If the actual title is different, the screenshot can show the page that was actually displayed at the time of failure.
A screenshot can also help investigate NoSuchElementException failures.
driver.findElement(
By.id("loginButton")
).click();
If the element is missing, the screenshot may show an unexpected page, loading state, popup, error message, or changed UI.
Synchronization failures can also benefit from screenshots.
WebDriverWait wait =
new WebDriverWait(
driver,
Duration.ofSeconds(10)
);
wait.until(
ExpectedConditions
.visibilityOfElementLocated(
By.id("dashboard")
)
);
If the expected element does not appear, a screenshot can provide additional information about the browser state.
Assert.assertEquals(
driver.getCurrentUrl(),
"https://example.com/dashboard"
);
A failure screenshot can help determine whether the application displayed an error page, login page, redirect page, or another unexpected screen.
Assert.assertEquals(
driver.getTitle(),
"Dashboard"
);
The screenshot provides visual evidence in addition to the assertion failure message.
Login automation is one of the most common use cases.
@DataProvider(name = "loginData")
public Object[][] loginData() {
return new Object[][] {
{"admin", "admin123"},
{"manager", "manager123"},
{"invalid", "wrong123"}
};
}
@Test(dataProvider = "loginData")
public void loginTest(
String username,
String password) {
driver.findElement(
By.id("username")
).sendKeys(username);
driver.findElement(
By.id("password")
).sendKeys(password);
driver.findElement(
By.id("loginButton")
).click();
Assert.assertTrue(
driver.getTitle()
.contains("Dashboard")
);
}
When a particular data set fails, the framework should make it possible to identify the corresponding screenshot without exposing sensitive credentials.
Data Providers create multiple test invocations from different data sets. When screenshots are captured, filenames should distinguish different invocations.
loginTest_admin_001.png
loginTest_manager_002.png
loginTest_invalid_003.png
Do not include passwords, tokens, session identifiers, or other secrets in filenames.
Parallel execution requires special attention because multiple WebDriver sessions may be active at the same time.
Thread 1
|
+-- Chrome
+-- LoginTest
+-- failure_001.png
Thread 2
|
+-- Firefox
+-- SearchTest
+-- failure_002.png
Thread 3
|
+-- Edge
+-- CheckoutTest
+-- failure_003.png
Each test invocation should have access to its own WebDriver instance, and screenshot filenames should be unique.
A common framework approach for parallel Selenium execution is to maintain a WebDriver instance per thread.
public class DriverManager {
private static ThreadLocal<WebDriver>
driver = new ThreadLocal<>();
public static void setDriver(
WebDriver webDriver) {
driver.set(webDriver);
}
public static WebDriver getDriver() {
return driver.get();
}
public static void quitDriver() {
if (driver.get() != null) {
driver.get().quit();
driver.remove();
}
}
}
This architecture helps the screenshot listener obtain the driver associated with the correct execution context.
A parallel-safe screenshot filename can include class, method, thread, timestamp, and a unique identifier.
String fileName =
result.getTestClass()
.getName()
+ "_"
+ result.getMethod()
.getMethodName()
+ "_thread_"
+ Thread.currentThread().getId()
+ "_"
+ System.currentTimeMillis()
+ ".png";
Some TestNG frameworks retry failed tests. When retries are used, decide whether each failed attempt should produce a separate screenshot.
Attempt 1
|
+-- FAIL
+-- screenshot_attempt_1.png
|
v
Retry
|
Attempt 2
|
+-- FAIL
+-- screenshot_attempt_2.png
Keeping separate screenshots can be useful when investigating flaky tests because each attempt may show a different browser state.
A flaky test may pass during one execution and fail during another. Failure screenshots can help compare the visual state of different failed executions.
Unexpected JavaScript alerts can interfere with screenshot commands and WebDriver interactions. The framework should handle such situations carefully and preserve the original failure information.
try {
driver.findElement(
By.id("submit")
).click();
} catch (Exception e) {
ScreenshotUtil.capture(
driver,
"alert_failure.png"
);
throw e;
}
If a test opens multiple browser windows or tabs, the screenshot represents the current WebDriver context. The framework should make sure the correct window is selected before attempting the capture.
String mainWindow =
driver.getWindowHandle();
for (String handle :
driver.getWindowHandles()) {
driver.switchTo()
.window(handle);
}
When working with iframes, the current WebDriver context matters. A screenshot may reflect the current browser state, while an element-level screenshot can target a specific element.
driver.switchTo()
.frame("paymentFrame");
driver.findElement(
By.id("cardNumber")
).sendKeys("1234");
A standard WebDriver screenshot should not automatically be treated as a guaranteed full-page capture. The captured area can depend on the browser, driver, implementation, and capture method.
For ordinary failure debugging, the visible browser state is often useful. If complete-page evidence is required, use a browser or framework capability that explicitly supports the desired full-page behavior.
Selenium can also capture a screenshot of an individual element when supported by the WebElement screenshot functionality.
WebElement logo =
driver.findElement(
By.id("logo")
);
File source =
logo.getScreenshotAs(
OutputType.FILE
);
Element screenshots are useful when the failure is specifically related to one component of the page.
| Failure Screenshot | Success Screenshot |
|---|---|
| Captured when test fails | Captured when test passes or at selected checkpoints |
| Primarily for debugging | Primarily for evidence or documentation |
| Reduces unnecessary files | Can produce many artifacts |
| Useful in CI/CD | Useful for business evidence |
A framework should define where screenshots are stored and how long they are retained.
Project
|
|-- test-artifacts
| |-- screenshots
| |-- logs
| |-- reports
|
|-- src
| |-- test
| |-- java
| |-- resources
For CI systems, the screenshot directory should be configured as a build artifact when the project requires screenshots to remain accessible after the workspace is cleaned.
Jenkins can publish test results and retain build artifacts. Screenshot files should be stored in a predictable directory and configured as artifacts when they need to be available after the build.
Jenkins Job
|
v
Checkout Code
|
v
Maven Build
|
v
TestNG Tests
|
v
Failure
|
v
Screenshot
|
v
test-artifacts/screenshots
|
v
Publish Artifacts
|
v
Jenkins Build Results
Publishing the test result and publishing screenshot files are separate concerns; both should be configured when visual failure evidence is required.
A Maven-based Selenium TestNG project can store screenshots under the build output directory.
mvn clean testA common project structure is:
target
|
|-- test-output
| |-- screenshots
| |-- reports
|
|-- surefire-reports
Developer Commit
|
v
CI Pipeline
|
v
Build
|
v
Execute Tests
|
+---- PASS
|
+---- FAIL
|
v
Capture Screenshot
|
v
Save Test Artifact
|
v
Generate Report
|
v
Publish Results
Screenshots should complement logs rather than replace them.
| Evidence | Provides |
|---|---|
| Screenshot | Visual browser state |
| Log | Execution information |
| Stack Trace | Technical failure location |
| Test Report | Overall execution result |
| Test Data | Input used for execution |
Screenshots can contain sensitive information such as usernames, personal information, tokens, account details, or business data. Test frameworks should consider the sensitivity of captured browser content.
The screenshot operation is diagnostic support. If screenshot capture itself fails, it should not replace the original assertion or WebDriver failure.
try {
captureScreenshot(driver);
} catch (Exception screenshotError) {
System.err.println(
"Screenshot failed: "
+ screenshotError.getMessage()
);
}
// Preserve the original test failure
This approach helps keep the original failure as the primary diagnostic information.
try {
File source =
((TakesScreenshot) driver)
.getScreenshotAs(
OutputType.FILE
);
FileUtils.copyFile(
source,
destination
);
} catch (Exception e) {
System.err.println(
"Unable to capture screenshot: "
+ e.getMessage()
);
}
Capture errors can occur when the browser session has already ended, the driver does not support the requested operation, the destination cannot be written, or another runtime problem occurs.
public class ScreenshotUtil {
public static String capture(
WebDriver driver,
String testName) {
String timestamp =
new SimpleDateFormat(
"yyyyMMdd_HHmmss"
).format(new Date());
String fileName =
testName
+ "_"
+ timestamp
+ ".png";
File destination =
new File(
"test-artifacts/screenshots/"
+ fileName
);
try {
File source =
((TakesScreenshot) driver)
.getScreenshotAs(
OutputType.FILE
);
FileUtils.copyFile(
source,
destination
);
return destination
.getAbsolutePath();
} catch (Exception e) {
System.err.println(
"Screenshot failed: "
+ e.getMessage()
);
return null;
}
}
}
TestNG
|
v
Test Execution
|
v
Test Failure
|
v
ITestListener
|
v
onTestFailure()
|
v
Identify Test Instance
|
v
Get WebDriver
|
v
TakesScreenshot
|
v
Capture Image
|
v
Unique File Name
|
v
Save Test Artifact
|
+--------+--------+
| |
v v
HTML Report CI Artifact
| |
+--------+--------+
|
v
Test Evidence
src
|-- test
|-- java
|-- tests
| |-- LoginTest.java
| |-- SearchTest.java
| |-- CheckoutTest.java
|
|-- listeners
| |-- FailureScreenshotListener.java
|
|-- utilities
| |-- ScreenshotUtil.java
| |-- DriverManager.java
|
|-- base
|-- BaseTest.java
test-artifacts
|-- screenshots
|-- reports
|-- logs
import java.io.File;
import java.text.SimpleDateFormat;
import java.util.Date;
import org.apache.commons.io.FileUtils;
import org.openqa.selenium.By;
import org.openqa.selenium.OutputType;
import org.openqa.selenium.TakesScreenshot;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.testng.Assert;
import org.testng.ITestListener;
import org.testng.ITestResult;
import org.testng.annotations.AfterMethod;
import org.testng.annotations.BeforeMethod;
import org.testng.annotations.Listeners;
import org.testng.annotations.Test;
@Listeners(FailureScreenshotListener.class)
public class LoginTest {
private WebDriver driver;
@BeforeMethod
public void setUp() {
driver = new ChromeDriver();
driver.manage()
.window()
.maximize();
driver.get(
"https://example.com/login"
);
}
@Test
public void loginTest() {
driver.findElement(
By.id("username")
).sendKeys("admin");
driver.findElement(
By.id("password")
).sendKeys("admin123");
driver.findElement(
By.id("loginButton")
).click();
Assert.assertTrue(
driver.getTitle()
.contains("Dashboard")
);
}
public WebDriver getDriver() {
return driver;
}
@AfterMethod(alwaysRun = true)
public void tearDown() {
if (driver != null) {
driver.quit();
driver = null;
}
}
}
import java.io.File;
import org.apache.commons.io.FileUtils;
import org.openqa.selenium.OutputType;
import org.openqa.selenium.TakesScreenshot;
import org.openqa.selenium.WebDriver;
import org.testng.ITestListener;
import org.testng.ITestResult;
public class FailureScreenshotListener
implements ITestListener {
@Override
public void onTestFailure(
ITestResult result) {
try {
Object instance =
result.getInstance();
if (!(instance
instanceof LoginTest)) {
return;
}
LoginTest test =
(LoginTest) instance;
WebDriver driver =
test.getDriver();
if (!(driver instanceof TakesScreenshot)) {
return;
}
File source =
((TakesScreenshot) driver)
.getScreenshotAs(
OutputType.FILE
);
String testName =
result.getMethod()
.getMethodName();
File destination =
new File(
"test-artifacts/screenshots/"
+ testName
+ "_"
+ System.currentTimeMillis()
+ ".png"
);
FileUtils.copyFile(
source,
destination
);
System.out.println(
"Failure screenshot saved: "
+ destination
.getAbsolutePath()
);
} catch (Exception e) {
System.err.println(
"Could not capture failure screenshot: "
+ e.getMessage()
);
}
}
}
Failure screenshots become even more useful when a Data Provider executes the same test with multiple data sets.
@DataProvider(name = "products")
public Object[][] products() {
return new Object[][] {
{"Laptop"},
{"Mobile"},
{"Tablet"},
{"Headphones"}
};
}
@Test(dataProvider = "products")
public void searchTest(String product) {
driver.findElement(
By.id("search")
).sendKeys(product);
driver.findElement(
By.id("searchButton")
).click();
Assert.assertTrue(
driver.getTitle()
.contains(product)
);
}
A robust framework can include a sanitized product identifier in the screenshot filename so the failed data set is easier to identify.
Failure screenshots can be integrated with the Page Object Model. The page classes handle browser interaction while the listener handles failure evidence.
Test Class
|
v
Page Object
|
v
Selenium WebDriver
|
v
Application
|
v
Failure
|
v
TestNG Listener
|
v
Screenshot Utility
This separation keeps screenshot management independent from page-specific Selenium interactions.
Reporting tools can provide richer ways to display screenshots alongside test results. The exact attachment mechanism depends on the reporting library and project configuration.
A common architecture is:
TestNG
|
+-- Test Result
|
+-- Failure Details
|
+-- Screenshot
|
+-- Logs
|
v
Automation Report
When using a third-party reporting library, follow that library's supported screenshot attachment API rather than assuming that saving a PNG automatically embeds it into the report.
Regression suites can contain hundreds or thousands of automated tests. Automatically capturing screenshots only when tests fail can provide useful debugging evidence without generating screenshots for every successful execution.
For regression automation, combine screenshots with:
When the same test executes on Chrome, Firefox, and Edge, the screenshot filename should identify the browser.
LoginTest_Chrome_failure.png
LoginTest_Firefox_failure.png
LoginTest_Edge_failure.png
This makes browser-specific failures easier to investigate.
TestNG
|
+-----------+-----------+
| | |
Chrome Firefox Edge
| | |
v v v
Test A Test A Test A
| | |
v v v
Failure Pass Failure
| |
v v
Screenshot Screenshot
| |
+-----------+-----------+
|
v
Report
Testing across QA, staging, and production-like environments can create similar failures with different visual states. The environment name can be included in the screenshot path.
screenshots
|
|-- QA
| |-- LoginTest_failure.png
|
|-- Stage
| |-- LoginTest_failure.png
|
|-- Production
|-- LoginTest_failure.png
For large automation suites, it can be useful to record browser information alongside screenshot metadata.
Browser: Chrome
Environment: QA
Test: LoginTest
Method: validLogin
Thread: 4
Timestamp: 20261001_132100
Screenshot: LoginTest_validLogin_4.png
This information can be stored in logs or reports without putting unnecessary sensitive information into the image filename.
E-commerce applications contain many workflows where failure screenshots are valuable.
Search
|
v
Product
|
v
Cart
|
v
Checkout
|
v
Payment
|
v
Confirmation
|
+---- Failure Screenshot
Forms are another common use case because visual evidence can show validation messages and incorrectly displayed fields.
Registration Form
|
+-- Name
+-- Email
+-- Mobile
+-- Password
+-- Confirm Password
|
v
Submit
|
v
Validation
|
+-- PASS
|
+-- FAIL
|
v
Failure Screenshot
UI automation often verifies visibility, text, buttons, labels, menus, images, and page layouts. A screenshot can provide useful visual context when such checks fail.
Assert element visible
|
v
Element missing
|
v
Test Failure
|
v
Screenshot
|
v
Visual Investigation
Home
|
v
Login
|
v
Dashboard
|
v
Profile
|
v
Settings
|
v
Unexpected Page
|
v
Failure Screenshot
The screenshot can help determine which page was displayed when navigation validation failed.
Screenshot files can accumulate rapidly in large test suites. Define a retention strategy for local and CI environments.
Screenshot capture adds file-generation and storage work when a failure occurs. In normal failure-only designs, successful tests do not generate screenshot files.
For very large suites, avoid unnecessarily capturing multiple copies of the same failure and keep the listener lightweight.
| Problem | Possible Cause | Solution |
|---|---|---|
| No screenshot | Listener not registered | Check @Listeners or testng.xml |
| No screenshot | Driver is null | Initialize driver before test |
| No screenshot | Driver already closed | Capture before quit() |
| Files overwritten | Duplicate filename | Use timestamp/UUID/thread ID |
| Screenshot not in CI | Artifact not published | Publish screenshot directory |
| Wrong browser screenshot | Shared driver | Use isolated driver instances |
| Blank/incomplete image | Browser state or capture limitation | Check browser state and capture timing |
| Original failure hidden | Screenshot exception replaces failure | Handle screenshot exception separately |
A failure screenshot is an image captured from the browser when an automated test fails.
The TakesScreenshot interface is commonly used for browser screenshot capture.
The getScreenshotAs() method is used to obtain screenshot output.
onTestFailure(ITestResult result) is commonly used.
Because the browser session needs to remain available for the screenshot operation.
It can be registered using @Listeners or through testng.xml.
Unique names prevent one failure from overwriting another screenshot.
A Java date/time formatter or another unique identifier can be included in the filename.
Yes. Screenshot filenames can identify the test invocation while avoiding sensitive test data.
Yes. Screenshot handling can remain in a listener or utility while page objects manage application interactions.
Yes, but each test invocation should use an appropriate isolated WebDriver and unique screenshot destination.
It requests the screenshot as a file representation.
It returns the screenshot as byte data, which can be useful for report attachment APIs.
It returns the screenshot as Base64 encoded data.
No. Saving the image and attaching or linking it in a particular report are separate operations.
The original test failure contains the primary diagnostic information and should remain visible even if screenshot capture fails.
Yes. The screenshot directory can be retained and published as a build artifact.
Passwords, tokens, session identifiers, and other sensitive information should not be included.
They provide visual evidence when the browser executes on a remote build agent where the tester cannot directly observe the browser.
They provide reusable visual evidence automatically whenever a test fails, reducing the need for manual reproduction.
| Concept | Description |
|---|---|
| TakesScreenshot | Selenium interface for screenshot capture |
| getScreenshotAs() | Captures screenshot output |
| OutputType.FILE | Returns screenshot as a file |
| OutputType.BYTES | Returns screenshot bytes |
| OutputType.BASE64 | Returns Base64 screenshot data |
| ITestListener | TestNG listener interface |
| onTestFailure() | Callback used for failed-test handling |
| @Listeners | Registers a TestNG listener |
| testng.xml | Can register listeners at suite level |
| Screenshot Utility | Reusable screenshot capture component |
| ThreadLocal WebDriver | Common approach for thread-specific drivers |
| CI Artifact | Persistent build output such as screenshots |
Suppose a checkout test fails because the expected confirmation message is not displayed.
Checkout Test
|
v
Add Product
|
v
Open Cart
|
v
Checkout
|
v
Place Order
|
v
Assert Confirmation
|
X
Test Failed
|
v
ITestListener
|
v
Failure Screenshot
|
+-- Browser State
+-- Error Message
+-- Test Name
+-- Timestamp
|
v
Report / CI Artifact
The QA engineer can inspect the screenshot together with the stack trace and logs to understand what happened during the failed execution.
Selenium Test Framework
|
+-------------------+-------------------+
| | |
Tests Page Objects Utilities
| | |
| | +--------+--------+
| | | |
| | Driver Screenshot
| | Manager Utility
| | | |
+-------------------+----------+-----------------+
|
v
TestNG
|
v
ITestListener
|
v
Failure Screenshot
|
+---------+---------+
| |
v v
Report CI Artifact
Failure screenshots are an important part of a professional Selenium automation framework because they provide visual evidence of the browser state when an automated test fails.
Selenium provides the TakesScreenshot interface and getScreenshotAs() method for screenshot capture. TestNG's ITestListener and onTestFailure() provide a convenient mechanism for automatically triggering screenshot capture when tests fail.
A robust implementation should capture the screenshot while the WebDriver session is still active, save the image to a durable and predictable location, use unique filenames, and publish the screenshot with the test results when required.
For advanced Selenium frameworks, failure screenshots can be combined with Page Object Model, Data Providers, parallel execution, reusable Driver Managers, Maven, CI/CD, Jenkins, logs, and reporting systems.
Failure Screenshots = Test Failure + Visual Evidence.
A good Selenium framework should not only tell the team that a test failed; it should also make it easier to understand what the browser looked like at the time of failure. By combining Selenium screenshot capabilities with TestNG listeners, reusable utilities, proper WebDriver management, unique filenames, and CI artifact publishing, failure investigation becomes more structured and efficient.
Learn more about Selenium automation, WebDriver, TestNG, Page Object Model, and related automation testing concepts:
Quick Revision: Use TakesScreenshot to capture screenshots, use ITestListener.onTestFailure() for automatic failure handling, capture before driver.quit(), use unique filenames, keep WebDriver thread-safe for parallel execution, preserve the original failure, and publish screenshots as test artifacts when running automation in CI/CD.
