Create Cucumber JVM custom formatter

Last Updated on by

Post summary: How to implement custom formatter for Cucumber JVM.

Cucumber code examples can be found in selenium-samples-java/cucumber-parallel GitHub repository.

Cucumber has different types of formatters available. See Cucumber formatters for more details. Still those might not fulfil your needs. If this is the case Cucumber provides a way to create own custom formatter.

Why to create Cucumber JVM custom formatter

There could be different reasons for this. Standard formatters are know not to be thread safety, so one reason could be to create own thread safety formatter. Other reason could be if you want you results to be stored directly into database or sent to a REST service. There could be many reasons, reading this post means you already have one.

How to create Cucumber JVM custom formatter

Custom formatter can be created by implementing two interfaces: gherkin.formatter.Reporter and gherkin.formatter.Formatter. This is it. You have to know though when each method from interfaces is called and this is pretty tricky. One simple implementation of custom formatter can be found in GitHub file. This is implementation from scratch. Other option is to extend some already existing formatter and modify its behaviour.

Using custom formatter in Cucumber runner

Custom formatter is invoked by fully qualified class name in @CucumberOptions annotation. In this example it is: plugin = {“com.automationrhapsody.cucumber.formatter.CustomFormatter”}.

import org.junit.runner.RunWith;

import cucumber.api.CucumberOptions;
import cucumber.api.junit.Cucumber;

		plugin = {
public class RunWikipediaTestsWithCustomFormatter {

Passing argument to custom formatter

In code above along with fully qualified class name of CustomFormatter there is also file name (and location) with colon – :custom-formatter-output.txt.  This is the way to pass argument to CustomFormatter. In order to receive the argument CustomFormatter constructor should have one of the following parameters:

  • null – empty constructor, this is just to instantiate some variable, nothing can be received from outside.
  • interface java.lang.Appendable – object to which values should be appended. It should have implementation which can be custom or gherkin.formatter.NiceAppendable can be used. See example bellow.
  • class – URI that can be used in case of database connection strings or URL. Also applicable for passing a plain String.
  • class – only for web URL.
  • class – file path can be passed, could be absolute or relative.


public CustomFormatter(Appendable appendable) {
	output = new NiceAppendable(appendable);
	System.out.println("CustomFormatter(): " + output.toString());


Cucumber JVM gives lot of flexibility by providing a way to implement custom formatter based on your current needs. It is pretty straightforward to do it. It is possible also to pass arguments to a parametrised constructor in custom formatter.

If you find this post useful, please share it to reach more people. Sharing is caring!
Share on FacebookShare on LinkedInTweet about this on TwitterShare on Google+Email this to someone
Category: Java | Tags:
  • Vamsi Krishna

    Hi Latinov,
    I am currently trying to customize my Report and building a custom formatter similar to this. I need to push feature , scenario and it’s steps and their respective results during run time. Problem is if I run multiple features/scenarios parallely from different runner classes and use same custom formatter class, how would I differentiate scenarios and their steps since same overridden method is called by multiple parallel threads during run time. Please share your inputs on the same.