Introduce `commentCharacter` property in `@Csv{File}Source` #5031

vdmitrienko · 2025-10-06T21:38:45Z

I hereby agree to the terms of the JUnit Contributor License Agreement.

#5028

Definition of Done

There are no TODOs left in the code
Method preconditions are checked and documented in the method's Javadoc
Coding conventions (e.g. for logging) have been followed
Change is covered by automated tests including corner cases, errors, and exception handling
Public API has Javadoc and @API annotations
Change is documented in the User Guide and Release Notes

junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvReaderFactory.java

vdmitrienko · 2025-10-11T11:31:08Z

@vdmitrienko, is this PR "ready for review"?

@sbrannen, I’d like to update the User Guide and Release Notes, but other than that, it’s ready.

UPD

The User Guide and Release Notes updated ✔️

vdmitrienko · 2025-10-11T14:46:44Z

@marcphilipp, @sbrannen, I'm a bit confused 😅 . According to the compatibility scan, this new method is a source-incompatible change, even though it has a default value:

char commentCharacter() default '#';

Could you take a look?

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

marcphilipp · 2025-10-12T12:06:51Z

I'm a bit confused 😅 . According to the compatibility scan, this new method is a source-incompatible change, even though it has a default value

Looks like that's a false-positive reported by japicmp:

New method in annotation with default value reported as METHOD_ABSTRACT_ADDED_TO_CLASS siom79/japicmp#249

