# How to Take Screenshots on Test Failures Using CaptureHelpers in automationframeworkselenium

> Learn to automatically capture screenshots on test failures with CaptureHelpers in automationframeworkselenium. Enable SCREENSHOT_FAILED_TCS for seamless reporting.

- Repository: [Anh Tester/automationframeworkselenium](https://github.com/anhtester/automationframeworkselenium)
- Tags: how-to-guide
- Published: 2026-02-24

---

**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`](https://github.com/anhtester/automationframeworkselenium/blob/main/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`](https://github.com/anhtester/automationframeworkselenium/blob/main/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`](https://github.com/anhtester/automationframeworkselenium/blob/main/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:

```properties
SCREENSHOT_FAILED_TCS = yes

```

The [`FrameworkConstants.java`](https://github.com/anhtester/automationframeworkselenium/blob/main/FrameworkConstants.java) file reads this value at startup:

```java
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`](https://github.com/anhtester/automationframeworkselenium/blob/main/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:

```java
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:

```java
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`](https://github.com/anhtester/automationframeworkselenium/blob/main/TestListener.java):

```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`.