Testing a text format
A text format is a contract about characters: which separator, when a value is quoted, how a quote inside a value is written. A test of a writer asserts the exact string, because a format that is almost right is wrong. This lesson writes CSV lines and checks the three rules that matter in a small table.
A CSV line writer
CsvLine.java joins two values with a comma. A value that contains a comma or a quote is wrapped in quotes, and a quote inside the value is doubled. Those are the rules of RFC 4180, and they are small enough to state in one method.
public class CsvLine {
static String join(String left, String right) {
return quote(left) + "," + quote(right);
}
private static String quote(String value) {
if (value.contains(",") || value.contains("\"")) {
return "\"" + value.replace("\"", "\"\"") + "\"";
}
return value;
}
}
The quoting rules
The plain case has no special character: the value goes through unchanged. A comma is the separator, so a value with a comma must be quoted or the reader would split it in two. A quote must be doubled inside a quoted value, so the reader can tell a quote in the data from the quote that ends the field. A value with a quote but no comma is still quoted, because the doubled quote is unambiguous only inside quotes.
import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Test;
public class CsvLineTest {
@Test
void joinsTwoPlainValues() {
assertEquals("Ada,Grace", CsvLine.join("Ada", "Grace"));
}
@Test
void quotesAComma() {
assertEquals("\"Ada, Grace\",Hopper", CsvLine.join("Ada, Grace", "Hopper"));
}
@Test
void doublesAQuote() {
assertEquals("\"say \"\"hi\"\"\",Ada", CsvLine.join("say \"hi\"", "Ada"));
}
}
Three tests
Each test names the rule it checks. The expected string is written with the Java escapes, so the source is noisy, but the value in the report is the real line. A test that only checked startsWith or the length would pass for the wrong quote in the wrong place.
The expected string is a literal, so the compiler checks its escapes and the test checks the writer. When the format is generated, compare against a golden file read through the class path, and keep the file in the same commit as the writer.
The report
javac -Xlint:all -cp /opt/java-tools/junit-platform-console-standalone.jar -d out CsvLine.java CsvLineTest.java
junit execute --class-path out --scan-classpath --disable-ansi-colors
Thanks for using JUnit! Support its development at https://junit.org/sponsoring
╷
├─ JUnit Platform Suite ✔
├─ JUnit Jupiter ✔
│ └─ CsvLineTest ✔
│ ├─ quotesAComma() ✔
│ ├─ joinsTwoPlainValues() ✔
│ └─ doublesAQuote() ✔
└─ JUnit Vintage ✔
Test run finished after 812 ms
[ 4 containers found ]
[ 0 containers skipped ]
[ 4 containers started ]
[ 0 containers aborted ]
[ 4 containers successful ]
[ 0 containers failed ]
[ 3 tests found ]
[ 0 tests skipped ]
[ 3 tests started ]
[ 0 tests aborted ]
[ 3 tests successful ]
[ 0 tests failed ]
Testing a parser as well
A writer is half of a format. The other half is a reader, and the best test of the pair is a round trip: write two values, read them back, compare the values. That test catches a writer and a reader that agree only with themselves, which is the failure mode a single-side test cannot see. The next lesson puts a reader behind an interface and tests both sides.
Exercises
- Change the writer to quote every value and run. Which of the three tests fails first?
- Add a test for an empty value. What does the writer produce, and what should the reader see?
- Add a value with a newline and decide whether it must be quoted. Write the test first.
- Write a round-trip test that calls split on the result and compares the two parts for a value without a comma.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
When must a CSV value be quoted?
Answer
When it contains the separator or a quote
The separator and the quote are the two characters the format gives a meaning to.
-
How is a quote inside a quoted value written?
Answer
Doubled
RFC 4180 doubles the quote so the reader can tell data from the closing quote.
-
Why check the exact expected string rather than its length?
Answer
A format that is almost right is wrong
The position of a quote or comma is the contract, and only the exact string checks it.
-
What does this program print?
public class Q1 { public static void main(String[] args) { System.out.println("a" + "," + "b"); } }Answer
a,b
The string is joined with the comma literal, so the line is a,b.
-
What does this program print?
public class Q2 { public static void main(String[] args) { System.out.println("\"x\""); } }Answer
"x"
The escaped quotes are printed as quote characters around x.
-
What does this program print?
public class Q3 { public static void main(String[] args) { System.out.println("a,b".contains(",")); } }Answer
true
The string contains the comma, so contains is true.
-
What does this program print?
public class Q4 { public static void main(String[] args) { String value = "a b"; System.out.println(value.replace(" ", "_")); } }Answer
a_b
replace swaps every space for an underscore.
-
What is the failure mode a round-trip test catches that a writer-only test cannot?
Answer
A writer and reader that agree only with each other
The pair is tested together, so a shared misunderstanding of the format shows up.
-
What does this program print?
public class Q5 { public static void main(String[] args) { System.out.println("say \"hi\"".length()); } }Answer
8
The value is say "hi": three letters, a space, two quotes, two letters, so eight characters.
-
Which expected value is the exact CSV line for the values
Ada, GraceandHopper?Answer
"Ada, Grace",Hopper
The first value has the separator, so it is quoted; the second stays plain.
The code on this page was built with OpenJDK 21.0.13 (javac) and run with JUnit Platform Console Launcher 1.14.3 on Alpine Linux in a Docker container.
Article author: Arthur Isaev