TestReport

TestNG test reporting with beautiful dashboard - just copy files and go!

TestReport is a lightweight npm package that provides a beautiful HTML dashboard for viewing TestNG test results. It includes Java listeners that automatically generate JSON reports and capture screenshots on test failures.

Supported stack

• Build tool: Maven (single-module or multi-module)
• Language: Java 17+
• Test framework: TestNG only (JUnit, JUnit 5, Cucumber, etc. are not supported yet)

Features

• 🎨 Beautiful Dashboard - Modern HTML dashboard with dark/light themes
• 📸 Auto Screenshots - Automatically captures screenshots on test failure
• 🔍 Zero-Change Integration - Works with existing tests without modifications
• 📊 Rich Reports - Detailed test execution logs and error context
• ⚡ Easy Setup - Simple installation script or manual file copy

Quick Start

Installation

npm install testreport-io-selenium

Integration

Option 1: Use the installation script (Recommended)

npx testreport-install

The script will:

• Detect your Maven project structure
• Prompt for your Java package name
• Copy listener files with correct package names
• Copy dashboard files
• Check for required Maven dependencies
• Provide next steps

Option 2: Manual installation

1. Copy Java files from node_modules/testreport/listeners/ to your project:

   src/test/java/com/yourpackage/
   ├── listeners/
   │   ├── AutoDetectJsonReportListener.java
   │   └── AutoDetectExtentReportListener.java
   └── utils/
       ├── TestReportContext.java
       └── TestReportHelper.java

2. Replace placeholders in the Java files:

   • {{PACKAGE_NAME}} → Your package name (e.g., com.mycompany.tests)
   • {{OUTPUT_DIR}} → Output directory (default: test-output)
   • {{LISTENERS_DIR}} → listeners
   • {{UTILS_DIR}} → utils

3. Copy dashboard files from node_modules/testreport/dashboard/ to test-output/dashboard/

Configuration

1. Add Maven dependencies to pom.xml:

<dependencies>
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.10.1</version>
    </dependency>
    <dependency>
        <groupId>com.aventstack</groupId>
        <artifactId>extentreports</artifactId>
        <version>5.1.1</version>
    </dependency>
</dependencies>

2. Register listeners in testng.xml:

<suite name="Test Suite">
    <listeners>
        <listener class-name="com.yourpackage.listeners.AutoDetectJsonReportListener"/>
        <listener class-name="com.yourpackage.listeners.AutoDetectExtentReportListener"/>
    </listeners>
    
    <test name="Tests">
        <classes>
            <class name="com.yourpackage.tests.YourTestClass"/>
        </classes>
    </test>
</suite>

Usage

Run your tests:

mvn clean test

View the dashboard:

Option 1: Use the open command (Recommended)

npx testreport-open

This automatically finds and opens the dashboard in your default browser.

Option 2: Manual Open test-output/dashboard/index.html in your browser.

How It Works

Auto-Detection

The listeners use reflection to automatically detect WebDriver instances in your test classes. No changes to your existing test code are required!

// Your existing test - works as-is!
public class MyExistingTest {
    private WebDriver driver;
    
    @BeforeMethod
    public void setup() {
        driver = new ChromeDriver();
    }
    
    @Test
    public void myTest() {
        driver.get("https://example.com");
        // Screenshots automatically captured on failure!
    }
}

Optional Enhanced Logging

You can optionally add detailed logging using TestReportHelper:

import com.yourpackage.utils.TestReportHelper;

@Test
public void myTest() {
    TestReportHelper.step("Navigate to login page");
    driver.get("https://example.com/login");
    
    TestReportHelper.step("Enter credentials");
    // ... your code ...
    
    TestReportHelper.pass("Login successful");
}

Dashboard Features

• Overall Statistics - Pass rate, total tests, duration
• Status Breakdown - Passed, Failed, Skipped counts
• Test Details - Click any test to see:
  • Execution logs
  • Error context (layman explanations)
  • Screenshots (if available)
  • Video recordings (if available)
• Dark/Light Theme - Toggle between themes
• Responsive Design - Works on desktop and mobile

Video Recording Integration

TestReport supports video recording of test execution through external video recording libraries. This design ensures cross-platform compatibility and works reliably in all environments (local, CI/CD, headless, etc.).

Why External Video Recording?

TestReport does not include built-in video recording because:

• Cross-platform reliability: Built-in screen capture (e.g., Monte Screen Recorder) requires specific JVM flags (--add-exports, --add-opens) on Java 9+ and fails in headless/CI environments
• Flexibility: You can use any video recording solution (Monte, FFmpeg, browser-level capture, Selenium Grid, BrowserStack, etc.)
• Better format support: External libraries can output MP4 (best browser support) instead of AVI

