1 /**
2 * Powerunit - A JDK1.8 test framework
3 * Copyright (C) 2014 Mathieu Boretti.
4 *
5 * This file is part of Powerunit
6 *
7 * Powerunit is free software: you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation, either version 3 of the License, or
10 * (at your option) any later version.
11 *
12 * Powerunit is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with Powerunit. If not, see <http://www.gnu.org/licenses/>.
19 */
20 package ch.powerunit;
21
22 import org.hamcrest.Matcher;
23 import org.hamcrest.Matchers;
24
25 /**
26 * DSL for assertion on object.
27 * <p>
28 * This interface is returned by the various methods
29 * {@link TestSuite#assertThat(Object) assertThat} exposed by {@link TestSuite}.
30 *
31 * @author borettim
32 * @param <T>
33 * the object type.
34 */
35 public interface AssertThatObject<T> {
36
37 /**
38 * Check that the object is matching the passed matcher.
39 * <p>
40 * <br>
41 * <i>By default, assertion can only be used from the main thread of the
42 * test ; When used from another thread, the assertion will be lost. In the
43 * case the {@link Test#fastFail() fastFail} attribute of {@link Test @Test}
44 * annotation is used, the assertion may not be lost, in case the thread use
45 * an assertion method from the test object instance. </i>
46 *
47 * @param matching
48 * the matcher.
49 * @return true if the assertion is valid ; If the assertion is false,
50 * depending on {@link Test#fastFail()} : If <code>true</code>, then
51 * fail the test, else, return false and the test will be failed
52 * later.
53 * @see Test#fastFail() The documentation of the <code>fastFail</code>
54 * attribute of the <code>@Test</code> annotation, regarding the action
55 * done by this assertion.
56 */
57 boolean is(Matcher<? super T> matching);
58
59 /**
60 * Check that the object is the passed one (shortcut to Matcher.equalTo).
61 * <p>
62 * This method is a shortcut to <code>is(equalTo(compareTo))</code>. <br>
63 * <br>
64 * <i>By default, assertion can only be used from the main thread of the
65 * test ; When used from another thread, the assertion will be lost. In the
66 * case the {@link Test#fastFail() fastFail} attribute of {@link Test @Test}
67 * annotation is used, the assertion may not be lost, in case the thread use
68 * an assertion method from the test object instance. </i>
69 *
70 * @param compareTo
71 * the value.
72 * @return true if the assertion is valid ; If the assertion is false,
73 * depending on {@link Test#fastFail()} : If <code>true</code>, then
74 * fail the test, else, return false and the test will be failed
75 * later.
76 * @see Test#fastFail() The documentation of the <code>fastFail</code>
77 * attribute of the <code>@Test</code> annotation, regarding the action
78 * done by this assertion.
79 */
80 default boolean is(T compareTo) {
81 return is(Matchers.equalTo(compareTo));
82 }
83
84 /**
85 * Check that the object is not the passed one.
86 * <p>
87 * This method is a shortcut to <code>isNot(equalTo(compareTo))</code>. <br>
88 * <br>
89 * <i>By default, assertion can only be used from the main thread of the
90 * test ; When used from another thread, the assertion will be lost. In the
91 * case the {@link Test#fastFail() fastFail} attribute of {@link Test @Test}
92 * annotation is used, the assertion may not be lost, in case the thread use
93 * an assertion method from the test object instance. </i>
94 *
95 * @param compareTo
96 * the value
97 * @return true if the assertion is valid ; If the assertion is false,
98 * depending on {@link Test#fastFail()} : If <code>true</code>, then
99 * fail the test, else, return false and the test will be failed
100 * later.
101 * @see Test#fastFail() The documentation of the <code>fastFail</code>
102 * attribute of the <code>@Test</code> annotation, regarding the action
103 * done by this assertion.
104 */
105 default boolean isNot(T compareTo) {
106 return isNot(Matchers.equalTo(compareTo));
107 }
108
109 /**
110 * Check that the object is not matching the passed matcher.
111 * <p>
112 * This method is a shortcut to <code>is(not(matching))</code>. <br>
113 * <br>
114 * <i>By default, assertion can only be used from the main thread of the
115 * test ; When used from another thread, the assertion will be lost. In the
116 * case the {@link Test#fastFail() fastFail} attribute of {@link Test @Test}
117 * annotation is used, the assertion may not be lost, in case the thread use
118 * an assertion method from the test object instance. </i>
119 *
120 * @param matching
121 * the matcher
122 * @return true if the assertion is valid ; If the assertion is false,
123 * depending on {@link Test#fastFail()} : If <code>true</code>, then
124 * fail the test, else, return false and the test will be failed
125 * later.
126 * @see Test#fastFail() The documentation of the <code>fastFail</code>
127 * attribute of the <code>@Test</code> annotation, regarding the action
128 * done by this assertion.
129 */
130 default boolean isNot(Matcher<T> matching) {
131 return is(Matchers.not(matching));
132 }
133
134 /**
135 * Check that the object is null.
136 * <p>
137 * This method is a shortcut to <code>is(nullValue())</code>. <br>
138 * <br>
139 * <i>By default, assertion can only be used from the main thread of the
140 * test ; When used from another thread, the assertion will be lost. In the
141 * case the {@link Test#fastFail() fastFail} attribute of {@link Test @Test}
142 * annotation is used, the assertion may not be lost, in case the thread use
143 * an assertion method from the test object instance. </i>
144 *
145 * @return true if the assertion is valid ; If the assertion is false,
146 * depending on {@link Test#fastFail()} : If <code>true</code>, then
147 * fail the test, else, return false and the test will be failed
148 * later.
149 * @see Test#fastFail() The documentation of the <code>fastFail</code>
150 * attribute of the <code>@Test</code> annotation, regarding the action
151 * done by this assertion.
152 */
153 default boolean isNull() {
154 return is(Matchers.nullValue());
155 }
156
157 /**
158 * Check that the object is not null.
159 * <p>
160 * This method is a shortcut to <code>is(notNullValue())</code>. <br>
161 * <br>
162 * <i>By default, assertion can only be used from the main thread of the
163 * test ; When used from another thread, the assertion will be lost. In the
164 * case the {@link Test#fastFail() fastFail} attribute of {@link Test @Test}
165 * annotation is used, the assertion may not be lost, in case the thread use
166 * an assertion method from the test object instance. </i>
167 *
168 * @return true if the assertion is valid ; If the assertion is false,
169 * depending on {@link Test#fastFail()} : If <code>true</code>, then
170 * fail the test, else, return false and the test will be failed
171 * later.
172 * @see Test#fastFail() The documentation of the <code>fastFail</code>
173 * attribute of the <code>@Test</code> annotation, regarding the action
174 * done by this assertion.
175 */
176 default boolean isNotNull() {
177 return is(Matchers.notNullValue());
178 }
179
180 /**
181 * Check that the object is of a specific class (or subclasses).
182 * <p>
183 * This method is a shortcut to <code>is(isA(clazz))</code>. <br>
184 * <br>
185 * <i>By default, assertion can only be used from the main thread of the
186 * test ; When used from another thread, the assertion will be lost. In the
187 * case the {@link Test#fastFail() fastFail} attribute of {@link Test @Test}
188 * annotation is used, the assertion may not be lost, in case the thread use
189 * an assertion method from the test object instance. </i>
190 *
191 * @param clazz
192 * the class
193 * @return true if the assertion is valid ; If the assertion is false,
194 * depending on {@link Test#fastFail()} : If <code>true</code>, then
195 * fail the test, else, return false and the test will be failed
196 * later.
197 * @see Test#fastFail() The documentation of the <code>fastFail</code>
198 * attribute of the <code>@Test</code> annotation, regarding the action
199 * done by this assertion.
200 */
201 default boolean isA(Class<? super T> clazz) {
202 return is(Matchers.isA(clazz));
203 }
204
205 }