How to Take Screenshots on Test Failures Using CaptureHelpers in automationframeworkselenium

The automationframeworkselenium framework automatically captures screenshots on test failures by enabling the SCREENSHOT_FAILED_TCS flag in config.properties, which triggers the TestListener to invoke CaptureHelpers.captureScreenshot() and embed the image into both Extent and Allure reports.

The anhtester/automationframeworkselenium project provides a robust mechanism for capturing visual evidence when tests fail. By leveraging the CaptureHelpers utility class combined with TestNG listeners, the framework automates screenshot generation without requiring manual intervention in every test method.

Architecture of the Screenshot System

CaptureHelpers Utility

Located in src/main/java/com/anhtester/helpers/CaptureHelpers.java, this class handles the low-level screenshot operations. It interfaces with Selenium's TakesScreenshot interface, manages directory creation using SystemHelpers.getCurrentDir(), and generates timestamped PNG files with the pattern <testName>_<dd-MM-yyyy HH-mm-ss>.png.

TestListener for Extent Reports

The src/test/java/com/anhtester/listeners/TestListener.java implements TestNG's ITestListener interface. Its onTestFailure(ITestResult iTestResult) method checks the screenshot configuration flag and orchestrates the capture process, subsequently attaching the image to Extent reports via ExtentReportManager.addScreenShot(Status.FAIL, testName).

AllureListener for Allure Reports

Independently, src/test/java/com/anhtester/listeners/AllureListener.java attaches screenshots to Allure reports when tests fail. This operates separate from the Extent reporting flow, ensuring visual evidence appears regardless of which reporting tool you use.

Configuring Screenshot Capture on Failure

The framework uses src/test/resources/config/config.properties to control behavior:

SCREENSHOT_FAILED_TCS = yes

The FrameworkConstants.java file reads this value at startup:

public static final String SCREENSHOT_FAILED_TCS = PropertiesHelpers.getValue("SCREENSHOT_FAILED_TCS");

When set to yes, the listeners trigger automatic capture; any other value disables the feature.

How the Screenshot Mechanism Works

When a test fails, the following sequence executes:

1. TestListener triggers: The onTestFailure(ITestResult iTestResult) method in TestListener.java receives the failure event.

2. Configuration check: The listener verifies SCREENSHOT_FAILED_TCS.equals("yes") before proceeding.

3. Screenshot capture: It calls CaptureHelpers.captureScreenshot(DriverManager.getDriver(), getTestName(iTestResult)), which:

   • Resolves the export path using SystemHelpers.getCurrentDir() + FrameworkConstants.EXPORT_CAPTURE_PATH
   • Creates the directory if missing using file.mkdir()
   • Captures via ((TakesScreenshot) driver).getScreenshotAs(OutputType.FILE)
   • Saves the file with a timestamped name

4. Extent Report attachment: The listener adds the image using ExtentReportManager.addScreenShot(Status.FAIL, getTestName(iTestResult)).

5. Allure attachment: Simultaneously, AllureListener attaches the screenshot to the Allure result files.

Implementation Examples

Manual Screenshot Capture

To capture screenshots outside the automatic failure flow:

import com.anhtester.helpers.CaptureHelpers;
import com.anhtester.driver.DriverManager;

public void customVerification() {
    // Perform test steps
    if (validationFailed) {
        CaptureHelpers.captureScreenshot(DriverManager.getDriver(), "CustomVerification_Failed");
    }
}

Verifying Screenshot Files

You can verify the saved files using standard Java file operations:

import com.anhtester.helpers.SystemHelpers;
import com.anhtester.constants.FrameworkConstants;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.text.SimpleDateFormat;
import java.util.Date;

@Test
public void verifyScreenshotExists() {
    String testName = "validationTest";
    CaptureHelpers.captureScreenshot(DriverManager.getDriver(), testName);
    
    String timestamp = new SimpleDateFormat("dd-MM-yyyy HH-mm-ss").format(new Date());
    Path screenshotPath = Paths.get(
        SystemHelpers.getCurrentDir(),
        FrameworkConstants.EXPORT_CAPTURE_PATH,
        testName + "_" + timestamp + ".png"
    );
    
    assertTrue(Files.exists(screenshotPath), "Screenshot should exist");
}

Customizing the Listener

Extend the default behavior by modifying TestListener.java:

@Override
public void onTestFailure(ITestResult iTestResult) {
    if (SCREENSHOT_FAILED_TCS.equals(YES)) {
        String prefixedName = "FAIL_" + getTestName(iTestResult);
        CaptureHelpers.captureScreenshot(DriverManager.getDriver(), prefixedName);
        ExtentReportManager.addScreenShot(Status.FAIL, prefixedName);
    }
}

Summary

• Set SCREENSHOT_FAILED_TCS = yes in src/test/resources/config/config.properties to enable automatic capture
• The TestListener class automatically invokes CaptureHelpers.captureScreenshot() when tests fail
• Screenshots are saved to the path defined in FrameworkConstants.EXPORT_CAPTURE_PATH (default: ./reports/screenshots)
• Images are automatically embedded into both Extent and Allure reports
• Use CaptureHelpers.captureScreenshot() manually for custom capture scenarios outside test failures

Frequently Asked Questions

How do I enable screenshots only for failed tests?

Set the SCREENSHOT_FAILED_TCS property to yes in config.properties. The TestListener checks this flag in its onTestFailure() method before calling CaptureHelpers.captureScreenshot(), ensuring screenshots are taken only when assertions fail.

Where are the screenshots saved?

Screenshots are saved to the directory specified by FrameworkConstants.EXPORT_CAPTURE_PATH, which defaults to ./reports/screenshots. The CaptureHelpers class creates this directory automatically if it doesn't exist and names files using the pattern <testName>_<dd-MM-yyyy HH-mm-ss>.png.

Can I use CaptureHelpers outside of the TestListener?

Yes. You can import com.anhtester.helpers.CaptureHelpers and call captureScreenshot(DriverManager.getDriver(), "customName") from any test method or utility class. This writes the file to the same configured export path without requiring the TestNG listener trigger.

How do I view screenshots in Allure reports?

The AllureListener automatically attaches screenshots when tests fail. The attachment appears in the Allure UI under the failed test case with a label containing the test name. No additional configuration is required beyond enabling the screenshot flag in config.properties.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}