Visualising Executions

TestNG allows you to visualise the test method executions via the interface IExecutionVisualiser.

TestNG passes metadata about the current execution state in dot representation.

Color coding is done as below:

  • tests that are yet to run are colored in yellow.

  • tests that are currently running are colored in green.

  • tests that have completed execution are colored in grey.

This listener should be declared, as explained in the section about TestNG listeners.

Let’s a sample.


  • Follow the instructions detailed in graphviz website to install graphviz. This binary will help us convert the dot format into png files.

  • Add a dependency to a library such as gifencoder so that we can convert a bunch of png files into a gif file.


Code sample

Here’s how a sample implementation could look like:

import com.squareup.gifencoder.FloydSteinbergDitherer;
import com.squareup.gifencoder.GifEncoder;
import com.squareup.gifencoder.ImageOptions;
import org.testng.IExecutionVisualiser;
import org.testng.IReporter;
import org.testng.ISuite;
import org.testng.xml.XmlSuite;

import javax.imageio.ImageIO;
import java.awt.image.BufferedImage;
import java.nio.file.*;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicInteger;

public class SampleVisualiser implements IExecutionVisualiser, IReporter {

    private final AtomicInteger counter = new AtomicInteger(1);
    private final Path tmpdir;

    private final List<String> pngFiles = new ArrayList<>();

    public SampleVisualiser() throws IOException {
        tmpdir = Files.createTempDirectory(Paths.get("target"), "dot-");

    public void consumeDotDefinition(String dotDefinition) {
        String filePrefix = counter.getAndIncrement() + "-" + UUID.randomUUID();
        Path input = Path.of(tmpdir.toFile().getAbsolutePath(), filePrefix + "");
        try {
            Files.writeString(input, dotDefinition);
            Path output = Path.of(tmpdir.toFile().getAbsolutePath(), filePrefix + "-output.png");
            if (generatePngFileFromDotContent(input, output)) {
        } catch (IOException | InterruptedException e) {
            throw new RuntimeException(e);

    public void generateReport(List<XmlSuite> xmlSuites, List<ISuite> suites, String outputDirectory) {
        //The GIF image will be created with file name "animation.gif"
        File writeTo = new File(tmpdir.toFile().getAbsolutePath(), "animation.gif");
        try (FileOutputStream outputStream = new FileOutputStream(writeTo)) {
            ImageOptions options = new ImageOptions();

            //Set 500ms between each frame
            options.setDelay(500, TimeUnit.MILLISECONDS);
            //Use Floyd Steinberg dithering as it yields the best quality
            GifEncoder encoder = new GifEncoder(outputStream, 1600, 1200, 0);
            for (String pngFile : pngFiles) {
                encoder.addImage(convertImageToArray(new File(pngFile)), options);
        } catch (IOException e) {
            throw new RuntimeException(e);
        System.err.println("The gif has been generated in :" + writeTo.getAbsolutePath());

    private int[][] convertImageToArray(File file) throws IOException {
        BufferedImage bufferedImage =;
        int[][] rgbArray = new int[bufferedImage.getHeight()][bufferedImage.getWidth()];
        for (int i = 0; i < bufferedImage.getHeight(); i++) {
            for (int j = 0; j < bufferedImage.getWidth(); j++) {
                rgbArray[i][j] = bufferedImage.getRGB(j, i);
        return rgbArray;

    private static boolean generatePngFileFromDotContent(Path input, Path output) throws IOException, InterruptedException {
        String[] cmds = {
        Process process = new ProcessBuilder().command(cmds).start();
        int exitCode = process.waitFor();
        System.err.println("PNG file written to " + output.toFile().getAbsolutePath());
        return exitCode == 0;

    private static void handleInputErrorFrom(Process process) throws IOException {

    private static void processStream(InputStream stream) throws IOException {
        if (stream == null) {
        BufferedReader reader = new BufferedReader(new InputStreamReader(stream));

        String line;
        while ((line = reader.readLine()) != null) {