001 package org.junit;
002
003 import org.hamcrest.Matcher;
004 import org.hamcrest.MatcherAssert;
005 import org.junit.function.ThrowingRunnable;
006 import org.junit.internal.ArrayComparisonFailure;
007 import org.junit.internal.ExactComparisonCriteria;
008 import org.junit.internal.InexactComparisonCriteria;
009
010 /**
011 * A set of assertion methods useful for writing tests. Only failed assertions
012 * are recorded. These methods can be used directly:
013 * <code>Assert.assertEquals(...)</code>, however, they read better if they
014 * are referenced through static import:
015 *
016 * <pre>
017 * import static org.junit.Assert.*;
018 * ...
019 * assertEquals(...);
020 * </pre>
021 *
022 * @see AssertionError
023 * @since 4.0
024 */
025 public class Assert {
026 /**
027 * Protect constructor since it is a static only class
028 */
029 protected Assert() {
030 }
031
032 /**
033 * Asserts that a condition is true. If it isn't it throws an
034 * {@link AssertionError} with the given message.
035 *
036 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
037 * okay)
038 * @param condition condition to be checked
039 */
040 public static void assertTrue(String message, boolean condition) {
041 if (!condition) {
042 fail(message);
043 }
044 }
045
046 /**
047 * Asserts that a condition is true. If it isn't it throws an
048 * {@link AssertionError} without a message.
049 *
050 * @param condition condition to be checked
051 */
052 public static void assertTrue(boolean condition) {
053 assertTrue(null, condition);
054 }
055
056 /**
057 * Asserts that a condition is false. If it isn't it throws an
058 * {@link AssertionError} with the given message.
059 *
060 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
061 * okay)
062 * @param condition condition to be checked
063 */
064 public static void assertFalse(String message, boolean condition) {
065 assertTrue(message, !condition);
066 }
067
068 /**
069 * Asserts that a condition is false. If it isn't it throws an
070 * {@link AssertionError} without a message.
071 *
072 * @param condition condition to be checked
073 */
074 public static void assertFalse(boolean condition) {
075 assertFalse(null, condition);
076 }
077
078 /**
079 * Fails a test with the given message.
080 *
081 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
082 * okay)
083 * @see AssertionError
084 */
085 public static void fail(String message) {
086 if (message == null) {
087 throw new AssertionError();
088 }
089 throw new AssertionError(message);
090 }
091
092 /**
093 * Fails a test with no message.
094 */
095 public static void fail() {
096 fail(null);
097 }
098
099 /**
100 * Asserts that two objects are equal. If they are not, an
101 * {@link AssertionError} is thrown with the given message. If
102 * <code>expected</code> and <code>actual</code> are <code>null</code>,
103 * they are considered equal.
104 *
105 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
106 * okay)
107 * @param expected expected value
108 * @param actual actual value
109 */
110 public static void assertEquals(String message, Object expected,
111 Object actual) {
112 if (equalsRegardingNull(expected, actual)) {
113 return;
114 }
115 if (expected instanceof String && actual instanceof String) {
116 String cleanMessage = message == null ? "" : message;
117 throw new ComparisonFailure(cleanMessage, (String) expected,
118 (String) actual);
119 } else {
120 failNotEquals(message, expected, actual);
121 }
122 }
123
124 private static boolean equalsRegardingNull(Object expected, Object actual) {
125 if (expected == null) {
126 return actual == null;
127 }
128
129 return isEquals(expected, actual);
130 }
131
132 private static boolean isEquals(Object expected, Object actual) {
133 return expected.equals(actual);
134 }
135
136 /**
137 * Asserts that two objects are equal. If they are not, an
138 * {@link AssertionError} without a message is thrown. If
139 * <code>expected</code> and <code>actual</code> are <code>null</code>,
140 * they are considered equal.
141 *
142 * @param expected expected value
143 * @param actual the value to check against <code>expected</code>
144 */
145 public static void assertEquals(Object expected, Object actual) {
146 assertEquals(null, expected, actual);
147 }
148
149 /**
150 * Asserts that two objects are <b>not</b> equals. If they are, an
151 * {@link AssertionError} is thrown with the given message. If
152 * <code>unexpected</code> and <code>actual</code> are <code>null</code>,
153 * they are considered equal.
154 *
155 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
156 * okay)
157 * @param unexpected unexpected value to check
158 * @param actual the value to check against <code>unexpected</code>
159 */
160 public static void assertNotEquals(String message, Object unexpected,
161 Object actual) {
162 if (equalsRegardingNull(unexpected, actual)) {
163 failEquals(message, actual);
164 }
165 }
166
167 /**
168 * Asserts that two objects are <b>not</b> equals. If they are, an
169 * {@link AssertionError} without a message is thrown. If
170 * <code>unexpected</code> and <code>actual</code> are <code>null</code>,
171 * they are considered equal.
172 *
173 * @param unexpected unexpected value to check
174 * @param actual the value to check against <code>unexpected</code>
175 */
176 public static void assertNotEquals(Object unexpected, Object actual) {
177 assertNotEquals(null, unexpected, actual);
178 }
179
180 private static void failEquals(String message, Object actual) {
181 String formatted = "Values should be different. ";
182 if (message != null) {
183 formatted = message + ". ";
184 }
185
186 formatted += "Actual: " + actual;
187 fail(formatted);
188 }
189
190 /**
191 * Asserts that two longs are <b>not</b> equals. If they are, an
192 * {@link AssertionError} is thrown with the given message.
193 *
194 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
195 * okay)
196 * @param unexpected unexpected value to check
197 * @param actual the value to check against <code>unexpected</code>
198 */
199 public static void assertNotEquals(String message, long unexpected, long actual) {
200 if (unexpected == actual) {
201 failEquals(message, Long.valueOf(actual));
202 }
203 }
204
205 /**
206 * Asserts that two longs are <b>not</b> equals. If they are, an
207 * {@link AssertionError} without a message is thrown.
208 *
209 * @param unexpected unexpected value to check
210 * @param actual the value to check against <code>unexpected</code>
211 */
212 public static void assertNotEquals(long unexpected, long actual) {
213 assertNotEquals(null, unexpected, actual);
214 }
215
216 /**
217 * Asserts that two doubles are <b>not</b> equal to within a positive delta.
218 * If they are, an {@link AssertionError} is thrown with the given
219 * message. If the unexpected value is infinity then the delta value is
220 * ignored. NaNs are considered equal:
221 * <code>assertNotEquals(Double.NaN, Double.NaN, *)</code> fails
222 *
223 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
224 * okay)
225 * @param unexpected unexpected value
226 * @param actual the value to check against <code>unexpected</code>
227 * @param delta the maximum delta between <code>unexpected</code> and
228 * <code>actual</code> for which both numbers are still
229 * considered equal.
230 */
231 public static void assertNotEquals(String message, double unexpected,
232 double actual, double delta) {
233 if (!doubleIsDifferent(unexpected, actual, delta)) {
234 failEquals(message, Double.valueOf(actual));
235 }
236 }
237
238 /**
239 * Asserts that two doubles are <b>not</b> equal to within a positive delta.
240 * If they are, an {@link AssertionError} is thrown. If the unexpected
241 * value is infinity then the delta value is ignored.NaNs are considered
242 * equal: <code>assertNotEquals(Double.NaN, Double.NaN, *)</code> fails
243 *
244 * @param unexpected unexpected value
245 * @param actual the value to check against <code>unexpected</code>
246 * @param delta the maximum delta between <code>unexpected</code> and
247 * <code>actual</code> for which both numbers are still
248 * considered equal.
249 */
250 public static void assertNotEquals(double unexpected, double actual, double delta) {
251 assertNotEquals(null, unexpected, actual, delta);
252 }
253
254 /**
255 * Asserts that two floats are <b>not</b> equal to within a positive delta.
256 * If they are, an {@link AssertionError} is thrown. If the unexpected
257 * value is infinity then the delta value is ignored.NaNs are considered
258 * equal: <code>assertNotEquals(Float.NaN, Float.NaN, *)</code> fails
259 *
260 * @param unexpected unexpected value
261 * @param actual the value to check against <code>unexpected</code>
262 * @param delta the maximum delta between <code>unexpected</code> and
263 * <code>actual</code> for which both numbers are still
264 * considered equal.
265 */
266 public static void assertNotEquals(float unexpected, float actual, float delta) {
267 assertNotEquals(null, unexpected, actual, delta);
268 }
269
270 /**
271 * Asserts that two object arrays are equal. If they are not, an
272 * {@link AssertionError} is thrown with the given message. If
273 * <code>expecteds</code> and <code>actuals</code> are <code>null</code>,
274 * they are considered equal.
275 *
276 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
277 * okay)
278 * @param expecteds Object array or array of arrays (multi-dimensional array) with
279 * expected values.
280 * @param actuals Object array or array of arrays (multi-dimensional array) with
281 * actual values
282 */
283 public static void assertArrayEquals(String message, Object[] expecteds,
284 Object[] actuals) throws ArrayComparisonFailure {
285 internalArrayEquals(message, expecteds, actuals);
286 }
287
288 /**
289 * Asserts that two object arrays are equal. If they are not, an
290 * {@link AssertionError} is thrown. If <code>expected</code> and
291 * <code>actual</code> are <code>null</code>, they are considered
292 * equal.
293 *
294 * @param expecteds Object array or array of arrays (multi-dimensional array) with
295 * expected values
296 * @param actuals Object array or array of arrays (multi-dimensional array) with
297 * actual values
298 */
299 public static void assertArrayEquals(Object[] expecteds, Object[] actuals) {
300 assertArrayEquals(null, expecteds, actuals);
301 }
302
303 /**
304 * Asserts that two boolean arrays are equal. If they are not, an
305 * {@link AssertionError} is thrown with the given message. If
306 * <code>expecteds</code> and <code>actuals</code> are <code>null</code>,
307 * they are considered equal.
308 *
309 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
310 * okay)
311 * @param expecteds boolean array with expected values.
312 * @param actuals boolean array with expected values.
313 */
314 public static void assertArrayEquals(String message, boolean[] expecteds,
315 boolean[] actuals) throws ArrayComparisonFailure {
316 internalArrayEquals(message, expecteds, actuals);
317 }
318
319 /**
320 * Asserts that two boolean arrays are equal. If they are not, an
321 * {@link AssertionError} is thrown. If <code>expected</code> and
322 * <code>actual</code> are <code>null</code>, they are considered
323 * equal.
324 *
325 * @param expecteds boolean array with expected values.
326 * @param actuals boolean array with expected values.
327 */
328 public static void assertArrayEquals(boolean[] expecteds, boolean[] actuals) {
329 assertArrayEquals(null, expecteds, actuals);
330 }
331
332 /**
333 * Asserts that two byte arrays are equal. If they are not, an
334 * {@link AssertionError} is thrown with the given message.
335 *
336 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
337 * okay)
338 * @param expecteds byte array with expected values.
339 * @param actuals byte array with actual values
340 */
341 public static void assertArrayEquals(String message, byte[] expecteds,
342 byte[] actuals) throws ArrayComparisonFailure {
343 internalArrayEquals(message, expecteds, actuals);
344 }
345
346 /**
347 * Asserts that two byte arrays are equal. If they are not, an
348 * {@link AssertionError} is thrown.
349 *
350 * @param expecteds byte array with expected values.
351 * @param actuals byte array with actual values
352 */
353 public static void assertArrayEquals(byte[] expecteds, byte[] actuals) {
354 assertArrayEquals(null, expecteds, actuals);
355 }
356
357 /**
358 * Asserts that two char arrays are equal. If they are not, an
359 * {@link AssertionError} is thrown with the given message.
360 *
361 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
362 * okay)
363 * @param expecteds char array with expected values.
364 * @param actuals char array with actual values
365 */
366 public static void assertArrayEquals(String message, char[] expecteds,
367 char[] actuals) throws ArrayComparisonFailure {
368 internalArrayEquals(message, expecteds, actuals);
369 }
370
371 /**
372 * Asserts that two char arrays are equal. If they are not, an
373 * {@link AssertionError} is thrown.
374 *
375 * @param expecteds char array with expected values.
376 * @param actuals char array with actual values
377 */
378 public static void assertArrayEquals(char[] expecteds, char[] actuals) {
379 assertArrayEquals(null, expecteds, actuals);
380 }
381
382 /**
383 * Asserts that two short arrays are equal. If they are not, an
384 * {@link AssertionError} is thrown with the given message.
385 *
386 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
387 * okay)
388 * @param expecteds short array with expected values.
389 * @param actuals short array with actual values
390 */
391 public static void assertArrayEquals(String message, short[] expecteds,
392 short[] actuals) throws ArrayComparisonFailure {
393 internalArrayEquals(message, expecteds, actuals);
394 }
395
396 /**
397 * Asserts that two short arrays are equal. If they are not, an
398 * {@link AssertionError} is thrown.
399 *
400 * @param expecteds short array with expected values.
401 * @param actuals short array with actual values
402 */
403 public static void assertArrayEquals(short[] expecteds, short[] actuals) {
404 assertArrayEquals(null, expecteds, actuals);
405 }
406
407 /**
408 * Asserts that two int arrays are equal. If they are not, an
409 * {@link AssertionError} is thrown with the given message.
410 *
411 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
412 * okay)
413 * @param expecteds int array with expected values.
414 * @param actuals int array with actual values
415 */
416 public static void assertArrayEquals(String message, int[] expecteds,
417 int[] actuals) throws ArrayComparisonFailure {
418 internalArrayEquals(message, expecteds, actuals);
419 }
420
421 /**
422 * Asserts that two int arrays are equal. If they are not, an
423 * {@link AssertionError} is thrown.
424 *
425 * @param expecteds int array with expected values.
426 * @param actuals int array with actual values
427 */
428 public static void assertArrayEquals(int[] expecteds, int[] actuals) {
429 assertArrayEquals(null, expecteds, actuals);
430 }
431
432 /**
433 * Asserts that two long arrays are equal. If they are not, an
434 * {@link AssertionError} is thrown with the given message.
435 *
436 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
437 * okay)
438 * @param expecteds long array with expected values.
439 * @param actuals long array with actual values
440 */
441 public static void assertArrayEquals(String message, long[] expecteds,
442 long[] actuals) throws ArrayComparisonFailure {
443 internalArrayEquals(message, expecteds, actuals);
444 }
445
446 /**
447 * Asserts that two long arrays are equal. If they are not, an
448 * {@link AssertionError} is thrown.
449 *
450 * @param expecteds long array with expected values.
451 * @param actuals long array with actual values
452 */
453 public static void assertArrayEquals(long[] expecteds, long[] actuals) {
454 assertArrayEquals(null, expecteds, actuals);
455 }
456
457 /**
458 * Asserts that two double arrays are equal. If they are not, an
459 * {@link AssertionError} is thrown with the given message.
460 *
461 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
462 * okay)
463 * @param expecteds double array with expected values.
464 * @param actuals double array with actual values
465 * @param delta the maximum delta between <code>expecteds[i]</code> and
466 * <code>actuals[i]</code> for which both numbers are still
467 * considered equal.
468 */
469 public static void assertArrayEquals(String message, double[] expecteds,
470 double[] actuals, double delta) throws ArrayComparisonFailure {
471 new InexactComparisonCriteria(delta).arrayEquals(message, expecteds, actuals);
472 }
473
474 /**
475 * Asserts that two double arrays are equal. If they are not, an
476 * {@link AssertionError} is thrown.
477 *
478 * @param expecteds double array with expected values.
479 * @param actuals double array with actual values
480 * @param delta the maximum delta between <code>expecteds[i]</code> and
481 * <code>actuals[i]</code> for which both numbers are still
482 * considered equal.
483 */
484 public static void assertArrayEquals(double[] expecteds, double[] actuals, double delta) {
485 assertArrayEquals(null, expecteds, actuals, delta);
486 }
487
488 /**
489 * Asserts that two float arrays are equal. If they are not, an
490 * {@link AssertionError} is thrown with the given message.
491 *
492 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
493 * okay)
494 * @param expecteds float array with expected values.
495 * @param actuals float array with actual values
496 * @param delta the maximum delta between <code>expecteds[i]</code> and
497 * <code>actuals[i]</code> for which both numbers are still
498 * considered equal.
499 */
500 public static void assertArrayEquals(String message, float[] expecteds,
501 float[] actuals, float delta) throws ArrayComparisonFailure {
502 new InexactComparisonCriteria(delta).arrayEquals(message, expecteds, actuals);
503 }
504
505 /**
506 * Asserts that two float arrays are equal. If they are not, an
507 * {@link AssertionError} is thrown.
508 *
509 * @param expecteds float array with expected values.
510 * @param actuals float array with actual values
511 * @param delta the maximum delta between <code>expecteds[i]</code> and
512 * <code>actuals[i]</code> for which both numbers are still
513 * considered equal.
514 */
515 public static void assertArrayEquals(float[] expecteds, float[] actuals, float delta) {
516 assertArrayEquals(null, expecteds, actuals, delta);
517 }
518
519 /**
520 * Asserts that two object arrays are equal. If they are not, an
521 * {@link AssertionError} is thrown with the given message. If
522 * <code>expecteds</code> and <code>actuals</code> are <code>null</code>,
523 * they are considered equal.
524 *
525 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
526 * okay)
527 * @param expecteds Object array or array of arrays (multi-dimensional array) with
528 * expected values.
529 * @param actuals Object array or array of arrays (multi-dimensional array) with
530 * actual values
531 */
532 private static void internalArrayEquals(String message, Object expecteds,
533 Object actuals) throws ArrayComparisonFailure {
534 new ExactComparisonCriteria().arrayEquals(message, expecteds, actuals);
535 }
536
537 /**
538 * Asserts that two doubles are equal to within a positive delta.
539 * If they are not, an {@link AssertionError} is thrown with the given
540 * message. If the expected value is infinity then the delta value is
541 * ignored. NaNs are considered equal:
542 * <code>assertEquals(Double.NaN, Double.NaN, *)</code> passes
543 *
544 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
545 * okay)
546 * @param expected expected value
547 * @param actual the value to check against <code>expected</code>
548 * @param delta the maximum delta between <code>expected</code> and
549 * <code>actual</code> for which both numbers are still
550 * considered equal.
551 */
552 public static void assertEquals(String message, double expected,
553 double actual, double delta) {
554 if (doubleIsDifferent(expected, actual, delta)) {
555 failNotEquals(message, Double.valueOf(expected), Double.valueOf(actual));
556 }
557 }
558
559 /**
560 * Asserts that two floats are equal to within a positive delta.
561 * If they are not, an {@link AssertionError} is thrown with the given
562 * message. If the expected value is infinity then the delta value is
563 * ignored. NaNs are considered equal:
564 * <code>assertEquals(Float.NaN, Float.NaN, *)</code> passes
565 *
566 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
567 * okay)
568 * @param expected expected value
569 * @param actual the value to check against <code>expected</code>
570 * @param delta the maximum delta between <code>expected</code> and
571 * <code>actual</code> for which both numbers are still
572 * considered equal.
573 */
574 public static void assertEquals(String message, float expected,
575 float actual, float delta) {
576 if (floatIsDifferent(expected, actual, delta)) {
577 failNotEquals(message, Float.valueOf(expected), Float.valueOf(actual));
578 }
579 }
580
581 /**
582 * Asserts that two floats are <b>not</b> equal to within a positive delta.
583 * If they are, an {@link AssertionError} is thrown with the given
584 * message. If the unexpected value is infinity then the delta value is
585 * ignored. NaNs are considered equal:
586 * <code>assertNotEquals(Float.NaN, Float.NaN, *)</code> fails
587 *
588 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
589 * okay)
590 * @param unexpected unexpected value
591 * @param actual the value to check against <code>unexpected</code>
592 * @param delta the maximum delta between <code>unexpected</code> and
593 * <code>actual</code> for which both numbers are still
594 * considered equal.
595 */
596 public static void assertNotEquals(String message, float unexpected,
597 float actual, float delta) {
598 if (!floatIsDifferent(unexpected, actual, delta)) {
599 failEquals(message, Float.valueOf(actual));
600 }
601 }
602
603 private static boolean doubleIsDifferent(double d1, double d2, double delta) {
604 if (Double.compare(d1, d2) == 0) {
605 return false;
606 }
607 if ((Math.abs(d1 - d2) <= delta)) {
608 return false;
609 }
610
611 return true;
612 }
613
614 private static boolean floatIsDifferent(float f1, float f2, float delta) {
615 if (Float.compare(f1, f2) == 0) {
616 return false;
617 }
618 if ((Math.abs(f1 - f2) <= delta)) {
619 return false;
620 }
621
622 return true;
623 }
624
625 /**
626 * Asserts that two longs are equal. If they are not, an
627 * {@link AssertionError} is thrown.
628 *
629 * @param expected expected long value.
630 * @param actual actual long value
631 */
632 public static void assertEquals(long expected, long actual) {
633 assertEquals(null, expected, actual);
634 }
635
636 /**
637 * Asserts that two longs are equal. If they are not, an
638 * {@link AssertionError} is thrown with the given message.
639 *
640 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
641 * okay)
642 * @param expected long expected value.
643 * @param actual long actual value
644 */
645 public static void assertEquals(String message, long expected, long actual) {
646 if (expected != actual) {
647 failNotEquals(message, Long.valueOf(expected), Long.valueOf(actual));
648 }
649 }
650
651 /**
652 * @deprecated Use
653 * <code>assertEquals(double expected, double actual, double delta)</code>
654 * instead
655 */
656 @Deprecated
657 public static void assertEquals(double expected, double actual) {
658 assertEquals(null, expected, actual);
659 }
660
661 /**
662 * @deprecated Use
663 * <code>assertEquals(String message, double expected, double actual, double delta)</code>
664 * instead
665 */
666 @Deprecated
667 public static void assertEquals(String message, double expected,
668 double actual) {
669 fail("Use assertEquals(expected, actual, delta) to compare floating-point numbers");
670 }
671
672 /**
673 * Asserts that two doubles are equal to within a positive delta.
674 * If they are not, an {@link AssertionError} is thrown. If the expected
675 * value is infinity then the delta value is ignored.NaNs are considered
676 * equal: <code>assertEquals(Double.NaN, Double.NaN, *)</code> passes
677 *
678 * @param expected expected value
679 * @param actual the value to check against <code>expected</code>
680 * @param delta the maximum delta between <code>expected</code> and
681 * <code>actual</code> for which both numbers are still
682 * considered equal.
683 */
684 public static void assertEquals(double expected, double actual, double delta) {
685 assertEquals(null, expected, actual, delta);
686 }
687
688 /**
689 * Asserts that two floats are equal to within a positive delta.
690 * If they are not, an {@link AssertionError} is thrown. If the expected
691 * value is infinity then the delta value is ignored. NaNs are considered
692 * equal: <code>assertEquals(Float.NaN, Float.NaN, *)</code> passes
693 *
694 * @param expected expected value
695 * @param actual the value to check against <code>expected</code>
696 * @param delta the maximum delta between <code>expected</code> and
697 * <code>actual</code> for which both numbers are still
698 * considered equal.
699 */
700 public static void assertEquals(float expected, float actual, float delta) {
701 assertEquals(null, expected, actual, delta);
702 }
703
704 /**
705 * Asserts that an object isn't null. If it is an {@link AssertionError} is
706 * thrown with the given message.
707 *
708 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
709 * okay)
710 * @param object Object to check or <code>null</code>
711 */
712 public static void assertNotNull(String message, Object object) {
713 assertTrue(message, object != null);
714 }
715
716 /**
717 * Asserts that an object isn't null. If it is an {@link AssertionError} is
718 * thrown.
719 *
720 * @param object Object to check or <code>null</code>
721 */
722 public static void assertNotNull(Object object) {
723 assertNotNull(null, object);
724 }
725
726 /**
727 * Asserts that an object is null. If it is not, an {@link AssertionError}
728 * is thrown with the given message.
729 *
730 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
731 * okay)
732 * @param object Object to check or <code>null</code>
733 */
734 public static void assertNull(String message, Object object) {
735 if (object == null) {
736 return;
737 }
738 failNotNull(message, object);
739 }
740
741 /**
742 * Asserts that an object is null. If it isn't an {@link AssertionError} is
743 * thrown.
744 *
745 * @param object Object to check or <code>null</code>
746 */
747 public static void assertNull(Object object) {
748 assertNull(null, object);
749 }
750
751 private static void failNotNull(String message, Object actual) {
752 String formatted = "";
753 if (message != null) {
754 formatted = message + " ";
755 }
756 fail(formatted + "expected null, but was:<" + actual + ">");
757 }
758
759 /**
760 * Asserts that two objects refer to the same object. If they are not, an
761 * {@link AssertionError} is thrown with the given message.
762 *
763 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
764 * okay)
765 * @param expected the expected object
766 * @param actual the object to compare to <code>expected</code>
767 */
768 public static void assertSame(String message, Object expected, Object actual) {
769 if (expected == actual) {
770 return;
771 }
772 failNotSame(message, expected, actual);
773 }
774
775 /**
776 * Asserts that two objects refer to the same object. If they are not the
777 * same, an {@link AssertionError} without a message is thrown.
778 *
779 * @param expected the expected object
780 * @param actual the object to compare to <code>expected</code>
781 */
782 public static void assertSame(Object expected, Object actual) {
783 assertSame(null, expected, actual);
784 }
785
786 /**
787 * Asserts that two objects do not refer to the same object. If they do
788 * refer to the same object, an {@link AssertionError} is thrown with the
789 * given message.
790 *
791 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
792 * okay)
793 * @param unexpected the object you don't expect
794 * @param actual the object to compare to <code>unexpected</code>
795 */
796 public static void assertNotSame(String message, Object unexpected,
797 Object actual) {
798 if (unexpected == actual) {
799 failSame(message);
800 }
801 }
802
803 /**
804 * Asserts that two objects do not refer to the same object. If they do
805 * refer to the same object, an {@link AssertionError} without a message is
806 * thrown.
807 *
808 * @param unexpected the object you don't expect
809 * @param actual the object to compare to <code>unexpected</code>
810 */
811 public static void assertNotSame(Object unexpected, Object actual) {
812 assertNotSame(null, unexpected, actual);
813 }
814
815 private static void failSame(String message) {
816 String formatted = "";
817 if (message != null) {
818 formatted = message + " ";
819 }
820 fail(formatted + "expected not same");
821 }
822
823 private static void failNotSame(String message, Object expected,
824 Object actual) {
825 String formatted = "";
826 if (message != null) {
827 formatted = message + " ";
828 }
829 fail(formatted + "expected same:<" + expected + "> was not:<" + actual
830 + ">");
831 }
832
833 private static void failNotEquals(String message, Object expected,
834 Object actual) {
835 fail(format(message, expected, actual));
836 }
837
838 static String format(String message, Object expected, Object actual) {
839 String formatted = "";
840 if (message != null && !"".equals(message)) {
841 formatted = message + " ";
842 }
843 String expectedString = String.valueOf(expected);
844 String actualString = String.valueOf(actual);
845 if (equalsRegardingNull(expectedString, actualString)) {
846 return formatted + "expected: "
847 + formatClassAndValue(expected, expectedString)
848 + " but was: " + formatClassAndValue(actual, actualString);
849 } else {
850 return formatted + "expected:<" + expectedString + "> but was:<"
851 + actualString + ">";
852 }
853 }
854
855 private static String formatClass(Class<?> value) {
856 String className = value.getCanonicalName();
857 return className == null ? value.getName() : className;
858 }
859
860 private static String formatClassAndValue(Object value, String valueString) {
861 String className = value == null ? "null" : value.getClass().getName();
862 return className + "<" + valueString + ">";
863 }
864
865 /**
866 * Asserts that two object arrays are equal. If they are not, an
867 * {@link AssertionError} is thrown with the given message. If
868 * <code>expecteds</code> and <code>actuals</code> are <code>null</code>,
869 * they are considered equal.
870 *
871 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
872 * okay)
873 * @param expecteds Object array or array of arrays (multi-dimensional array) with
874 * expected values.
875 * @param actuals Object array or array of arrays (multi-dimensional array) with
876 * actual values
877 * @deprecated use assertArrayEquals
878 */
879 @Deprecated
880 public static void assertEquals(String message, Object[] expecteds,
881 Object[] actuals) {
882 assertArrayEquals(message, expecteds, actuals);
883 }
884
885 /**
886 * Asserts that two object arrays are equal. If they are not, an
887 * {@link AssertionError} is thrown. If <code>expected</code> and
888 * <code>actual</code> are <code>null</code>, they are considered
889 * equal.
890 *
891 * @param expecteds Object array or array of arrays (multi-dimensional array) with
892 * expected values
893 * @param actuals Object array or array of arrays (multi-dimensional array) with
894 * actual values
895 * @deprecated use assertArrayEquals
896 */
897 @Deprecated
898 public static void assertEquals(Object[] expecteds, Object[] actuals) {
899 assertArrayEquals(expecteds, actuals);
900 }
901
902 /**
903 * Asserts that <code>actual</code> satisfies the condition specified by
904 * <code>matcher</code>. If not, an {@link AssertionError} is thrown with
905 * information about the matcher and failing value. Example:
906 *
907 * <pre>
908 * assertThat(0, is(1)); // fails:
909 * // failure message:
910 * // expected: is <1>
911 * // got value: <0>
912 * assertThat(0, is(not(1))) // passes
913 * </pre>
914 *
915 * <code>org.hamcrest.Matcher</code> does not currently document the meaning
916 * of its type parameter <code>T</code>. This method assumes that a matcher
917 * typed as <code>Matcher<T></code> can be meaningfully applied only
918 * to values that could be assigned to a variable of type <code>T</code>.
919 *
920 * @param <T> the static type accepted by the matcher (this can flag obvious
921 * compile-time problems such as {@code assertThat(1, is("a"))}
922 * @param actual the computed value being compared
923 * @param matcher an expression, built of {@link Matcher}s, specifying allowed
924 * values
925 * @see org.hamcrest.CoreMatchers
926 * @deprecated use {@code org.hamcrest.MatcherAssert.assertThat()}
927 */
928 @Deprecated
929 public static <T> void assertThat(T actual, Matcher<? super T> matcher) {
930 assertThat("", actual, matcher);
931 }
932
933 /**
934 * Asserts that <code>actual</code> satisfies the condition specified by
935 * <code>matcher</code>. If not, an {@link AssertionError} is thrown with
936 * the reason and information about the matcher and failing value. Example:
937 *
938 * <pre>
939 * assertThat("Help! Integers don't work", 0, is(1)); // fails:
940 * // failure message:
941 * // Help! Integers don't work
942 * // expected: is <1>
943 * // got value: <0>
944 * assertThat("Zero is one", 0, is(not(1))) // passes
945 * </pre>
946 *
947 * <code>org.hamcrest.Matcher</code> does not currently document the meaning
948 * of its type parameter <code>T</code>. This method assumes that a matcher
949 * typed as <code>Matcher<T></code> can be meaningfully applied only
950 * to values that could be assigned to a variable of type <code>T</code>.
951 *
952 * @param reason additional information about the error
953 * @param <T> the static type accepted by the matcher (this can flag obvious
954 * compile-time problems such as {@code assertThat(1, is("a"))}
955 * @param actual the computed value being compared
956 * @param matcher an expression, built of {@link Matcher}s, specifying allowed
957 * values
958 * @see org.hamcrest.CoreMatchers
959 * @deprecated use {@code org.hamcrest.MatcherAssert.assertThat()}
960 */
961 @Deprecated
962 public static <T> void assertThat(String reason, T actual,
963 Matcher<? super T> matcher) {
964 MatcherAssert.assertThat(reason, actual, matcher);
965 }
966
967 /**
968 * Asserts that {@code runnable} throws an exception of type {@code expectedThrowable} when
969 * executed. If it does, the exception object is returned. If it does not throw an exception, an
970 * {@link AssertionError} is thrown. If it throws the wrong type of exception, an {@code
971 * AssertionError} is thrown describing the mismatch; the exception that was actually thrown can
972 * be obtained by calling {@link AssertionError#getCause}.
973 *
974 * @param expectedThrowable the expected type of the exception
975 * @param runnable a function that is expected to throw an exception when executed
976 * @return the exception thrown by {@code runnable}
977 * @since 4.13
978 */
979 public static <T extends Throwable> T assertThrows(Class<T> expectedThrowable,
980 ThrowingRunnable runnable) {
981 return assertThrows(null, expectedThrowable, runnable);
982 }
983
984 /**
985 * Asserts that {@code runnable} throws an exception of type {@code expectedThrowable} when
986 * executed. If it does, the exception object is returned. If it does not throw an exception, an
987 * {@link AssertionError} is thrown. If it throws the wrong type of exception, an {@code
988 * AssertionError} is thrown describing the mismatch; the exception that was actually thrown can
989 * be obtained by calling {@link AssertionError#getCause}.
990 *
991 * @param message the identifying message for the {@link AssertionError} (<code>null</code>
992 * okay)
993 * @param expectedThrowable the expected type of the exception
994 * @param runnable a function that is expected to throw an exception when executed
995 * @return the exception thrown by {@code runnable}
996 * @since 4.13
997 */
998 public static <T extends Throwable> T assertThrows(String message, Class<T> expectedThrowable,
999 ThrowingRunnable runnable) {
1000 try {
1001 runnable.run();
1002 } catch (Throwable actualThrown) {
1003 if (expectedThrowable.isInstance(actualThrown)) {
1004 @SuppressWarnings("unchecked") T retVal = (T) actualThrown;
1005 return retVal;
1006 } else {
1007 String expected = formatClass(expectedThrowable);
1008 Class<? extends Throwable> actualThrowable = actualThrown.getClass();
1009 String actual = formatClass(actualThrowable);
1010 if (expected.equals(actual)) {
1011 // There must be multiple class loaders. Add the identity hash code so the message
1012 // doesn't say "expected: java.lang.String<my.package.MyException> ..."
1013 expected += "@" + Integer.toHexString(System.identityHashCode(expectedThrowable));
1014 actual += "@" + Integer.toHexString(System.identityHashCode(actualThrowable));
1015 }
1016 String mismatchMessage = buildPrefix(message)
1017 + format("unexpected exception type thrown;", expected, actual);
1018
1019 // The AssertionError(String, Throwable) ctor is only available on JDK7.
1020 AssertionError assertionError = new AssertionError(mismatchMessage);
1021 assertionError.initCause(actualThrown);
1022 throw assertionError;
1023 }
1024 }
1025 String notThrownMessage = buildPrefix(message) + String
1026 .format("expected %s to be thrown, but nothing was thrown",
1027 formatClass(expectedThrowable));
1028 throw new AssertionError(notThrownMessage);
1029 }
1030
1031 private static String buildPrefix(String message) {
1032 return message != null && message.length() != 0 ? message + ": " : "";
1033 }
1034 }