1 /*
2 * Copyright (c) 2013, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.
8 *
9 * This code is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12 * version 2 for more details (a copy is included in the LICENSE file that
13 * accompanied this code).
14 *
15 * You should have received a copy of the GNU General Public License version
16 * 2 along with this work; if not, write to the Free Software Foundation,
17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 *
19 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20 * or visit www.oracle.com if you need additional information or have any
21 * questions.
22 */
23
24 package jdk.test.lib;
25
26 import java.util.Objects;
27
28 /**
29 * Asserts that can be used for verifying assumptions in tests.
30 *
31 * An assertion will throw a {@link RuntimeException} if the assertion isn't true.
32 * All the asserts can be imported into a test by using a static import:
33 *
34 * <pre>
35 * {@code
36 * import static jdk.testlibrary.Asserts.*;
37 * }
38 *
39 * Always provide a message describing the assumption if the line number of the
40 * failing assertion isn't enough to understand why the assumption failed. For
41 * example, if the assertion is in a loop or in a method that is called
42 * multiple times, then the line number won't provide enough context to
43 * understand the failure.
44 * </pre>
45 */
46 public class Asserts {
47
48 /**
49 * Shorthand for {@link #assertLessThan(Comparable, Comparable)}.
50 *
51 * @param <T> a type
52 * @param lhs The left hand side of the comparison.
53 * @param rhs The right hand side of the comparison.
54 * @see #assertLessThan(Comparable, Comparable)
55 */
56 public static <T extends Comparable<T>> void assertLT(T lhs, T rhs) {
57 assertLessThan(lhs, rhs);
58 }
59
60 /**
61 * Shorthand for {@link #assertLessThan(Comparable, Comparable, String)}.
62 *
63 * @param <T> a type
64 * @param lhs The left hand side of the comparison.
65 * @param rhs The right hand side of the comparison.
66 * @param msg A description of the assumption; {@code null} for a default message.
67 * @see #assertLessThan(Comparable, Comparable, String)
68 */
69 public static <T extends Comparable<T>> void assertLT(T lhs, T rhs, String msg) {
70 assertLessThan(lhs, rhs, msg);
71 }
72
73 /**
74 * Calls {@link #assertLessThan(Comparable, Comparable, String)} with a default message.
75 *
76 * @param <T> a type
77 * @param lhs The left hand side of the comparison.
78 * @param rhs The right hand side of the comparison.
79 * @see #assertLessThan(Comparable, Comparable, String)
80 */
81 public static <T extends Comparable<T>> void assertLessThan(T lhs, T rhs) {
82 assertLessThan(lhs, rhs, null);
83 }
84
85 /**
86 * Asserts that {@code lhs} is less than {@code rhs}.
87 *
88 * @param <T> a type
89 * @param lhs The left hand side of the comparison.
90 * @param rhs The right hand side of the comparison.
91 * @param msg A description of the assumption; {@code null} for a default message.
92 * @throws RuntimeException if the assertion is not true.
93 */
94 public static <T extends Comparable<T>>void assertLessThan(T lhs, T rhs, String msg) {
95 if (!(compare(lhs, rhs, msg) < 0)) {
96 msg = Objects.toString(msg, "assertLessThan")
97 + ": expected that " + Objects.toString(lhs)
98 + " < " + Objects.toString(rhs);
99 fail(msg);
100 }
101 }
102
103 /**
104 * Shorthand for {@link #assertLessThanOrEqual(Comparable, Comparable)}.
105 *
106 * @param <T> a type
107 * @param lhs The left hand side of the comparison.
108 * @param rhs The right hand side of the comparison.
109 * @see #assertLessThanOrEqual(Comparable, Comparable)
110 */
111 public static <T extends Comparable<T>> void assertLTE(T lhs, T rhs) {
112 assertLessThanOrEqual(lhs, rhs);
113 }
114
115 /**
116 * Shorthand for {@link #assertLessThanOrEqual(Comparable, Comparable, String)}.
117 *
118 * @param <T> a type
119 * @param lhs The left hand side of the comparison.
120 * @param rhs The right hand side of the comparison.
121 * @param msg A description of the assumption; {@code null} for a default message.
122 * @see #assertLessThanOrEqual(Comparable, Comparable, String)
123 */
124 public static <T extends Comparable<T>> void assertLTE(T lhs, T rhs, String msg) {
125 assertLessThanOrEqual(lhs, rhs, msg);
126 }
127
128 /**
129 * Calls {@link #assertLessThanOrEqual(Comparable, Comparable, String)} with a default message.
130 *
131 * @param <T> a type
132 * @param lhs The left hand side of the comparison.
133 * @param rhs The right hand side of the comparison.
134 * @see #assertLessThanOrEqual(Comparable, Comparable, String)
135 */
136 public static <T extends Comparable<T>> void assertLessThanOrEqual(T lhs, T rhs) {
137 assertLessThanOrEqual(lhs, rhs, null);
138 }
139
140 /**
141 * Asserts that {@code lhs} is less than or equal to {@code rhs}.
142 *
143 * @param <T> a type
144 * @param lhs The left hand side of the comparison.
145 * @param rhs The right hand side of the comparison.
146 * @param msg A description of the assumption; {@code null} for a default message.
147 * @throws RuntimeException if the assertion is not true.
148 */
149 public static <T extends Comparable<T>> void assertLessThanOrEqual(T lhs, T rhs, String msg) {
150 if (!(compare(lhs, rhs, msg) <= 0)) {
151 msg = Objects.toString(msg, "assertLessThanOrEqual")
152 + ": expected that " + Objects.toString(lhs)
153 + " <= " + Objects.toString(rhs);
154 fail(msg);
155 }
156 }
157
158 /**
159 * Shorthand for {@link #assertEquals(Object, Object)}.
160 *
161 * @param lhs The left hand side of the comparison.
162 * @param rhs The right hand side of the comparison.
163 * @see #assertEquals(Object, Object)
164 */
165 public static void assertEQ(Object lhs, Object rhs) {
166 assertEquals(lhs, rhs);
167 }
168
169 /**
170 * Shorthand for {@link #assertEquals(Object, Object, String)}.
171 *
172 * @param lhs The left hand side of the comparison.
173 * @param rhs The right hand side of the comparison.
174 * @param msg A description of the assumption; {@code null} for a default message.
175 * @see #assertEquals(Object, Object, String)
176 */
177 public static void assertEQ(Object lhs, Object rhs, String msg) {
178 assertEquals(lhs, rhs, msg);
179 }
180
181 /**
182 * Calls {@link #assertEquals(java.lang.Object, java.lang.Object, java.lang.String)} with a default message.
183 *
184 * @param lhs The left hand side of the comparison.
185 * @param rhs The right hand side of the comparison.
186 * @see #assertEquals(Object, Object, String)
187 */
188 public static void assertEquals(Object lhs, Object rhs) {
189 assertEquals(lhs, rhs, null);
190 }
191
192 /**
193 * Asserts that {@code lhs} is equal to {@code rhs}.
194 *
195 * @param lhs The left hand side of the comparison.
196 * @param rhs The right hand side of the comparison.
197 * @param msg A description of the assumption; {@code null} for a default message.
198 * @throws RuntimeException if the assertion is not true.
199 */
200 public static void assertEquals(Object lhs, Object rhs, String msg) {
201 if ((lhs != rhs) && ((lhs == null) || !(lhs.equals(rhs)))) {
202 msg = Objects.toString(msg, "assertEquals")
203 + ": expected " + Objects.toString(lhs)
204 + " to equal " + Objects.toString(rhs);
205 fail(msg);
206 }
207 }
208
209 /**
210 * Calls {@link #assertSame(java.lang.Object, java.lang.Object, java.lang.String)} with a default message.
211 *
212 * @param lhs The left hand side of the comparison.
213 * @param rhs The right hand side of the comparison.
214 * @see #assertSame(Object, Object, String)
215 */
216 public static void assertSame(Object lhs, Object rhs) {
217 assertSame(lhs, rhs, null);
218 }
219
220 /**
221 * Asserts that {@code lhs} is the same as {@code rhs}.
222 *
223 * @param lhs The left hand side of the comparison.
224 * @param rhs The right hand side of the comparison.
225 * @param msg A description of the assumption; {@code null} for a default message.
226 * @throws RuntimeException if the assertion is not true.
227 */
228 public static void assertSame(Object lhs, Object rhs, String msg) {
229 if (lhs != rhs) {
230 msg = Objects.toString(msg, "assertSame")
231 + ": expected " + Objects.toString(lhs)
232 + " to equal " + Objects.toString(rhs);
233 fail(msg);
234 }
235 }
236
237 /**
238 * Shorthand for {@link #assertGreaterThanOrEqual(Comparable, Comparable)}.
239 *
240 * @param <T> a type
241 * @param lhs The left hand side of the comparison.
242 * @param rhs The right hand side of the comparison.
243 * @see #assertGreaterThanOrEqual(Comparable, Comparable)
244 */
245 public static <T extends Comparable<T>> void assertGTE(T lhs, T rhs) {
246 assertGreaterThanOrEqual(lhs, rhs);
247 }
248
249 /**
250 * Shorthand for {@link #assertGreaterThanOrEqual(Comparable, Comparable, String)}.
251 *
252 * @param <T> a type
253 * @param lhs The left hand side of the comparison.
254 * @param rhs The right hand side of the comparison.
255 * @param msg A description of the assumption; {@code null} for a default message.
256 * @see #assertGreaterThanOrEqual(Comparable, Comparable, String)
257 */
258 public static <T extends Comparable<T>> void assertGTE(T lhs, T rhs, String msg) {
259 assertGreaterThanOrEqual(lhs, rhs, msg);
260 }
261
262 /**
263 * Calls {@link #assertGreaterThanOrEqual(Comparable, Comparable, String)} with a default message.
264 *
265 * @param <T> a type
266 * @param lhs The left hand side of the comparison.
267 * @param rhs The right hand side of the comparison.
268 * @see #assertGreaterThanOrEqual(Comparable, Comparable, String)
269 */
270 public static <T extends Comparable<T>> void assertGreaterThanOrEqual(T lhs, T rhs) {
271 assertGreaterThanOrEqual(lhs, rhs, null);
272 }
273
274 /**
275 * Asserts that {@code lhs} is greater than or equal to {@code rhs}.
276 *
277 * @param <T> a type
278 * @param lhs The left hand side of the comparison.
279 * @param rhs The right hand side of the comparison.
280 * @param msg A description of the assumption; {@code null} for a default message.
281 * @throws RuntimeException if the assertion is not true.
282 */
283 public static <T extends Comparable<T>> void assertGreaterThanOrEqual(T lhs, T rhs, String msg) {
284 if (!(compare(lhs, rhs, msg) >= 0)) {
285 msg = Objects.toString(msg, "assertGreaterThanOrEqual")
286 + ": expected " + Objects.toString(lhs)
287 + " >= " + Objects.toString(rhs);
288 fail(msg);
289 }
290 }
291
292 /**
293 * Shorthand for {@link #assertGreaterThan(Comparable, Comparable)}.
294 *
295 * @param <T> a type
296 * @param lhs The left hand side of the comparison.
297 * @param rhs The right hand side of the comparison.
298 * @see #assertGreaterThan(Comparable, Comparable)
299 */
300 public static <T extends Comparable<T>> void assertGT(T lhs, T rhs) {
301 assertGreaterThan(lhs, rhs);
302 }
303
304 /**
305 * Shorthand for {@link #assertGreaterThan(Comparable, Comparable, String)}.
306 *
307 * @param <T> a type
308 * @param lhs the left hand value
309 * @param rhs the right hand value
310 * @param msg A description of the assumption; {@code null} for a default message.
311 * @see #assertGreaterThan(Comparable, Comparable, String)
312 */
313 public static <T extends Comparable<T>> void assertGT(T lhs, T rhs, String msg) {
314 assertGreaterThan(lhs, rhs, msg);
315 }
316
317 /**
318 * Calls {@link #assertGreaterThan(Comparable, Comparable, String)} with a default message.
319 *
320 * @param <T> a type
321 * @param lhs the left hand value
322 * @param rhs the right hand value
323 * @see #assertGreaterThan(Comparable, Comparable, String)
324 */
325 public static <T extends Comparable<T>> void assertGreaterThan(T lhs, T rhs) {
326 assertGreaterThan(lhs, rhs, null);
327 }
328
329 /**
330 * Asserts that {@code lhs} is greater than {@code rhs}.
331 *
332 * @param <T> a type
333 * @param lhs The left hand side of the comparison.
334 * @param rhs The right hand side of the comparison.
335 * @param msg A description of the assumption; {@code null} for a default message.
336 * @throws RuntimeException if the assertion is not true.
337 */
338 public static <T extends Comparable<T>> void assertGreaterThan(T lhs, T rhs, String msg) {
339 if (!(compare(lhs, rhs, msg) > 0)) {
340 msg = Objects.toString(msg, "assertGreaterThan")
341 + ": expected " + Objects.toString(lhs)
342 + " > " + Objects.toString(rhs);
343 fail(msg);
344 }
345 }
346
347 /**
348 * Shorthand for {@link #assertNotEquals(Object, Object)}.
349 *
350 * @param lhs The left hand side of the comparison.
351 * @param rhs The right hand side of the comparison.
352 * @see #assertNotEquals(Object, Object)
353 */
354 public static void assertNE(Object lhs, Object rhs) {
355 assertNotEquals(lhs, rhs);
356 }
357
358 /**
359 * Shorthand for {@link #assertNotEquals(Object, Object, String)}.
360 *
361 * @param lhs The left hand side of the comparison.
362 * @param rhs The right hand side of the comparison.
363 * @param msg A description of the assumption; {@code null} for a default message.
364 * @see #assertNotEquals(Object, Object, String)
365 */
366 public static void assertNE(Object lhs, Object rhs, String msg) {
367 assertNotEquals(lhs, rhs, msg);
368 }
369
370 /**
371 * Calls {@link #assertNotEquals(Object, Object, String)} with a default message.
372 *
373 * @param lhs The left hand side of the comparison.
374 * @param rhs The right hand side of the comparison.
375 * @see #assertNotEquals(Object, Object, String)
376 */
377 public static void assertNotEquals(Object lhs, Object rhs) {
378 assertNotEquals(lhs, rhs, null);
379 }
380
381 /**
382 * Asserts that {@code lhs} is not equal to {@code rhs}.
383 *
384 * @param lhs The left hand side of the comparison.
385 * @param rhs The right hand side of the comparison.
386 * @param msg A description of the assumption; {@code null} for a default message.
387 * @throws RuntimeException if the assertion is not true.
388 */
389 public static void assertNotEquals(Object lhs, Object rhs, String msg) {
390 if ((lhs == rhs) || (lhs != null && lhs.equals(rhs))) {
391 msg = Objects.toString(msg, "assertNotEquals")
392 + ": expected " + Objects.toString(lhs)
393 + " to not equal " + Objects.toString(rhs);
394 fail(msg);
395 }
396 }
397
398 /**
399 * Calls {@link #assertNull(Object, String)} with a default message.
400 *
401 * @param o The reference assumed to be null.
402 * @see #assertNull(Object, String)
403 */
404 public static void assertNull(Object o) {
405 assertNull(o, null);
406 }
407
408 /**
409 * Asserts that {@code o} is null.
410 *
411 * @param o The reference assumed to be null.
412 * @param msg A description of the assumption; {@code null} for a default message.
413 * @throws RuntimeException if the assertion is not true.
414 */
415 public static void assertNull(Object o, String msg) {
416 assertEquals(o, null, msg);
417 }
418
419 /**
420 * Calls {@link #assertNotNull(Object, String)} with a default message.
421 *
422 * @param o The reference assumed <i>not</i> to be null,
423 * @see #assertNotNull(Object, String)
424 */
425 public static void assertNotNull(Object o) {
426 assertNotNull(o, null);
427 }
428
429 /**
430 * Asserts that {@code o} is <i>not</i> null.
431 *
432 * @param o The reference assumed <i>not</i> to be null,
433 * @param msg A description of the assumption; {@code null} for a default message.
434 * @throws RuntimeException if the assertion is not true.
435 */
436 public static void assertNotNull(Object o, String msg) {
437 assertNotEquals(o, null, msg);
438 }
439
440 /**
441 * Calls {@link #assertFalse(boolean, String)} with a default message.
442 *
443 * @param value The value assumed to be false.
444 * @see #assertFalse(boolean, String)
445 */
446 public static void assertFalse(boolean value) {
447 assertFalse(value, null);
448 }
449
450 /**
451 * Asserts that {@code value} is {@code false}.
452 *
453 * @param value The value assumed to be false.
454 * @param msg A description of the assumption; {@code null} for a default message.
455 * @throws RuntimeException if the assertion is not true.
456 */
457 public static void assertFalse(boolean value, String msg) {
458 if (value) {
459 msg = Objects.toString(msg, "assertFalse")
460 + ": expected false, was true";
461 fail(msg);
462 }
463 }
464
465 /**
466 * Calls {@link #assertTrue(boolean, String)} with a default message.
467 *
468 * @param value The value assumed to be true.
469 * @see #assertTrue(boolean, String)
470 */
471 public static void assertTrue(boolean value) {
472 assertTrue(value, null);
473 }
474
475 /**
476 * Asserts that {@code value} is {@code true}.
477 *
478 * @param value The value assumed to be true.
479 * @param msg A description of the assumption; {@code null} for a default message.
480 * @throws RuntimeException if the assertion is not true.
481 */
482 public static void assertTrue(boolean value, String msg) {
483 if (!value) {
484 msg = Objects.toString(msg, "assertTrue")
485 + ": expected true, was false";
486 fail(msg);
487 }
488 }
489
490 private static <T extends Comparable<T>> int compare(T lhs, T rhs, String msg) {
491 if (lhs == null || rhs == null) {
492 fail(lhs, rhs, msg + ": values must be non-null:", ",");
493 }
494 return lhs.compareTo(rhs);
495 }
496
497 /**
498 * Asserts that two strings are equal.
499 *
500 * If strings are not equals, then exception message
501 * will contain {@code msg} followed by list of mismatched lines.
502 *
503 * @param str1 First string to compare.
504 * @param str2 Second string to compare.
505 * @param msg A description of the assumption.
506 * @throws RuntimeException if strings are not equal.
507 */
508 public static void assertStringsEqual(String str1, String str2,
509 String msg) {
510 String lineSeparator = System.getProperty("line.separator");
511 String str1Lines[] = str1.split(lineSeparator);
512 String str2Lines[] = str2.split(lineSeparator);
513
514 int minLength = Math.min(str1Lines.length, str2Lines.length);
515 String longestStringLines[] = ((str1Lines.length == minLength) ?
516 str2Lines : str1Lines);
517
518 boolean stringsAreDifferent = false;
519
520 StringBuilder messageBuilder = new StringBuilder(msg);
521
522 messageBuilder.append("\n");
523
524 for (int line = 0; line < minLength; line++) {
525 if (!str1Lines[line].equals(str2Lines[line])) {
526 messageBuilder.append(String.
527 format("[line %d] '%s' differs " +
528 "from '%s'\n",
529 line,
530 str1Lines[line],
531 str2Lines[line]));
532 stringsAreDifferent = true;
533 }
534 }
535
536 if (minLength < longestStringLines.length) {
537 String stringName = ((longestStringLines == str1Lines) ?
538 "first" : "second");
539 messageBuilder.append(String.format("Only %s string contains " +
540 "following lines:\n",
541 stringName));
542 stringsAreDifferent = true;
543 for(int line = minLength; line < longestStringLines.length; line++) {
544 messageBuilder.append(String.
545 format("[line %d] '%s'", line,
546 longestStringLines[line]));
547 }
548 }
549
550 if (stringsAreDifferent) {
551 fail(messageBuilder.toString());
552 }
553 }
554
555 /**
556 * Returns a string formatted with a message and expected and actual values.
557 * @param lhs the actual value
558 * @param rhs the expected value
559 * @param message the actual value
560 * @param relation the asserted relationship between lhs and rhs
561 * @return a formatted string
562 */
563 public static String format(Object lhs, Object rhs, String message, String relation) {
564 StringBuilder sb = new StringBuilder(80);
565 if (message != null) {
566 sb.append(message);
567 sb.append(' ');
568 }
569 sb.append("<");
570 sb.append(Objects.toString(lhs));
571 sb.append("> ");
572 sb.append(Objects.toString(relation, ","));
573 sb.append(" <");
574 sb.append(Objects.toString(rhs));
575 sb.append(">");
576 return sb.toString();
577 }
578
579 /**
580 * Fail reports a failure with message fail.
581 *
582 * @throws RuntimeException always
583 */
584 public static void fail() {
585 fail("fail");
586 }
587
588 /**
589 * Fail reports a failure with a message.
590 * @param message for the failure
591 * @throws RuntimeException always
592 */
593 public static void fail(String message) {
594 throw new RuntimeException(message);
595 }
596
597 /**
598 * Fail reports a failure with a formatted message.
599 *
600 * @param lhs the actual value
601 * @param rhs the expected value
602 * @param message to be format before the expected and actual values
603 * @param relation the asserted relationship between lhs and rhs
604 * @throws RuntimeException always
605 */
606 public static void fail(Object lhs, Object rhs, String message, String relation) {
607 throw new RuntimeException(format(lhs, rhs, message, relation));
608 }
609
610 /**
611 * Fail reports a failure with a message and a cause.
612 * @param message to be format before the expected and actual values
613 * @param cause the exception that caused this failure
614 * @throws RuntimeException always
615 */
616 public static void fail(String message, Throwable cause) {
617 throw new RuntimeException(message, cause);
618 }
619
620 }