Support text blocks in `@ValueSource` and deprecate `textBlock` attribute in `@CsvSource`

[manoelcampos]

Introduction

JUnit 6 requires JDK 17 and text blocks are already supported in @CsvSource(textBlock = ...). However, we need to explicitly choose between using a text block or a regular string.

JEP 378 aimed for the interchangeability of regular Strings and Text Blocks, but that textBlock attribute in @CsvSource() forces users to choose between them.

@CsvSource

The code snippet below shows that we need to use textBlock property to pass a multiline String and the test is run 3 times:

@ParameterizedTest
@CsvSource(textBlock =
        """
        2,1
        6,3
        10,5
        """)
void csvSourceTextBlock(int a, int b) {
    assertEquals(a, b*2);
}

But using the value default property, only the first line is parsed:

@ParameterizedTest
@CsvSource(
        """
        100,50
        200,100
        300,150
        """)
void csvSourceTextBlockUsingValueProp(int a, int b) {
    assertEquals(a, b*2);
}

@ValueSource

This other annotation doesn’t even allow using text blocks as one would expect. Despite using a text block the code compiles, it doesn't give the expected result:

@ParameterizedTest
@ValueSource(strings =
        """
        L1
        L2
        L3
        """)
void valueSourceTextBlock(final String value) {
    assertFalse(value.contains("\n"), "Each value must represent a single line only (without line break)");
}

Instead of running the test 3 times (one line at a time), it runs a single time with value "L1 L2 L3".

Motivation

Leveraging the utilization of text blocks and providing and more natural way to use them interchangeably with regular Strings will make tests easier and cleaner.

This code below:

@ValueSource(
        """
        One
        Two
        Three
        """
)

is much cleaner than:

@ValueSource(strings = {
        "One",
        "Two",
        "Three"
})

Proposal

Proposal for @ValueSource

Add a String value default property and leave the strings for backward compatibility and for users that prefer passing values as an array. Internally, if the value has a line break, split it and run as if a String array was given to the strings property.

Proposal for @CsvSource

• Make the annotation split the value property at line breaks and run the test once for each resulting line.
• Deprecate the textBlock property

Final Thoughts

Behaviour change may cause issues depending on the user provided strings (such as strings with an explicit \n), but that requires some tests. I don't know what the effort would be to implement these changes. However, if you think these are valuable enhancements, I'll be happy to try implementing them.

[sbrannen]

Behaviour change may cause issues depending on the user provided strings (such as strings with an explicit \n)

I introduced the textBlock support in @CsvSource, and if I recall correctly "breaking behavior" was the exact line of reasoning for not simply treating any string as a text block.

The same would apply for @ValueSource and anywhere else that JUnit has traditionally had special treatment/processing for arrays of strings.

Thus, I'm not confident that we can make the proposed changes to @CsvSource.

In any case, we will discuss the topic within the team.

[manoelcampos]

Behaviour change may cause issues depending on the user provided strings (such as strings with an explicit \n)

@ParameterizedTest
@ValueSource(strings =
        """
        One 
        Test
         Run
         For a
        Multi-line
        String
        """)
void valueSourceTextBlockSingleRun(final String value) {
    assertTrue(value.contains("\n"), "The value must multiple lines");
}

Here, the user intention may really be running a single test with a multi-line string. So, this behavior must not be changed. But since the value property is not being used, it should be for running the test for each line in the string. But if the proposal for CsvSource cannot be implemented, adding a textBlock property to ValueSource (instead of using the value property) would be better for consistency with CsvSource.

[marcphilipp]

Proposal for @ValueSource

Add a String value default property and leave the strings for backward compatibility and for users that prefer passing values as an array. Internally, if the value has a line break, split it and run as if a String array was given to the strings property.

That annotation has no value attribute by design. I think we could introduce a new lines attribute that takes a String and splits it using the platform line separator.

Proposal for @CsvSource

• Make the annotation split the value property at line breaks and run the test once for each resulting line.

• Deprecate the textBlock property

Since CSV values can can contain line breaks, we can't split the value at line breaks because it would break existing use cases, for example:

@CsvSource("aaa,\"b \r\nbb\",ccc")

This would now result in two lines of invalid CSV.

[sbrannen]

I think we could introduce a new lines attribute that takes a String and splits it using the platform line separator.

That won't work, since newlines are normalized in text blocks.

We would have to consistently split using \n.

Or we could use java.lang.String.lines() and document the behavior.

[manoelcampos]

That annotation has no value attribute by design. I think we could introduce a new lines attribute that takes a String and splits it using the platform line separator.

Great