How It Works

1. You record the video using your preferred library in your test code
2. You tell TestReport where the video is via a TestNG attribute
3. TestReport displays it in the dashboard

Quick Start

In your test's @AfterMethod (or wherever you stop recording), set the recordingPath attribute:

import org.testng.ITestResult;
import org.testng.Reporter;

@AfterMethod(alwaysRun = true)
public void stopRecording(ITestResult result) {
    // After your video recording library has saved the file
    String videoPath = "/path/to/your/video.mp4";
    
    // Tell TestReport where the video is
    result.setAttribute("recordingPath", videoPath);
}

That's it! TestReport will automatically:

• Normalize the path for dashboard display
• Validate the file exists
• Show a video link in the test details

Complete Example with Monte Screen Recorder

Here's a full example using Monte Screen Recorder in your project's BaseTest (not in the listener):

import org.monte.screenrecorder.ScreenRecorder;
import org.testng.ITestResult;
import org.testng.annotations.*;
import java.awt.*;
import java.io.File;
import java.lang.reflect.Method;

public class BaseTest {
    protected WebDriver driver;
    private ScreenRecorder recorder;
    private File videosDir;

    @BeforeMethod
    public void setUp(Method method) throws Exception {
        // Set up WebDriver
        driver = new ChromeDriver();
        
        // Start video recording (only if enabled and not headless)
        if (Boolean.getBoolean("video.enabled") && !GraphicsEnvironment.isHeadless()) {
            videosDir = new File("test-output/recordings");
            videosDir.mkdirs();
            
            GraphicsConfiguration gc = GraphicsEnvironment
                .getLocalGraphicsEnvironment()
                .getDefaultScreenDevice()
                .getDefaultConfiguration();
            
            String fileName = method.getName() + "-" + System.currentTimeMillis();
            recorder = new ScreenRecorder(gc, gc.getBounds(), null, null, null, videosDir, fileName);
            recorder.start();
        }
    }

    @AfterMethod(alwaysRun = true)
    public void tearDown(ITestResult result) {
        // Stop video recording and tell TestReport about it
        if (recorder != null) {
            try {
                recorder.stop();
                java.util.List<File> files = recorder.getCreatedMovieFiles();
                if (files != null && !files.isEmpty()) {
                    File videoFile = files.get(0);
                    if (videoFile.exists() && videoFile.length() > 0) {
                        // Tell TestReport where the video is
                        result.setAttribute("recordingPath", videoFile.getAbsolutePath());
                    }
                }
            } catch (Exception e) {
                System.err.println("Failed to stop video recording: " + e.getMessage());
            } finally {
                recorder = null;
            }
        }
        
        // Quit WebDriver
        if (driver != null) {
            driver.quit();
        }
    }
}

To use Monte, add this dependency to your pom.xml:

<dependency>
    <groupId>com.github.stephenc.monte</groupId>
    <artifactId>monte-screen-recorder</artifactId>
    <version>0.7.7.0</version>
</dependency>

And add JVM flags for Java 9+ (in Maven Surefire):

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.2.5</version>
    <configuration>
        <argLine>
            --add-exports java.desktop/sun.awt=ALL-UNNAMED
            --add-opens java.desktop/java.awt=ALL-UNNAMED
        </argLine>
    </configuration>
</plugin>

Path Format Guidelines

TestReport accepts video paths in multiple formats:

| Format | Example | Notes | |--------|---------|-------| | Absolute path | /home/user/project/test-output/recordings/video.mp4 | Automatically converted to relative | | Relative with ../ | ../recordings/video.mp4 | Used as-is | | Simple filename | video.mp4 | Placed in run-specific videos directory |

Recommended locations for videos:

• test-output/recordings/ - Legacy/shared location
• test-output/runs/run-{timestamp}/videos/ - Run-specific location (for multi-run support)

Supported Video Formats

The dashboard supports these formats (browser compatibility varies):

| Format | Extension | Browser Support | |--------|-----------|-----------------| | MP4 | .mp4 | ✅ Excellent (all browsers) | | WebM | .webm | ✅ Good (modern browsers) | | QuickTime | .mov | ⚠️ Good (Safari, Chrome) | | OGG | .ogg, .ogv | ⚠️ Good (Firefox, Chrome) | | AVI | .avi | ⚠️ Limited (requires codecs) | | MKV | .mkv | ⚠️ Limited (requires codecs) |

Recommendation: Use MP4 format for best cross-browser compatibility.

Alternative Recording Solutions

Besides Monte, you can use:

• FFmpeg CLI: Record screen via command line, output MP4
• Selenium Grid: Many grid providers (BrowserStack, Sauce Labs, LambdaTest) provide video recording
• Browser DevTools Protocol: Capture browser-level video
• OBS Studio: For local development with high-quality recordings

