Changing names of parameterized tests

java

test-engineering

best-practices

unit-testing

byNikita Barsukov·Oct 21, 2024

In JUnit 5 you can customize your parameterized test names with @ParameterizedTest and use the name parameter. Include placeholders like {0}, {1}, or {displayName} for dynamical names which refer to method arguments or the actual test display name.

@ParameterizedTest(name = "Test {index}: {0} + {1} = {2}")
@CsvSource({
    "1, 1, 2",
    "2, 3, 5"
})
void addTest(int a, int b, int sum) {
    assertEquals(sum, a + b);
}

This code results in: Test 0: 1 + 1 = 2, Test 1: 2 + 3 = 5.

Detailed guidelines for advanced use

Enhancing readability with dynamic naming

Increase the readability and comprehensibility of your tests by giving your test cases a custom name. Placeholder enriched names make test scenarios or expected results clear, resulting in a self-documented test suite and simplified debugging.

Use custom test runners for more configuration possibilities

Should you need further customizations or specific test name configurations, BlockJUnit4ClassRunner is what you need to extend when writing your own test runners. Override the getName() method to gain full control over the generated test name ({index} is so 2019).

Leverage third-party libraries

In case the standard set of features in JUnit does not suffice, JUnitParams might fill in the rest. It provides additional features and works well within the JUnit4 framework.

Evolving together with JUnit

JUnit is in constant evolution and your feedback matters. Your real-world scenarios and challenges can help the JUnit maintainers to adapt the framework to the needs of the developers in the trenches.

Keeping balance while updating JUnit versions

Before upgrading JUnit to the latest version in your project, ponder on the possible effects it may have on your team. In other words, safety first - the flashy new naming features should not compromise stable code.

Use custom Suite classes for granular test configuration

A custom Suite class based runner can be suitable if you want to adjust configurations at a granular level. It provides you more flexibility where the standard configurations do not suffice.

Test case configuration and management

When customizing tests, remember to use @Config for annotation-based configurations. Implement getChildren() in custom runners to manage test instances effectively - less missing children at the 'JUnit amusement park'.

Maintain and document your tests

Finally, make sure to document the test set-ups, the custom features and the custom classes. This is not only for your future-self to understand your work, but also to help others who may be digging through your code.

Go the extra mile and customize succinctly

Backwards compatibility with older JUnit versions

To use custom naming in projects where upgrading to the latest version of JUnit isn't feasible, use NewLabelledParameterized class.

Representing parameters as Strings in test names

When Parameterized class is used, parameters can be represented as strings. This makes your report more comprehensible, as seeing "2 vs 2" is easier to understand than "True".