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.testlibrary;
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 * @deprecated This class is deprecated. Use the one from
47 * {@code <root>/test/lib/jdk/test/lib}
48 */
49 @Deprecated
50 public class Asserts {
51
52 /**
53 * Shorthand for {@link #assertLessThan(Comparable, Comparable)}.
54 *
55 * @param <T> a type
56 * @param lhs The left hand side of the comparison.
57 * @param rhs The right hand side of the comparison.
58 * @see #assertLessThan(Comparable, Comparable)
59 */
60 public static <T extends Comparable<T>> void assertLT(T lhs, T rhs) {
61 assertLessThan(lhs, rhs);
62 }
63
64 /**
65 * Shorthand for {@link #assertLessThan(Comparable, Comparable, String)}.
66 *
67 * @param <T> a type
68 * @param lhs The left hand side of the comparison.
69 * @param rhs The right hand side of the comparison.
70 * @param msg A description of the assumption; {@code null} for a default message.
71 * @see #assertLessThan(Comparable, Comparable, String)
72 */
73 public static <T extends Comparable<T>> void assertLT(T lhs, T rhs, String msg) {
74 assertLessThan(lhs, rhs, msg);
75 }
76
77 /**
78 * Calls {@link #assertLessThan(Comparable, Comparable, String)} with a default message.
79 *
80 * @param <T> a type
81 * @param lhs The left hand side of the comparison.
82 * @param rhs The right hand side of the comparison.
83 * @see #assertLessThan(Comparable, Comparable, String)
84 */
85 public static <T extends Comparable<T>> void assertLessThan(T lhs, T rhs) {
86 assertLessThan(lhs, rhs, null);
87 }
88
89 /**
90 * Asserts that {@code lhs} is less than {@code rhs}.
91 *
92 * @param <T> a type
93 * @param lhs The left hand side of the comparison.
94 * @param rhs The right hand side of the comparison.
95 * @param msg A description of the assumption; {@code null} for a default message.
96 * @throws RuntimeException if the assertion is not true.
97 */
98 public static <T extends Comparable<T>>void assertLessThan(T lhs, T rhs, String msg) {
99 if (!(compare(lhs, rhs, msg) < 0)) {
100 msg = Objects.toString(msg, "assertLessThan")
101 + ": expected that " + Objects.toString(lhs)
102 + " < " + Objects.toString(rhs);
103 fail(msg);
104 }
105 }
106
107 /**
108 * Shorthand for {@link #assertLessThanOrEqual(Comparable, Comparable)}.
109 *
110 * @param <T> a type
111 * @param lhs The left hand side of the comparison.
112 * @param rhs The right hand side of the comparison.
113 * @see #assertLessThanOrEqual(Comparable, Comparable)
114 */
115 public static <T extends Comparable<T>> void assertLTE(T lhs, T rhs) {
116 assertLessThanOrEqual(lhs, rhs);
117 }
118
119 /**
120 * Shorthand for {@link #assertLessThanOrEqual(Comparable, Comparable, String)}.
121 *
122 * @param <T> a type
123 * @param lhs The left hand side of the comparison.
124 * @param rhs The right hand side of the comparison.
125 * @param msg A description of the assumption; {@code null} for a default message.
126 * @see #assertLessThanOrEqual(Comparable, Comparable, String)
127 */
128 public static <T extends Comparable<T>> void assertLTE(T lhs, T rhs, String msg) {
129 assertLessThanOrEqual(lhs, rhs, msg);
130 }
131
132 /**
133 * Calls {@link #assertLessThanOrEqual(Comparable, Comparable, String)} with a default message.
134 *
135 * @param <T> a type
136 * @param lhs The left hand side of the comparison.
137 * @param rhs The right hand side of the comparison.
138 * @see #assertLessThanOrEqual(Comparable, Comparable, String)
139 */
140 public static <T extends Comparable<T>> void assertLessThanOrEqual(T lhs, T rhs) {
141 assertLessThanOrEqual(lhs, rhs, null);
142 }
143
144 /**
145 * Asserts that {@code lhs} is less than or equal to {@code rhs}.
146 *
147 * @param <T> a type
148 * @param lhs The left hand side of the comparison.
149 * @param rhs The right hand side of the comparison.
150 * @param msg A description of the assumption; {@code null} for a default message.
151 * @throws RuntimeException if the assertion is not true.
152 */
153 public static <T extends Comparable<T>> void assertLessThanOrEqual(T lhs, T rhs, String msg) {
154 if (!(compare(lhs, rhs, msg) <= 0)) {
155 msg = Objects.toString(msg, "assertLessThanOrEqual")
156 + ": expected that " + Objects.toString(lhs)
157 + " <= " + Objects.toString(rhs);
158 fail(msg);
159 }
160 }
161
162 /**
163 * Shorthand for {@link #assertEquals(Object, Object)}.
164 *
165 * @param lhs The left hand side of the comparison.
166 * @param rhs The right hand side of the comparison.
167 * @see #assertEquals(Object, Object)
168 */
169 public static void assertEQ(Object lhs, Object rhs) {
170 assertEquals(lhs, rhs);
171 }
172
173 /**
174 * Shorthand for {@link #assertEquals(Object, Object, String)}.
175 *
176 * @param lhs The left hand side of the comparison.
177 * @param rhs The right hand side of the comparison.
178 * @param msg A description of the assumption; {@code null} for a default message.
179 * @see #assertEquals(Object, Object, String)
180 */
181 public static void assertEQ(Object lhs, Object rhs, String msg) {
182 assertEquals(lhs, rhs, msg);
183 }
184
185 /**
186 * Calls {@link #assertEquals(java.lang.Object, java.lang.Object, java.lang.String)} with a default message.
187 *
188 * @param lhs The left hand side of the comparison.
189 * @param rhs The right hand side of the comparison.
190 * @see #assertEquals(Object, Object, String)
191 */
192 public static void assertEquals(Object lhs, Object rhs) {
193 assertEquals(lhs, rhs, null);
194 }
195
196 /**
197 * Asserts that {@code lhs} is equal to {@code rhs}.
198 *
199 * @param lhs The left hand side of the comparison.
200 * @param rhs The right hand side of the comparison.
201 * @param msg A description of the assumption; {@code null} for a default message.
202 * @throws RuntimeException if the assertion is not true.
203 */
204 public static void assertEquals(Object lhs, Object rhs, String msg) {
205 if ((lhs != rhs) && ((lhs == null) || !(lhs.equals(rhs)))) {
206 msg = Objects.toString(msg, "assertEquals")
207 + ": expected " + Objects.toString(lhs)
208 + " to equal " + Objects.toString(rhs);
209 fail(msg);
210 }
211 }
212
213 /**
214 * Calls {@link #assertSame(java.lang.Object, java.lang.Object, java.lang.String)} with a default message.
215 *
216 * @param lhs The left hand side of the comparison.
217 * @param rhs The right hand side of the comparison.
218 * @see #assertSame(Object, Object, String)
219 */
220 public static void assertSame(Object lhs, Object rhs) {
221 assertSame(lhs, rhs, null);
222 }
223
224 /**
225 * Asserts that {@code lhs} is the same as {@code rhs}.
226 *
227 * @param lhs The left hand side of the comparison.
228 * @param rhs The right hand side of the comparison.
229 * @param msg A description of the assumption; {@code null} for a default message.
230 * @throws RuntimeException if the assertion is not true.
231 */
232 public static void assertSame(Object lhs, Object rhs, String msg) {
233 if (lhs != rhs) {
234 msg = Objects.toString(msg, "assertSame")
235 + ": expected " + Objects.toString(lhs)
236 + " to equal " + Objects.toString(rhs);
237 fail(msg);
238 }
239 }
240
241 /**
242 * Shorthand for {@link #assertGreaterThanOrEqual(Comparable, Comparable)}.
243 *
244 * @param <T> a type
245 * @param lhs The left hand side of the comparison.
246 * @param rhs The right hand side of the comparison.
247 * @see #assertGreaterThanOrEqual(Comparable, Comparable)
248 */
249 public static <T extends Comparable<T>> void assertGTE(T lhs, T rhs) {
250 assertGreaterThanOrEqual(lhs, rhs);
251 }
252
253 /**
254 * Shorthand for {@link #assertGreaterThanOrEqual(Comparable, Comparable, String)}.
255 *
256 * @param <T> a type
257 * @param lhs The left hand side of the comparison.
258 * @param rhs The right hand side of the comparison.
259 * @param msg A description of the assumption; {@code null} for a default message.
260 * @see #assertGreaterThanOrEqual(Comparable, Comparable, String)
261 */
262 public static <T extends Comparable<T>> void assertGTE(T lhs, T rhs, String msg) {
263 assertGreaterThanOrEqual(lhs, rhs, msg);
264 }
265
266 /**
267 * Calls {@link #assertGreaterThanOrEqual(Comparable, Comparable, String)} with a default message.
268 *
269 * @param <T> a type
270 * @param lhs The left hand side of the comparison.
271 * @param rhs The right hand side of the comparison.
272 * @see #assertGreaterThanOrEqual(Comparable, Comparable, String)
273 */
274 public static <T extends Comparable<T>> void assertGreaterThanOrEqual(T lhs, T rhs) {
275 assertGreaterThanOrEqual(lhs, rhs, null);
276 }
277
278 /**
279 * Asserts that {@code lhs} is greater than or equal to {@code rhs}.
280 *
281 * @param <T> a type
282 * @param lhs The left hand side of the comparison.
283 * @param rhs The right hand side of the comparison.
284 * @param msg A description of the assumption; {@code null} for a default message.
285 * @throws RuntimeException if the assertion is not true.
286 */
287 public static <T extends Comparable<T>> void assertGreaterThanOrEqual(T lhs, T rhs, String msg) {
288 if (!(compare(lhs, rhs, msg) >= 0)) {
289 msg = Objects.toString(msg, "assertGreaterThanOrEqual")
290 + ": expected " + Objects.toString(lhs)
291 + " >= " + Objects.toString(rhs);
292 fail(msg);
293 }
294 }
295
296 /**
297 * Shorthand for {@link #assertGreaterThan(Comparable, Comparable)}.
298 *
299 * @param <T> a type
300 * @param lhs The left hand side of the comparison.
301 * @param rhs The right hand side of the comparison.
302 * @see #assertGreaterThan(Comparable, Comparable)
303 */
304 public static <T extends Comparable<T>> void assertGT(T lhs, T rhs) {
305 assertGreaterThan(lhs, rhs);
306 }
307
308 /**
309 * Shorthand for {@link #assertGreaterThan(Comparable, Comparable, String)}.
310 *
311 * @param <T> a type
312 * @param lhs the left hand value
313 * @param rhs the right hand value
314 * @param msg A description of the assumption; {@code null} for a default message.
315 * @see #assertGreaterThan(Comparable, Comparable, String)
316 */
317 public static <T extends Comparable<T>> void assertGT(T lhs, T rhs, String msg) {
318 assertGreaterThan(lhs, rhs, msg);
319 }
320
321 /**
322 * Calls {@link #assertGreaterThan(Comparable, Comparable, String)} with a default message.
323 *
324 * @param <T> a type
325 * @param lhs the left hand value
326 * @param rhs the right hand value
327 * @see #assertGreaterThan(Comparable, Comparable, String)
328 */
329 public static <T extends Comparable<T>> void assertGreaterThan(T lhs, T rhs) {
330 assertGreaterThan(lhs, rhs, null);
331 }
332
333 /**
334 * Asserts that {@code lhs} is greater than {@code rhs}.
335 *
336 * @param <T> a type
337 * @param lhs The left hand side of the comparison.
338 * @param rhs The right hand side of the comparison.
339 * @param msg A description of the assumption; {@code null} for a default message.
340 * @throws RuntimeException if the assertion is not true.
341 */
342 public static <T extends Comparable<T>> void assertGreaterThan(T lhs, T rhs, String msg) {
343 if (!(compare(lhs, rhs, msg) > 0)) {
344 msg = Objects.toString(msg, "assertGreaterThan")
345 + ": expected " + Objects.toString(lhs)
346 + " > " + Objects.toString(rhs);
347 fail(msg);
348 }
349 }
350
351 /**
352 * Shorthand for {@link #assertNotEquals(Object, Object)}.
353 *
354 * @param lhs The left hand side of the comparison.
355 * @param rhs The right hand side of the comparison.
356 * @see #assertNotEquals(Object, Object)
357 */
358 public static void assertNE(Object lhs, Object rhs) {
359 assertNotEquals(lhs, rhs);
360 }
361
362 /**
363 * Shorthand for {@link #assertNotEquals(Object, Object, String)}.
364 *
365 * @param lhs The left hand side of the comparison.
366 * @param rhs The right hand side of the comparison.
367 * @param msg A description of the assumption; {@code null} for a default message.
368 * @see #assertNotEquals(Object, Object, String)
369 */
370 public static void assertNE(Object lhs, Object rhs, String msg) {
371 assertNotEquals(lhs, rhs, msg);
372 }
373
374 /**
375 * Calls {@link #assertNotEquals(Object, Object, String)} with a default message.
376 *
377 * @param lhs The left hand side of the comparison.
378 * @param rhs The right hand side of the comparison.
379 * @see #assertNotEquals(Object, Object, String)
380 */
381 public static void assertNotEquals(Object lhs, Object rhs) {
382 assertNotEquals(lhs, rhs, null);
383 }
384
385 /**
386 * Asserts that {@code lhs} is not equal to {@code rhs}.
387 *
388 * @param lhs The left hand side of the comparison.
389 * @param rhs The right hand side of the comparison.
390 * @param msg A description of the assumption; {@code null} for a default message.
391 * @throws RuntimeException if the assertion is not true.
392 */
393 public static void assertNotEquals(Object lhs, Object rhs, String msg) {
394 if ((lhs == rhs) || (lhs != null && lhs.equals(rhs))) {
395 msg = Objects.toString(msg, "assertNotEquals")
396 + ": expected " + Objects.toString(lhs)
397 + " to not equal " + Objects.toString(rhs);
398 fail(msg);
399 }
400 }
401
402 /**
403 * Calls {@link #assertNull(Object, String)} with a default message.
404 *
405 * @param o The reference assumed to be null.
406 * @see #assertNull(Object, String)
407 */
408 public static void assertNull(Object o) {
409 assertNull(o, null);
410 }
411
412 /**
413 * Asserts that {@code o} is null.
414 *
415 * @param o The reference assumed to be null.
416 * @param msg A description of the assumption; {@code null} for a default message.
417 * @throws RuntimeException if the assertion is not true.
418 */
419 public static void assertNull(Object o, String msg) {
420 assertEquals(o, null, msg);
421 }
422
423 /**
424 * Calls {@link #assertNotNull(Object, String)} with a default message.
425 *
426 * @param o The reference assumed <i>not</i> to be null,
427 * @see #assertNotNull(Object, String)
428 */
429 public static void assertNotNull(Object o) {
430 assertNotNull(o, null);
431 }
432
433 /**
434 * Asserts that {@code o} is <i>not</i> null.
435 *
436 * @param o The reference assumed <i>not</i> to be null,
437 * @param msg A description of the assumption; {@code null} for a default message.
438 * @throws RuntimeException if the assertion is not true.
439 */
440 public static void assertNotNull(Object o, String msg) {
441 assertNotEquals(o, null, msg);
442 }
443
444 /**
445 * Calls {@link #assertFalse(boolean, String)} with a default message.
446 *
447 * @param value The value assumed to be false.
448 * @see #assertFalse(boolean, String)
449 */
450 public static void assertFalse(boolean value) {
451 assertFalse(value, null);
452 }
453
454 /**
455 * Asserts that {@code value} is {@code false}.
456 *
457 * @param value The value assumed to be false.
458 * @param msg A description of the assumption; {@code null} for a default message.
459 * @throws RuntimeException if the assertion is not true.
460 */
461 public static void assertFalse(boolean value, String msg) {
462 if (value) {
463 msg = Objects.toString(msg, "assertFalse")
464 + ": expected false, was true";
465 fail(msg);
466 }
467 }
468
469 /**
470 * Calls {@link #assertTrue(boolean, String)} with a default message.
471 *
472 * @param value The value assumed to be true.
473 * @see #assertTrue(boolean, String)
474 */
475 public static void assertTrue(boolean value) {
476 assertTrue(value, null);
477 }
478
479 /**
480 * Asserts that {@code value} is {@code true}.
481 *
482 * @param value The value assumed to be true.
483 * @param msg A description of the assumption; {@code null} for a default message.
484 * @throws RuntimeException if the assertion is not true.
485 */
486 public static void assertTrue(boolean value, String msg) {
487 if (!value) {
488 msg = Objects.toString(msg, "assertTrue")
489 + ": expected true, was false";
490 fail(msg);
491 }
492 }
493
494 private static <T extends Comparable<T>> int compare(T lhs, T rhs, String msg) {
495 if (lhs == null || rhs == null) {
496 fail(lhs, rhs, msg + ": values must be non-null:", ",");
497 }
498 return lhs.compareTo(rhs);
499 }
500
501 /**
502 * Returns a string formatted with a message and expected and actual values.
503 * @param lhs the actual value
504 * @param rhs the expected value
505 * @param message the actual value
506 * @param relation the asserted relationship between lhs and rhs
507 * @return a formatted string
508 */
509 public static String format(Object lhs, Object rhs, String message, String relation) {
510 StringBuilder sb = new StringBuilder(80);
511 if (message != null) {
512 sb.append(message);
513 sb.append(' ');
514 }
515 sb.append("<");
516 sb.append(Objects.toString(lhs));
517 sb.append("> ");
518 sb.append(Objects.toString(relation, ","));
519 sb.append(" <");
520 sb.append(Objects.toString(rhs));
521 sb.append(">");
522 return sb.toString();
523 }
524
525 /**
526 * Fail reports a failure with message fail.
527 *
528 * @throws RuntimeException always
529 */
530 public static void fail() {
531 fail("fail");
532 }
533
534 /**
535 * Fail reports a failure with a message.
536 * @param message for the failure
537 * @throws RuntimeException always
538 */
539 public static void fail(String message) {
540 throw new RuntimeException(message);
541 }
542
543 /**
544 * Fail reports a failure with a formatted message.
545 *
546 * @param lhs the actual value
547 * @param rhs the expected value
548 * @param message to be format before the expected and actual values
549 * @param relation the asserted relationship between lhs and rhs
550 * @throws RuntimeException always
551 */
552 public static void fail(Object lhs, Object rhs, String message, String relation) {
553 throw new RuntimeException(format(lhs, rhs, message, relation));
554 }
555
556 /**
557 * Fail reports a failure with a message and a cause.
558 * @param message to be format before the expected and actual values
559 * @param cause the exception that caused this failure
560 * @throws RuntimeException always
561 */
562 public static void fail(String message, Throwable cause) {
563 throw new RuntimeException(message, cause);
564 }
565
566 }