Introducing TestParameterInjector: A JUnit4 parameterized test runner

 When writing unit tests, you may want to run the same or a very similar test for different inputs or input/output pairs. In Java, as in most programming languages, the best way to do this is by using a parameterized test framework.

JUnit4 has a number of such frameworks available, such as junit.runners.Parameterized and JUnitParams. A couple of years ago, a few Google engineers found the existing frameworks lacking in functionality and simplicity, and decided to create their own alternative. After a lot of tweaks, fixes, and feature additions based on feedback from clients all over Google, we arrived at what TestParameterInjector is today.

As can be seen in the graph below, TestParameterInjector is now the most used framework for new tests in the Google codebase:

How does TestParameterInjector work?

The TestParameterInjector exposes two annotations: @TestParameter and @TestParameters. The following code snippet shows how the former works:

@RunWith(TestParameterInjector.class) public class MyTest {   @TestParameter boolean isDryRun;   @Test public void test1(@TestParameter boolean enableFlag) {     // This method is run 4 times for all combinations of isDryRun and enableFlag   }   @Test public void test2(@TestParameter MyEnum myEnum) {     // This method is run 6 times for all combinations of isDryRun and myEnum   }   enum MyEnum { VALUE_A, VALUE_B, VALUE_C } }

Annotated fields (such as isDryRun) will cause each test method to run for all possible values while annotated method parameters (such as enableFlag) will only impact that test method. Note that the generated test names will typically be helpful but concise, for example: MyTest#test2[isDryRun=true, VALUE_A].

The other annotation, @TestParameters, can be seen at work in this snippet:

@RunWith(TestParameterInjector.class) public class MyTest {   @Test   @TestParameters({     "{age: 17, expectIsAdult: false}",     "{age: 22, expectIsAdult: true}",   })   public void personIsAdult(int age, boolean expectIsAdult) {     // This method is run 2 times   } }

In contrast to the first example, which tests all combinations, a @TestParameters-annotated method runs once for each test case specified.

How does TestParameterInjector compare to other frameworks?

To our knowledge, the table below summarizes the features of the different frameworks in use at Google:

	TestParameterInjector	junit.runners. Parameterized	JUnitParams	Burst	DataProvider	Jukito	Theories
Documentation	GitHub	GitHub	GitHub	GitHub	GitHub	GitHub	junit.org
Supports field injection	✓	✓		✓
Supports parameter injection	✓		✓	✓	✓	✓	✓
Considers sets of parameters correlated or orthogonal	both are supported	correlated	correlated	orthogonal	correlated	orthogon al	orthogonal
Refactor friendly	(✓)			✓		✓	✓

Learn more

Our GitHub README at https://github.com/google/TestParameterInjector gives an overview of the possibilities of this framework. Let us know on GitHub if you have any questions, comments, or feature requests!

By Jens Nyman, TestParameterInjector team

1Parameters are considered dependent. You specify explicit combinations to be run.

2Parameters are considered independent. The framework will run all possible combinations of parameters