I hope that we can switch to roseau soon (see #5010) because it seems to be more precise.

For now, I just pushed a commit adding the two new attributes to the list of "accepted breaking changes" even though we know they're not actually breaking.

marcphilipp · 2025-10-12T12:07:15Z

documentation/src/docs/asciidoc/release-notes/release-notes-6.0.1.adoc

-* ❓
+* A regression introduced in version 6.0.0 caused an exception when using the
+  `@CsvSource` or `@CsvFileSource` annotations when the `delimiter` or
+  `delimiterString` attribute was set to #. This occurred because `#` was used


Suggested change

`delimiterString` attribute was set to #. This occurred because `#` was used

`delimiterString` attribute was set to `#`. This occurred because `#` was used

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvFileSource.java

junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvSource.java

sbrannen · 2025-10-12T14:34:41Z

New method in annotation with default value reported as METHOD_ABSTRACT_ADDED_TO_CLASS siom79/japicmp#249

Ahhh, good that that's already been reported. 👍

I hope that we can switch to roseau soon (see #5010) because it seems to be more precise.

🤞

For now, I just pushed a commit adding the two new attributes to the list of "accepted breaking changes" even though we know they're not actually breaking.

Oh man... I literally did that at the same time as you (perhaps even before you), but I was away from the computer and came back to find you'd already pushed the same fix. 😆

Though, I sorted the entries alphabetically. 😉

sbrannen

Looking very good! 👍

I've requested a few minor changes.

sbrannen · 2025-10-12T14:50:17Z

documentation/src/docs/asciidoc/release-notes/release-notes-6.0.1.adoc

+* A regression introduced in version 6.0.0 caused an exception when using the
+  `@CsvSource` or `@CsvFileSource` annotations when the `delimiter` or
+  `delimiterString` attribute was set to #. This occurred because `#` was used
+  as the default comment character without an option to change it.
+  To resolve this, a new `commentCharacter` attribute has been added to both
+  annotations. Its default value remains `#`, but it can now be customized
+  to avoid conflicts with other control characters.


Suggested change

* A regression introduced in version 6.0.0 caused an exception when using the

`@CsvSource` or `@CsvFileSource` annotations when the `delimiter` or

`delimiterString` attribute was set to #. This occurred because `#` was used

as the default comment character without an option to change it.

To resolve this, a new `commentCharacter` attribute has been added to both

annotations. Its default value remains `#`, but it can now be customized

to avoid conflicts with other control characters.

* A regression introduced in version 6.0.0 caused an exception when using `@CsvSource` or

`@CsvFileSource` if the `delimiter` or `delimiterString` attribute was set to `+++#+++`.

This occurred because `+++#+++` was used as the default comment character without an

option to change it. To resolve this, a new `commentCharacter` attribute has been added

to both annotations. Its default value remains `+++#+++`, but it can now be customized

to avoid conflicts with other control characters.

sbrannen · 2025-10-12T14:52:04Z

gradle/config/japicmp/accepted-breaking-changes.txt

+org.junit.jupiter.params.provider.CsvSource#commentCharacter
+org.junit.jupiter.params.provider.CsvFileSource#commentCharacter


Suggested change

org.junit.jupiter.params.provider.CsvSource#commentCharacter

org.junit.jupiter.params.provider.CsvFileSource#commentCharacter

org.junit.jupiter.params.provider.CsvFileSource#commentCharacter

org.junit.jupiter.params.provider.CsvSource#commentCharacter

Sort alphabetically.

sbrannen · 2025-10-12T14:52:34Z

junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvFileSource.java

 *
- * <p>Any line beginning with a {@code #} symbol will be interpreted as a comment
- * and will be ignored.
+ * <p>Any line beginning with a {@link #commentCharacter()}


Suggested change

* Any line beginning with a {@link #commentCharacter()}

* Any line beginning with a {@linkplain #commentCharacter() comment character}

@sbrannen, what do you think about keeping {@link ...} here for consistency with how the other attributes are described?

No problem. Consistency is king. 👍🏻

sbrannen · 2025-10-12T14:53:41Z

junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvFileSource.java

+	 * <p>The comment character must be the first character on the line without
+	 * any leading whitespace.
+	 *
+	 * <p>Defaults to a hashtag {@code #}.


Suggested change

* Defaults to a hashtag {@code #}.

* Defaults to {@code '#'}.

sbrannen · 2025-10-12T14:54:36Z

junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvReaderFactory.java

+		validateControlCharactersDiffer(
+				delimiter, csvFileSource.quoteCharacter(), csvFileSource.commentCharacter(), commentStrategy
+		);


Suggested change

validateControlCharactersDiffer(

delimiter, csvFileSource.quoteCharacter(), csvFileSource.commentCharacter(), commentStrategy

);

validateControlCharactersDiffer(

delimiter, csvFileSource.quoteCharacter(), csvFileSource.commentCharacter(), commentStrategy);

sbrannen · 2025-10-12T15:00:42Z

junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvSource.java

+	 * <p>The comment character must be the first character on the line without
+	 * any leading whitespace.
+	 *
+	 * <p>Defaults to a hashtag {@code #}.


Suggested change

* Defaults to a hashtag {@code #}.

* Defaults to {@code '#'}.

jupiter-tests/src/test/java/org/junit/jupiter/params/provider/CsvArgumentsProviderTests.java

sbrannen · 2025-10-12T15:05:40Z

jupiter-tests/src/test/java/org/junit/jupiter/params/provider/CsvArgumentsProviderTests.java

+				? builder.delimiter(c).build() //
+				: builder.delimiterString(delimiter.toString()).build();
+
+		var message = "delimiter or delimiterString: '%s', and quoteCharacter: '%s' must differ";


Suggested change

var message = "delimiter or delimiterString: '%s', and quoteCharacter: '%s' must differ";

var message = "delimiter or delimiterString: '%s' and quoteCharacter: '%s' must differ";

sbrannen · 2025-10-12T15:06:28Z

jupiter-tests/src/test/java/org/junit/jupiter/params/provider/CsvArgumentsProviderTests.java

+	}
+
+	@Test
+	void doesNotThrowExceptionWhenDelimiterAndCommentCharacterTheSameWhenUsingValueAttribute() {


Suggested change

void doesNotThrowExceptionWhenDelimiterAndCommentCharacterTheSameWhenUsingValueAttribute() {

void doesNotThrowExceptionWhenDelimiterAndCommentCharacterAreTheSameWhenUsingValueAttribute() {

sbrannen · 2025-10-12T15:06:46Z

jupiter-tests/src/test/java/org/junit/jupiter/params/provider/CsvArgumentsProviderTests.java

+
+	@ParameterizedTest
+	@MethodSource("invalidDelimiterQuoteCharacterAndCommentCharacterCombinations")
+	void throwsExceptionWhenControlCharactersTheSameWhenUsingTextBlockAttribute(Object delimiter, char quoteCharacter,


Suggested change

void throwsExceptionWhenControlCharactersTheSameWhenUsingTextBlockAttribute(Object delimiter, char quoteCharacter,

void throwsExceptionWhenControlCharactersAreTheSameWhenUsingTextBlockAttribute(Object delimiter, char quoteCharacter,

sbrannen

"looses" -> "loses"

sbrannen · 2025-10-12T15:15:35Z

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

-below which demonstrates formatting similar to a table).
+comments. Any line beginning with the value of the `commentCharacter` attribute (`+++#+++`
+by default) will be treated as a comment and ignored. Note that there is one exception
+to this rule: if the comment character appears within a quoted field, it looses


Suggested change

to this rule: if the comment character appears within a quoted field, it looses

to this rule: if the comment character appears within a quoted field, it loses

sbrannen · 2025-10-12T15:15:49Z

junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvFileSource.java

+	 *
+	 * <p>Any line that begins with this character will be treated as a comment
+	 * and ignored during parsing. Note that there is one exception to this rule:
+	 * if the comment character appears within a quoted field, it looses its


Suggested change

* if the comment character appears within a quoted field, it looses its

* if the comment character appears within a quoted field, it loses its

sbrannen · 2025-10-12T15:16:09Z

junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvSource.java

+	 *
+	 * <p>Any line that begins with this character will be treated as a comment
+	 * and ignored during parsing. Note that there is one exception to this rule:
+	 * if the comment character appears within a quoted field, it looses its


Suggested change

* if the comment character appears within a quoted field, it looses its

* if the comment character appears within a quoted field, it loses its

Introduce commentCharacter property in @Csv{File}Source

ff2d88d

vdmitrienko marked this pull request as draft October 6, 2025 21:38

vdmitrienko mentioned this pull request Oct 6, 2025

Can no longer use # as delimiter with @CsvSource and @CsvFileSource #5028

Open

Apply spotless

f60b67e

vdmitrienko commented Oct 6, 2025

View reviewed changes

junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvReaderFactory.java Outdated Show resolved Hide resolved

sbrannen added type: enhancement component: Jupiter theme: parameterized tests labels Oct 7, 2025

vdmitrienko added 3 commits October 11, 2025 08:48

Merge branch 'main' into 5028-introduce-comment-character

7c8e062

Skip validation of commentCharacter when CommentStrategy is NONE

76cd357

Add a note about control characters to the JavaDoc

f4b4fed

This comment was marked as outdated.

Sign in to view

vdmitrienko marked this pull request as ready for review October 11, 2025 11:29

vdmitrienko added 2 commits October 11, 2025 15:08

Document commentCharacter usage in User Guide

da91a90

Document the change in the release notes

8d6b480

osiegmar reviewed Oct 12, 2025

View reviewed changes

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc Outdated Show resolved Hide resolved

Document behavior of comments within quoted fields

dbbbb5b

vdmitrienko requested review from marcphilipp, osiegmar and sbrannen October 12, 2025 09:20

Ignore false-positives reported by japicmp

cbd7113

marcphilipp reviewed Oct 12, 2025

View reviewed changes

Polish documentation

bb6155e

sbrannen requested changes Oct 12, 2025

View reviewed changes

Fix typo: looses -> loses

10128ba

vdmitrienko added 10 commits October 12, 2025 17:26

Correct test method names

4aebe17

Remove redundant comma in exception message

60f5ba7

Apply suggestion to the Release Notes (Bug Fixes)

fc162ed

Sort accepted breaking changes alphabetically

7961662

JavaDoc: remove parentheses after method name

16875c8

JavaDoc: wrap # in single quotes

7e11bad

CsvReaderFactory: adjust formatting as suggested

76a9a1b

JavaDoc: use tag instead of 

41ff7ef

JavaDoc: clarify rules for control characters

8a8218a

JavaDoc: wrap lines at 80 characters in CsvFileSource

82dad22

vdmitrienko requested review from marcphilipp and sbrannen October 12, 2025 17:04

	`delimiterString` attribute was set to #. This occurred because `#` was used
	`delimiterString` attribute was set to `#`. This occurred because `#` was used

		org.junit.jupiter.params.provider.CsvSource#commentCharacter
		org.junit.jupiter.params.provider.CsvFileSource#commentCharacter

	* <p>Any line beginning with a {@link #commentCharacter()}
	* <p>Any line beginning with a {@linkplain #commentCharacter() comment character}

	* <p>Defaults to a hashtag {@code #}.
	* <p>Defaults to {@code '#'}.

	var message = "delimiter or delimiterString: '%s', and quoteCharacter: '%s' must differ";
	var message = "delimiter or delimiterString: '%s' and quoteCharacter: '%s' must differ";

	void doesNotThrowExceptionWhenDelimiterAndCommentCharacterTheSameWhenUsingValueAttribute() {
	void doesNotThrowExceptionWhenDelimiterAndCommentCharacterAreTheSameWhenUsingValueAttribute() {

	void throwsExceptionWhenControlCharactersTheSameWhenUsingTextBlockAttribute(Object delimiter, char quoteCharacter,
	void throwsExceptionWhenControlCharactersAreTheSameWhenUsingTextBlockAttribute(Object delimiter, char quoteCharacter,

	to this rule: if the comment character appears within a quoted field, it looses
	to this rule: if the comment character appears within a quoted field, it loses

	* if the comment character appears within a quoted field, it looses its
	* if the comment character appears within a quoted field, it loses its

Uh oh!

Introduce commentCharacter property in @Csv{File}Source #5031

Are you sure you want to change the base?

Introduce commentCharacter property in @Csv{File}Source #5031

Uh oh!

Conversation

vdmitrienko commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Definition of Done

Uh oh!

Uh oh!

This comment was marked as outdated.

vdmitrienko commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vdmitrienko commented Oct 11, 2025

Uh oh!

Uh oh!

marcphilipp commented Oct 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sbrannen commented Oct 12, 2025

Uh oh!

sbrannen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbrannen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Introduce `commentCharacter` property in `@Csv{File}Source` #5031

Introduce `commentCharacter` property in `@Csv{File}Source` #5031

vdmitrienko commented Oct 6, 2025 •

edited

Loading

vdmitrienko commented Oct 11, 2025 •

edited

Loading