-
Notifications
You must be signed in to change notification settings - Fork 30
/
Copy pathassertj-core.html
416 lines (330 loc) · 21.6 KB
/
assertj-core.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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="AssertJ site">
<meta name="author" content="Joel Costigliola">
<title>AssertJ / Fluent assertions for java</title>
<!-- CSS -->
<link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Inconsolata|Source+Code+Pro|Open+Sans|Ubuntu|Varela+Round|Karla">
<link href="css/bootstrap.min.css" rel="stylesheet">
<link href="font-awesome/css/font-awesome.min.css" rel="stylesheet">
<script src="highlight/highlight.pack.js"></script>
<link rel="stylesheet" href="highlight/styles/railscasts.css">
<script>hljs.initHighlightingOnLoad();</script>
<link href="css/assertj.min.css" rel="stylesheet">
<link rel="shortcut icon" href="favicon.png" />
</head>
<body>
<nav class="navbar navbar-inverse navbar-fixed-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-ex1-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<!-- You'll want to use a responsive image option so this logo looks good on devices - I recommend using something like retina.js (do a quick Google search for it and you'll find it) -->
<a class="navbar-brand" href="index.html">AssertJ</a>
</div>
<!-- Collect the nav links, forms, and other content for toggling -->
<div class="collapse navbar-collapse navbar-ex1-collapse">
<ul class="nav navbar-nav navbar-right">
<li><a href="assertj-core-quick-start.html">Quick start</a></li>
<li><a href="assertj-news.html">News</a></li>
<li><a href="assertj-core.html">Core</a></li>
<li><a href="assertj-assertions-generator.html">Assertions generator</a></li>
<li><a href="assertj-guava.html">Guava</a></li>
<li><a href="assertj-joda-time.html">Joda-Time</a></li>
<li><a href="assertj-db.html">DB</a></li>
<li><a href="assertj-neo4j.html">Neo4j</a></li>
<li><a href="assertj-swing.html">Swing</a></li>
<li><a href="assertj-help.html">Help</a></li>
</ul>
</div>
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-md-2 assertj-sidebar-menu">
<div class="bs-sidebar hidden-print affix-top" role="complementary">
<ul class="bs-sidenav nav ">
<li class="sidenav-header">Main</li>
<li><a href="assertj-core.html">Overview</a></li>
<li><a href="assertj-core-quick-start.html">Quick start</a></li>
<li><a href="assertj-core-news.html">News & releases</a></li>
<li><a href="assertj-core-features-highlight.html">Features highlight</a></li>
<li><a href="assertj-core-conditions.html">Using conditions</a></li>
<li><a href="assertj-core-custom-assertions.html">Custom assertions</a></li>
<li><a href="http://joel-costigliola.github.io/assertj/core/api/index.html" target="_blank">Javadoc (2.x)</a></li>
<li><a href="http://joel-costigliola.github.io/assertj/core-8/api/index.html" target="_blank">Javadoc (3.x)</a></li>
<li><a href="assertj-core.html#help">Help & F.A.Q</a></li>
<li><a href="assertj-core.html#code">Code & issues <i class="fa fa-github"></i></a></li>
<li><a href="assertj-core.html#team">Team</a></li>
<li><a href="assertj-core.html#contributing">Contributing</a></li>
<li class="sidenav-header">Migrating</li>
<li><a href="assertj-core-converting-junit-assertions-to-assertj.html">JUnit 4 Assertions</a></li>
<li><a href="assertj-core-converting-junit5-assertions-to-assertj.html">JUnit 5 Assertions</a></li>
<li><a href="assertj-core-converting-testng-assertions-to-assertj.html">TestNG Assertions</a></li>
<li><a href="assertj-core-migrating-from-fest.html">Fest Assert</a></li>
</ul>
</div>
</div>
<div class="col-lg-10 col-md-10 col-sm-10 text-left">
<h1 class="page-header">AssertJ Core new website!</h1>
<h2 style="color:darkblue;font-style: italic;"><u>AssertJ Core site has moved to <a href="https://assertj.github.io/doc/">https://assertj.github.io/doc/</a> </u></h2>
<h1 class="page-header">AssertJ Core overview (deprecated)</h1>
<p>AssertJ core is a Java library that provides a fluent interface for writing assertions. Its main goal is to
improve test code readability and make maintenance of tests easier.</p>
<p>AssertJ core provides assertions for JDK standard types and can be used with JUnit, TestNG or any other test framework.</p>
<p>Different AssertJ major versions depend on different Java versions :</p>
<ul>
<li>AssertJ 3.x requires Java 8 or higher (use the <span class="small-code">org.assertj.core.api.Java6Assertions</span> entry point on Android API Level < 26)</li>
<li>AssertJ 2.x requires Java 7 or higher (use the <span class="small-code">org.assertj.core.api.Java6Assertions</span> entry point on Android API Level < 26)</li>
<li>AssertJ 1.x requires Java 6 or higher</li>
</ul>
<p>Note that AssertJ 3.x includes all AssertJ 2.x features and adds Java 8 specific ones (like <a href="assertj-core-features-highlight.html#exception-assertion">exception assertions with lambdas</a>).</p>
<p>Soft assertions are not supported in Android, this is due the internal use of Byte Buddy that does not support Android.</p>
<p>AssertJ core <a href="https://github.com/joel-costigliola/assertj-core">code</a> and
<a href="https://github.com/joel-costigliola/assertj-core/issues?state=open">issue tracker</a> are hosted on github.</p>
<p>AssertJ is a fork of FEST Assert, a great project I have contributed to for 3 years. <b>Many thanks to Alex Ruiz Fest Assert creator!</b></p>
<h3 class="page-header"><span id="fork"></span>Project philosophy</h3>
<p>We are trying hard to make AssertJ a community driven project that is listening to users and trying to help them. It turns out that most of the new features and improvements ideas come from users
and that's great because it means it is providing value. If you have an idea to improve AssertJ, please don't hesitate to <a href="https://github.com/joel-costigliola/assertj-core/issues?state=open">create an issue</a> to let us know.</p>
<p>AssertJ is not a complex project so don't be afraid to <a href="#contributing">contribute</a>, we will be here to help you especially if it is your first open source contribution. Documentation improvements are welcome, we value them a lot.</p>
<p>AssertJ is built on our spare time, although we are doing our best to give quick feedback sometimes we won't be able to, be patient, be nice, be cool, we all have life to live, families to take care of and time consuming hobbies (pen and paper RPG and basketball for me!).</p>
<i>Joel Costigliola (AssertJ creator)</i>
<h3 class="page-header">Getting started</h3>
<p>For a quick start, have a look at our
<a href="assertj-core-quick-start.html">one minute getting started guide</a>.
</p>
<p>Convert existing JUnit assertions to AssertJ ones : we have a <a href="assertj-core-converting-junit-assertions-to-assertj.html">guide</a> to easily
convert JUnit assertions to AssertJ.
</p>
<p>If you have any questions, please use
<a href="https://stackoverflow.com/search?tab=relevance&q=assertj">stack overflow</a> or the <a href="https://groups.google.com/forum/?fromgroups=#!forum/assertj">AssertJ google group</a> (with a preference for stack overflow).
</p>
<p>You are more than welcome to
<a href="https://github.com/joel-costigliola/assertj-core/issues?state=open">raise an issue</a> if you need new assertions or see potential improvements.
</p>
<h3 class="page-header">Working with AssertJ core</h3>
<h5>Working with AssertJ on a daily basis</h5>
<ul>
<li><a href="assertj-core-quick-start.html">Quick start guide</a></li>
<li><a href="assertj-core-features-highlight.html">Features highlight</a></li>
<li><a href="assertj-core-news.html">New and noteworthy in AssertJ core</a></li>
</ul>
<h5>Extending AssertJ</h5>
<ul>
<li><a href="assertj-core-conditions.html">Extending assertions with conditions</a></li>
<li><a href="assertj-core-custom-assertions.html">Creating your own specific assertions</a></li>
</ul>
<p>You can see assertions in action with the <a href="https://github.com/joel-costigliola/assertj-examples/blob/master/assertions-examples/src/test/java/org/assertj/examples/">assertj examples tests</a> of the <a href="https://github.com/joel-costigliola/assertj-examples/">assertj-examples</a> project.</p>
<h3 class="page-header"><span id="help"/></span>Help & F.A.Q</h3>
<p>The best way to get help is to ask your question on <a href="https://stackoverflow.com/questions/tagged/assertj?mixed=1">stackoverflow (assertj tag)</a>.</p>
<u><p>F.A.Q:</p></u>
<ul>
<li><a href="#ambiguous-compilation-error">compilation error: reference to <span class="small-code">assertThat</span> is ambiguous</a></li>
<li><a href="#faq-incorrect-api-usage">AssertJ incorrect API usage (and how to detect it with static code analysis)</a></li>
<li><a href="#java9-reflection-error">InaccessibleObjectException in Java 9+</a></li>
<li><a href="#android">Android Support</a></li>
</ul>
<h4 class="page-header"><span id="ambiguous-compilation-error" class="adjustAnchor"></span><i class="fa fa-arrow-circle-right"></i> Compilation error: reference to <span class="small-code">assertThat</span> is ambiguous</h4>
<p>The erroneous code probably looks like this:</p>
<pre><code class="java">protected static <T extends Date> T getDate() {
return (T) new Date();
}
@Test public void doesNotCompile()
// Error: reference to assertThat is ambiguous
Assertions.assertThat(getDate()).isEqualTo(getDate());
}</code></pre>
<p>The error is due to a combination of things:</p>
<ul>
<li><span class="small-code">T</span> could implement an interface, let's say <span class="small-code">I</span></li>
<li><span class="small-code">assertThat(I)</span> method is in <span class="small-code">Assertions</span></li>
<li>you are using <span class="small-code">Assertions</span> as an entry point for <span class="small-code">assertThat</span> methods</li>
</ul>
<p>This makes the compiler confused whether to use <span class="small-code">assertThat(Date)</span> or <span class="small-code">assertThat(I)</span>, a complete explanation is given <a href="https://stackoverflow.com/questions/29499847/ambiguous-method-in-java-8-why">here</a>.</p>
<p><u>Workaround 1:</u></p>
<p>Cast the object to a concrete type:</p>
<pre><code class="java">@Test public void doesCompile()
Assertions.assertThat((Date) getDate()).isEqualTo(getDate());
}</code></pre>
<p><u>Workaround 2:</u></p>
<p>For any AssertJ 3.x version <b>except 3.9.0</b> (sigh), use <span class="small-code">AssertionsForClassTypes.assertThat</span> as it does not provide any <span class="small-code">assertThat</span> methods taking an interface.</p>
<pre><code class="java">@Test public void doesCompile()
AssertionsForClassTypes.assertThat((Date) getDate()).isEqualTo(getDate());
}</code></pre>
<p><b>AssertJ 3.9.0</b>: Unfortunately you <b>can't</b> use this workaround since we wrongly added <span class="small-code">assertThat(CompletionStage)</span> in <span class="small-code">AssertionsForClassTypes</span> (<span class="small-code">CompletionStage</span> is an interface).
This has been fixed in <b>3.9.1</b>.</p>
<h4 class="page-header"><span id="faq-incorrect-api-usage" class="adjustAnchor"></span><i class="fa fa-arrow-circle-right"></i> AssertJ incorrect API usage and static code analysis</h4>
<p>The following examples show incorrect AssertJ API usage:</p>
<pre><code class="java">// BAD USAGE: DON'T DO THIS ! It does not assert anything
assertThat(actual.equals(expected));
// DO THIS:
assertThat(actual).isEqualTo(expected);
// OR THIS (less classy but ok):
assertThat(actual.equals(expected)).isTrue();</code></pre>
<pre><code class="java">// BAD USAGE: DON'T DO THIS ! It does not assert anything and passes
assertThat(1 == 2);
// DO THIS: (fails as expected)
assertThat(1).isEqualTo(2);
// OR THIS (less classy but ok):
assertThat(1 == 2).isTrue();</code></pre>
<pre><code class="java">// BAD USAGE: DON'T DO THIS ! as/describedAs have no effect after the assertion
assertThat(actual).isEqualTo(expected).as("description");
assertThat(actual).isEqualTo(expected).describedAs("description");
// DO THIS: use as/describedAs before the assertion
assertThat(actual).as("description").isEqualTo(expected);
assertThat(actual).describedAs("description").isEqualTo(expected);</code></pre>
<pre><code class="java">// BAD USAGE: DON'T DO THIS ! overridingErrorMessage/withFailMessage have no effect after the assertion
assertThat(actual).isEqualTo(expected).overridingErrorMessage("custom error message");
assertThat(actual).isEqualTo(expected).withFailMessage("custom error message");
// DO THIS: use overridingErrorMessage/withFailMessage before the assertion
assertThat(actual).overridingErrorMessage("custom error message").isEqualTo(expected);
assertThat(actual).withFailMessage("custom error message").isEqualTo(expected);</code></pre>
<pre><code class="java">// BAD USAGE: DON'T DO THIS ! Comparator is not used
assertThat(actual).isEqualTo(expected).usingComparator(new CustomComparator());
// DO THIS:
assertThat(actual).usingComparator(new CustomComparator()).isEqualTo("a");</code></pre>
<h4 class="page-header"><span id="java9-reflection-error" class="adjustAnchor"></span><i class="fa fa-arrow-circle-right"></i> InaccessibleObjectException in Java 9+</h4>
<p>You can encounter errors similar to the one below when using AssertJ features requiring private fields introspection in <b>Java 9+</b>:</p>
<pre><code class="xml">java.lang.reflect.InaccessibleObjectException:
Unable to make field private transient long java.util.Date.fastTime accessible:
module java.base does not "opens java.util" to unnamed module @66b72664</code></pre>
<p>Java 9 is much more restrictive concerning reflective access to non-public fields/methods, you need to open all required packages for AssertJ as follows (in particular it opens <span class="small-code">java.util</span>):</p>
<pre><code class="bash">--add-opens java.base/java.lang=ALL-UNNAMED
--add-opens java.base/java.util=ALL-UNNAMED
--add-opens java.base/java.io=ALL-UNNAMED
--add-opens java.base/java.math=ALL-UNNAMED</code></pre>
<p>A nice article on the topic: <a href="https://blog.codefx.org/java/five-command-line-options-to-hack-the-java-9-module-system/#Reflectively-Accessing-Internal-APIs-With--add-opens">https://blog.codefx.org/java/five-command-line-options-to-hack-the-java-9-module-system/#Reflectively-Accessing-Internal-APIs-With--add-opens</a></p>
<h4 class="page-header"><span id="android" class="adjustAnchor"></span><i class="fa fa-arrow-circle-right"></i> Android Support</h4>
<p>Android versions before 8.0.0 (API level 26) do not support the <span class="small-code">java.nio.file.Path</span> class, so the 'regular' AssertJ 3.x/2.x entry point classes can not be used.
Instead you can use the <span class="small-code">Java6XAssertions</span> classes. For example use <span class="small-code">org.assertj.core.api.Java6Assertions</span> instead of <span class="small-code">org.assertj.core.api.Assertions</span>.</p>
<p>Please note that <b>soft assertions are not supported in Android</b>, this is due the internal use of Byte Buddy that does not support Android.</p>
<p>The following listing contains 'regular' import statements and their android alternative:</p>
<pre><code class="java">// 'regular' assertj
import static org.assertj.core.api.Assertions.*
// assertj on android
import static org.assertj.core.api.Java6Assertions.*
// 'regular' assertj
import static org.assertj.core.api.BDDAssertions.*
// assertj on android
import static org.assertj.core.api.Java6BDDAssertions.*
</code></pre>
<h3 class="page-header"><span id="code"/></span>Code and issue tracker</h3>
<p>AssertJ Core is hosted on github : <a href="https://github.com/joel-costigliola/assertj-core">https://github.com/joel-costigliola/assertj-core</a>.</p>
<p>Please report bugs or missing features in the <a href="https://github.com/joel-costigliola/assertj-core/issues?labels=&milestone=&page=1&state=open">AssertJ Core issue tracker</a>.</p>
<h3 class="page-header"><span id="team"/></span>AssertJ Core Team</h3>
<h4 class="page-header"><span id="creating-condition"></span>Joel Costigliola</h4>
<p>AssertJ's Vetinari (ok, maybe not as Machiavellian), enjoys playing basket ball, loves Terry Pratchett's disc world (surprised ?) and works with linux.</p>
<h4 class="page-header"><span id="creating-condition"></span>Pascal Schumacher</h4>
<p>AssertJ collaborator, who loves books, history and books about history.</p>
<h3 class="page-header"><span id="contributing"/></span>Contributing to AssertJ</h3>
<p>You are very welcome to contribute, we want to offer the richest and easiest to use assertion API,
so ideas from our users are very appreciated.</p>
<p>Contributing is easy and we try to help people contributing. Have a look at the <a
href="https://github.com/joel-costigliola/assertj-core/blob/master/CONTRIBUTING.md">contributor guidelines</a>
(these are the same guidelines shown when you create a new issue).
</p>
<p>Special thanks assertj-core contributors :
<ul>
<li>Adam Dąbrowski</li>
<li>Adam Ruka</li>
<li>Alban Dericbourg</li>
<li>Alexander Bischof</li>
<li>Alexandre Balhier</li>
<li>Andrew Gaul</li>
<li>Ben Blank</li>
<li>Brian Laframboise</li>
<li>Brice Dutheil</li>
<li>Chris Arnott</li>
<li>Clément Cunin</li>
<li>Clément Mathieu</li>
<li>Cristiano Gavião</li>
<li>Dan Corder</li>
<li>Daniel Zlotin</li>
<li>Dima Gerasimov</li>
<li>dmwvr</li>
<li>Fabien Duminy</li>
<li>Fabien Meurisse</li>
<li>Francis Galiegue</li>
<li>Filip Hrisafov</li>
<li>Gregor Zeitlinger</li>
<li>hgcummings</li>
<li>James Strachan</li>
<li>Jean Christophe Gay</li>
<li>Jeremy Landis</li>
<li>Johannes Schneider</li>
<li>Johannes Brodwall</li>
<li>Guillaume Husta</li>
<li>Grzegorz Piwowarek</li>
<li>Kamil Szymanski</li>
<li>Kseniya Panasyuk</li>
<li>Kevin Fang</li>
<li>Lovro Pandzic</li>
<li>Lukasz Kryger</li>
<li>Libor Ondrušek</li>
<li>Marcin Mikosik</li>
<li>Marcus Klimstra</li>
<li>Mariusz Smykula</li>
<li>Mateusz Haligowski</li>
<li>Michael W. Fender</li>
<li>Michal Bareja</li>
<li>Michal Kordas</li>
<li>Michal Lipski</li>
<li>Michał Ostruszka</li>
<li>Michał Piotrkowski</li>
<li>Michaël Bitard</li>
<li>Mike Kobit</li>
<li>Mike Wilkes</li>
<li>Mikhail Mazursky</li>
<li>Misha Brukman</li>
<li>Nicolai Parlog</li>
<li>Nick Stolwijk</li>
<li>Paul Doran</li>
<li>Pascal Schumacher</li>
<li>Paweł Barszcz</li>
<li>Peter Phillips</li>
<li>Pierre Templier</li>
<li>Piotr Betkier</li>
<li>Richard Lucas</li>
<li>Ted Young</li>
<li>Tim Perry</li>
<li>timmikk</li>
<li>Tobias Bieniek</li>
<li>Tobias Liefke</li>
<li>Tomasz Bartczak</li>
<li>Trond Marius Øvstetun</li>
<li>Valeriy Vyrva</li>
<li>William Delanoue</li>
</ul>
</p>
<h3 class="page-header">Thanks</h3>
<p>AssertJ has its roots in FEST Assert, a project I have contributed to for 3 years, so thanks to Alex Ruiz
FEST's creator !</p>
<p>Thanks to SonarQube for providing AssertJ Core
<a href="http://nemo.sonarqube.org/dashboard/index/528057">quality reports</a>.</p>
</div>
</div>
</div>
<br>
<!--
<div class="container">
<footer>
<div class="row">
<div class="col-lg-12">
<p>AssertJ - Licensed under the Apache License, Version 2.0.</p>
</div>
</div>
</footer>
</div>
-->
<script src="js/jquery-1.10.2.js"></script>
<script src="js/bootstrap.js"></script>
<script src="js/modern-business.js"></script>
<script src="js/assertj.js"></script>
</body>
</html>