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 }