Tips for Designing Strings
When you use Approval tests, the results of the things you are testing are going to be stored on disk. It is good if you can diff the files, to gain an understanding of what is created and how they change. Mainly this is done by creating strings.
Design
If your code already has output operators, then go ahead and use them in Approvals.
If your code doesn’t have output operators already, then here are some general guidelines to consider, to generate strings that work well with Approvals.
The general design rules when writing:
Objects print their relevant data
The data is consistent between runs (no times, pointers, random)
The data is easy to read
Note: for the same data, different tests might need different string conversions, to satisfy these rules.
Method |
Example |
Advantages |
Disadvantages |
---|---|---|---|
XML |
|
Works with standard tools |
Very verbose; hard to scan by eye |
JSON |
|
Works with standard tools; less verbose |
|
YAML |
|
Works with standard tools; less verbose |
Indentation matters |
simple |
|
It’s a custom format |
|
simpler |
|
Does not include meta data |
|
formatted |
|
Works well for many lines of the same type of data, for example an array of rectangles |
|
tab-separated |
Works with Excel and Markdown; works well for many lines of the same data |
||
co mma-separated |
|
Works with Excel |
Works with Excel |
Lists
Some formats will be more readable when you are writing lists of objects. Here’s an example of verifing a list of rectangles
ApprovalTests::Approvals::verifyAll("rectangles", getRectangles());
(See snippet source)
Notice how this:
rectangles
[0] = [x: 4 y: 50 width: 100 height: 61]
[1] = [x: 50 y: 5200 width: 400 height: 62]
[2] = [x: 60 y: 3 width: 7 height: 63]
(See snippet source)
compares to this:
rectangles
(x,y,width,height) = (4,50,100,61)
(x,y,width,height) = (50,5200,400,62)
(x,y,width,height) = (60,3,7,63)
(See snippet source)
Tools
TODO Explain things like:
Using Excel to create graphs
Loading run-time data from captured approval results
Querying logs from JSON output
IExecutable queries
How to Implement This
Approvals offers multiple ways to customise the To String. For details, see String conversions.