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
24package jdk.testlibrary;
25
26import 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
50public 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}
567