All you need to do is save the video file and set recordingPath in your test.

Troubleshooting

Video not appearing in dashboard:

• Verify the video file exists at the path you set
• Check console for [AUTO-DETECT REPORTER] External video recording detected: ...
• Ensure the path is accessible from the dashboard directory

Monte errors on Java 17+:

• Add the --add-exports and --add-opens JVM flags (see example above)
• Or switch to a different recording library

Headless/CI environments:

• Monte and most screen recorders require a display
• Use Xvfb on Linux: xvfb-run mvn test
• Or use browser-level capture or cloud provider video features

Project Structure

After installation, your project will have:

your-project/
├── src/test/java/com/yourpackage/
│   ├── listeners/
│   │   ├── AutoDetectJsonReportListener.java
│   │   └── AutoDetectExtentReportListener.java
│   └── utils/
│       ├── TestReportContext.java
│       └── TestReportHelper.java
├── test-output/
│   ├── dashboard/
│   │   ├── index.html
│   │   ├── styles.css
│   │   ├── app.js
│   │   └── logo.png
│   └── report-data/
│       └── results.json
└── pom.xml

Requirements

• Node.js 16+ (for installation)
• Java 17+
• Maven 3.8+
• TestNG 7.9.0+
• Selenium 4.18.1+ (for WebDriver tests)

Troubleshooting

Dashboard shows "Unable to load test data"

• Make sure you've run mvn clean test first
• Check that test-output/report-data/results.json exists
• Verify listeners are registered in testng.xml

Screenshots not captured

• Ensure your WebDriver instance is accessible (not null)
• Check that the driver implements TakesScreenshot
• Verify the test actually failed (screenshots only captured on failure)

Listeners not working

• Verify listeners are registered in testng.xml
• Check that package names in testng.xml match your actual package structure
• Ensure Maven dependencies (gson, extentreports) are in pom.xml

Package name detection failed

• Run the install script from your Maven project root
• Or manually specify the package name when prompted
• Ensure you have at least one Java file in src/test/java/

Advanced Usage

Custom Output Directory

Option 1: Runtime Configuration (Recommended)

You can override the output directory at runtime without editing any files:

# Via system property
mvn test -Dtestreport.outputDir=target/custom-reports

# Via environment variable
export TESTREPORT_OUTPUT_DIR=target/custom-reports
mvn test

Option 2: Edit Listener Files

Edit the listener files and change the {{OUTPUT_DIR}} placeholder (replaced during installation) to your desired directory. The installer will replace this when you run npx testreport-install.

Multiple Test Suites

Each test suite will generate its own report. The dashboard will show the latest run by default.

Parallel Execution

The listeners are thread-safe and support parallel test execution.

Running Individual Tests

TestReport supports running individual tests or specific test classes. However, you must ensure testng.xml is used so that the listeners are properly registered.

Option 1: Use TestNG suiteXmlFiles

# Run specific test class
mvn test -Dsurefire.suiteXmlFiles=testng.xml -Dtest=NavigationTests

# Run specific test method
mvn test -Dsurefire.suiteXmlFiles=testng.xml -Dtest=NavigationTests#testMethodName

Option 2: Add @Listeners to BaseTest (best for all tests)

If all your tests extend BaseTest, add it there:

import com.ownstable.listeners.AutoDetectJsonReportListener;
import com.ownstable.listeners.AutoDetectExtentReportListener;
import org.testng.annotations.Listeners;

@Listeners({AutoDetectJsonReportListener.class, AutoDetectExtentReportListener.class})
public class BaseTest {
    // ... your base test code
}

Option 3: Add @Listeners to test class (quick fix)

import com.ownstable.listeners.AutoDetectJsonReportListener;
import org.testng.annotations.Listeners;
// ... other imports

@Listeners(AutoDetectJsonReportListener.class)

Why is this needed?

When using -Dtest without specifying suiteXmlFiles, Maven Surefire may bypass testng.xml and create a dynamic test suite. This means listeners registered in testng.xml won't be invoked, and no report will be generated.

Verification:

After running tests, check the console output for:

[AUTO-DETECT REPORTER] Suite started: ...
[AUTO-DETECT REPORTER] Captured X test(s) for reporting
[AUTO-DETECT REPORTER] Report generated for run: run-...

If you see a warning about "No tests were captured", the listeners weren't registered properly.

CLI Alternative

If you prefer a full CLI tool with project scaffolding, check out testreport-cli.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• Issues: GitHub Issues
• Documentation: See TESTING_GUIDE.md and PUBLISHING_GUIDE.md

Made with ❤️ for the testing community