-
Notifications
You must be signed in to change notification settings - Fork 2
/
introduction.html
176 lines (159 loc) · 8.68 KB
/
introduction.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<title>Expectations by jaycfields</title>
<link rel="stylesheet" href="stylesheets/styles.css">
<link rel="stylesheet" href="stylesheets/pygment_trac.css">
<script src="javascripts/scale.fix.js"></script>
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
</head>
<body>
<div class="wrapper">
<header>
<h1 class="header">Expectations</h1>
<p class="header">a minimalist's unit testing framework</p>
<ul>
<li><a class="buttons" href="index.html">Home</a></li>
<li><a class="buttons" href="installing.html">Installing</a></li>
<li><a class="buttons" href="introduction.html">Introduction</a></li>
<li><a class="buttons" href="advanced.html">Advanced</a></li>
<li><a class="buttons" href="collections.html">Collections</a></li>
<li><a class="buttons" href="templating.html">Expect More</a></li>
<li><a class="buttons" href="odds-ends.html">Odds & Ends</a></li>
<li><a class="buttons" href="in-context.html">Around Each</a></li>
<li><a class="buttons" href="before-run-hook.html">Around Suite</a></li>
<li><a class="buttons" href="state-warnings.html">State Warnings</a></li>
<li><a class="buttons" href="redef-state.html">Redef State</a></li>
<li><a class="buttons" href="interactions.html">Side Effects</a></li>
<li><a class="buttons" href="freeze-time.html">Freeze Time</a></li>
<li><a class="buttons" href="env-tweaks.html">ENV Tweaks</a></li>
<li><a class="buttons" href="emacs-tweaks.html">emacs Tweaks</a></li>
<li><a class="buttons" href="clojure-test.html">clojure.test</a></li>
<li><a class="buttons github" href="https://github.com/clojure-expectations/expectations">View On GitHub</a></li>
</ul>
<p class="header">This project is maintained by <a class="header name" href="https://github.com/seancorfield">seancorfield</a> and <a class="header name" href="https://github.com/jaycfields">jaycfields</a></p>
</header>
<section>
<h1>
<a name="expectations" class="anchor" href="#expectations"><span class="octicon octicon-link"></span></a>expectations</h1>
<blockquote>
<p>adding signal, removing noise</p>
</blockquote>
<h2>
<a name="introduction" class="anchor" href="#introduction"><span class="octicon octicon-link"></span></a>Introduction</h2>
expectations is built with the idea that unit tests should contain <a href="http://blog.jayfields.com/2007/06/testing-one-assertion-per-test.html">one assertion per test</a>. A result of this design choice is that expectations has very minimal syntax.<br />
<br />
For example, if you want to verify the result of a function call, all you need to do is specify what return value you expect from the function call.<br />
<pre>(expect 2 (+ 1 1)</pre>
note: you'll want to (:require [expectations :refer :all]); however, no other setup is required for using expectations. I created a sample project for this blog post and the entire test file looks like this (at this point):<br />
<pre>(ns sample.test.core
(:require [expectations :refer :all]))
(expect 2 (+ 1 1))</pre>
I'm using 'lein expectations' to run my tests. For more information on 'lein expectations', check out the <a href="installing.html">Installing</a> page.<br />
<pre>jfields$ lein expectations
Ran 1 tests containing 1 assertions in 2 msecs
0 failures, 0 errors.</pre>
That's the simplest, and most often used expectation - an equality comparison. The equality comparison works across all Clojure types - vectors, sets, maps, etc and any Java instances that return true when given to Clojure's = function.<br />
<pre>(ns sample.test.core
(:require [expectations :refer :all]))
(expect 2 (+ 1 1))
(expect [1 2] (conj [] 1 2))
(expect #{1 2} (conj #{} 1 2))
(expect {1 2} (assoc {} 1 2))</pre>
Running the previous expectations produces similar output as before.<br />
<pre>jfields$ lein expectations
Ran 4 tests containing 4 assertions in 26 msecs
0 failures, 0 errors.</pre>
Successful equality comparison isn't very exciting; however, expectations really begins to prove its worth with its failure messages. When comparing two numbers there's not much additional information that expectations can provide. Therefore, the following output is what you would expect when your expectation fails.<br />
<pre>(expect 2 (+ 1 3))
jfields$ lein expectations
failure in (core.clj:4) : sample.test.core
(expect 2 (+ 1 3))
expected: 2
was: 4</pre>
expectations gives you the namespace, file name, and line number along with the expectation you specified, the expected value, and the actual value. Again, nothing surprising. However, when you compare vectors, sets, and maps expectations does a bit of additional work to give you clues on what the problem might be. <br />
<br />
The following 3 expectations using vectors will all fail, and expectations provides detailed information on what exactly failed.<br />
<pre>(expect [1 2] (conj [] 1))
(expect [1 2] (conj [] 2 1))
(expect [1 2] (conj [] 1 3))
jfields$ lein expectations
failure in (core.clj:5) : sample.test.core
(expect [1 2] (conj [] 1))
expected: [1 2]
was: [1]
2 are in expected, but not in actual
expected is larger than actual
failure in (core.clj:6) : sample.test.core
(expect [1 2] (conj [] 2 1))
expected: [1 2]
was: [2 1]
lists appears to contain the same items with different ordering
failure in (core.clj:7) : sample.test.core
(expect [1 2] (conj [] 1 3))
expected: [1 2]
was: [1 3]
3 are in actual, but not in expected
2 are in expected, but not in actual
Ran 3 tests containing 3 assertions in 22 msecs
3 failures, 0 errors.</pre>
In these simple examples it's easy to see what the issue is; however, when working with larger lists expectations can save you a lot of time by telling you which specific elements in the list are causing the equality to fail.<br />
<br />
Failure reporting on sets looks very similar:<br />
<pre>(expect #{1 2} (conj #{} 1))
(expect #{1 2} (conj #{} 1 3))
jfields$ lein expectations
failure in (core.clj:9) : sample.test.core
(expect #{1 2} (conj #{} 1))
expected: #{1 2}
was: #{1}
2 are in expected, but not in actual
failure in (core.clj:10) : sample.test.core
(expect #{1 2} (conj #{} 1 3))
expected: #{1 2}
was: #{1 3}
3 are in actual, but not in expected
2 are in expected, but not in actual
Ran 2 tests containing 2 assertions in 15 msecs
2 failures, 0 errors.</pre>
expectations does this type of detailed failure reporting for maps as well, and this might be one if the biggest advantages expectations has over clojure.test - especially when dealing with nested maps.<br />
<pre>(expect {:one 1 :many {:two 2}}
(assoc {} :one 2 :many {:three 3}))
jfields$ lein expectations
failure in (core.clj:13) : sample.test.core
(expect {:one 1, :many {:two 2}} (assoc {} :one 2 :many {:three 3}))
expected: {:one 1, :many {:two 2}}
was: {:many {:three 3}, :one 2}
:many {:three with val 3 is in actual, but not in expected
:many {:two with val 2 is in expected, but not in actual
:one expected: 1
was: 2
Ran 1 tests containing 1 assertions in 19 msecs
1 failures, 0 errors.</pre>
expectations also provides a bit of additional help when comparing the equality of strings.<br />
<pre>(expect "in 1400 and 92" "in 14OO and 92")
jfields$ lein expectations
failure in (core.clj:17) : sample.test.core
(expect in 1400 and 92 in 14OO and 92)
expected: "in 1400 and 92"
was: "in 14OO and 92"
matches: "in 14"
diverges: "00 and 92"
&: "OO and 92"
Ran 1 tests containing 1 assertions in 8 msecs
1 failures, 0 errors.</pre>
That's basically all you'll need to know for using expectations to equality test. If you're still with me at this point, why not take a look at the examples of using expectations
with <a href="advanced.html">regexs, expected exceptions and type checking</a>?
</section>
<footer>
<p><small>Hosted on <a href="https://pages.github.com">GitHub Pages</a> using the Dinky theme</small></p>
</footer>
</div>
<!--[if !IE]><script>fixScale(document);</script><![endif]-->
</body>
</html>