Skip to content

Commit 496fc7f

Browse files
ScottBobScottBob
committed
t Update docs and test examples for CombinationTest approvals
1 parent ab0de7c commit 496fc7f

File tree

3 files changed

+110
-3
lines changed

3 files changed

+110
-3
lines changed

‎approvaltests-tests/src/test/java/org/approvaltests/combinations/CombinationTest.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,4 +36,22 @@ public Object processCall(Integer i, String s)
3636
{ throw new SkipCombination(); }
3737
return String.format("[%s, %s]", i, s);
3838
}
39+
40+
@Test
41+
void templateCode() {
42+
// begin-snippet: CombinationsStartingPoint
43+
String[] inputs1 = {"input1.value1", "input1.value2"};
44+
String[] inputs2 = {"input2.value1", "input2.value2", "input2.value3"};
45+
CombinationApprovals.verifyAllCombinations((a,b) -> "placeholder", inputs1, inputs2);
46+
// end-snippet
47+
}
48+
49+
@Test
50+
void testCombinationsOfTwo() {
51+
// begin-snippet: YouCanVerifyCombinationsOf2
52+
String[] strings = {"hello", "world"};
53+
Integer[] numbers = {1, 2, 3};
54+
CombinationApprovals.verifyAllCombinations((s, i) -> String.format("(%s,%s)", s, i), strings, numbers);
55+
// end-snippet
56+
}
3957
}

‎approvaltests/docs/how_to/TestCombinations.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
<a id="top"></a>
2+
3+
# Testing Combinations
4+
5+
<!-- toc -->
6+
## Contents
7+
8+
* [When to use Combinations](#when-to-use-combinations)
9+
* [Steps](#steps)
10+
* [The Basics](#the-basics)
11+
* [Passing in a Reporter](#passing-in-a-reporter)
12+
* [C++ Language Versions](#c-language-versions)<!-- endToc -->
13+
14+
## When to use Combinations
15+
16+
You have a function that takes, for example, 3 parameters, and you want to test its behaviour with a bunch of different values for each of those parameters.
17+
18+
If you have only one parameter that you want to vary, check out [How to Test a Variety of Values for One Input](/doc/how_tos/TestAVarietyOfValues.md#top).
19+
20+
## Steps
21+
22+
1. Copy this starter text, and adjust for the number of inputs that you have.
23+
24+
<!-- snippet: CombinationsStartingPoint -->
25+
<a id='snippet-combinationsstartingpoint'></a>
26+
```java
27+
String[] inputs1 = {"input1.value1", "input1.value2"};
28+
String[] inputs2 = {"input2.value1", "input2.value2", "input2.value3"};
29+
CombinationApprovals.verifyAllCombinations((a,b) -> "placeholder", inputs1, inputs2);
30+
```
31+
<sup><a href='/approvaltests-tests/src/test/java/org/approvaltests/combinations/CombinationTest.java#L42-L46' title='Snippet source file'>snippet source</a> | <a href='#snippet-combinationsstartingpoint' title='Start of snippet'>anchor</a></sup>
32+
<!-- endSnippet -->
33+
34+
2. Modify each input container for your chosen values.
35+
3. Run it, and make sure that you have your inputs wired up correctly.
36+
37+
If they are wired up correctly, you will see a file that looks like this: it is the left hand side of the file that
38+
matters at this point: all combinations of your own input values should be listed:
39+
40+
<!-- snippet: CombinationTest.templateCode.approved.txt -->
41+
<a id='snippet-CombinationTest.templateCode.approved.txt'></a>
42+
```txt
43+
[input1.value1, input2.value1] => placeholder
44+
[input1.value1, input2.value2] => placeholder
45+
[input1.value1, input2.value3] => placeholder
46+
[input1.value2, input2.value1] => placeholder
47+
[input1.value2, input2.value2] => placeholder
48+
[input1.value2, input2.value3] => placeholder
49+
```
50+
<sup><a href='/approvaltests-tests/src/test/java/org/approvaltests/combinations/CombinationTest.templateCode.approved.txt#L1-L6' title='Snippet source file'>snippet source</a> | <a href='#snippet-CombinationTest.templateCode.approved.txt' title='Start of snippet'>anchor</a></sup>
51+
<!-- endSnippet -->
52+
53+
5. Implement the body of your lambda
54+
6. Run it, and approve the output.
55+
56+
## The Basics
57+
58+
You can use `CombinationApprovals.verifyAllCombinations` to test the content of multiple containers.
59+
60+
This makes a kind of approval test matrix, automatically testing all combinations of a set of inputs. It's a powerful way to quickly get very good test coverage.
61+
62+
In this small example, all combinations of `{"hello", "world"}` and `{1, 2, 3}` are being used:
63+
64+
<!-- snippet: YouCanVerifyCombinationsOf2 -->
65+
<a id='snippet-youcanverifycombinationsof2'></a>
66+
```java
67+
String[] strings = {"hello", "world"};
68+
Integer[] numbers = {1, 2, 3};
69+
CombinationApprovals.verifyAllCombinations((s, i) -> String.format("(%s,%s)", s, i), strings, numbers);
70+
```
71+
<sup><a href='/approvaltests-tests/src/test/java/org/approvaltests/combinations/CombinationTest.java#L51-L55' title='Snippet source file'>snippet source</a> | <a href='#snippet-youcanverifycombinationsof2' title='Start of snippet'>anchor</a></sup>
72+
<!-- endSnippet -->
73+
74+
The format is carefully chosen to show both inputs and outputs, to make the test results easy to interpret. The output looks like this:
75+
76+
<!-- snippet: CombinationTest.testCombinationsOfTwo.approved.txt -->
77+
<a id='snippet-CombinationTest.testCombinationsOfTwo.approved.txt'></a>
78+
```txt
79+
[hello, 1] => (hello,1)
80+
[hello, 2] => (hello,2)
81+
[hello, 3] => (hello,3)
82+
[world, 1] => (world,1)
83+
[world, 2] => (world,2)
84+
[world, 3] => (world,3)
85+
```
86+
<sup><a href='/approvaltests-tests/src/test/java/org/approvaltests/combinations/CombinationTest.testCombinationsOfTwo.approved.txt#L1-L6' title='Snippet source file'>snippet source</a> | <a href='#snippet-CombinationTest.testCombinationsOfTwo.approved.txt' title='Start of snippet'>anchor</a></sup>
87+
<!-- endSnippet -->
88+
For
89+
advice on effective formatting, see [Tips for Designing Strings](https://github.com/approvals/ApprovalTests.cpp/blob/master/doc/explanations/TipsForDesigningStrings.md#top). As you write out larger volumes of data in your approval files, experience has shown that the choice of layout of text in approval files can make a big difference to maintainability of tests, when failures occur.
90+
---
91+
92+
[Back to User Guide](/doc/README.md#top)

‎todo.md‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
11
# Code
2-
* Continue to evolve StoryBoard
3-
42
* Approvals.options.forName.asMachineNameSpecificTest().onlyForEnvironments("Larss-Air.lan", "macbook13").run(this::extracted);
53
* better default FrontloadedReporter to handle CI
64
* NamedEnvironment with execute around pattern?
@@ -10,7 +8,6 @@
108
** update mrunit and fix tests
119
** VelocityApprovals doesn't know about Options yet
1210

13-
* remove all checked exceptions
1411
* Think about removing MethodExcecutionPath
1512
* remove all warnings
1613
* handle manual install of intellij

0 commit comments

Comments
 (0)