1 /*
2 * Copyright 2011-2024 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package com.googlecode.catchexception.throwable.apis;
17
18 import com.googlecode.catchexception.throwable.apis.internal.hamcrest.ThrowableMessageMatcher;
19 import com.googlecode.catchexception.throwable.apis.internal.hamcrest.ThrowableNoCauseMatcher;
20
21 import org.hamcrest.Matcher;
22
23 /**
24 * Provides some Hamcrest {@link Matcher matchers} to match some {@link Throwable throwable} properties.
25 * <p>
26 * EXAMPLE: <code>// given an empty list
27 List myList = new ArrayList();
28
29 // when we try to get the first element of the list
30 catchThrowable(myList).get(1);
31
32 // then we expect an IndexOutOfBoundsThrowable with message "Index: 1, Size: 0"
33 assertThat(caughtThrowable(),
34 allOf(
35 is(IndexOutOfBoundsThrowable.class),
36 hasMessage("Index: 1, Size: 0"),
37 hasNoCause()
38 )
39 );</code>
40 * <p>
41 * To combine the standard Hamcrest matchers, your custom matchers, these matchers, and other matcher collections (as
42 * JUnitMatchers in a single class follow the instructions outlined in
43 * <a href="http://code.google.com/p/hamcrest/wiki/Tutorial#Sugar_generation">Sugar generation</a>.
44 */
45 public final class CatchThrowableHamcrestMatchers {
46
47 /**
48 * Prevent Instantiation of a new catch throwable hamcrest matchers.
49 */
50 private CatchThrowableHamcrestMatchers() {
51 // Preventing instantiation
52 }
53
54 /**
55 * EXAMPLE: <code>assertThat(caughtThrowable(), hasMessage("Index: 9, Size: 9"));</code>.
56 *
57 * @param <T>
58 * the throwable subclass
59 * @param expectedMessage
60 * the expected throwable message
61 *
62 * @return Returns a matcher that matches an throwable if it has the given message.
63 */
64 public static <T extends Throwable> Matcher<T> hasMessage(String expectedMessage) {
65 return new ThrowableMessageMatcher<>(expectedMessage);
66 }
67
68 /**
69 * EXAMPLES: <code>assertThat(caughtThrowable(), hasMessageThat(is("Index: 9, Size: 9")));
70 * assertThat(caughtThrowable(), hasMessageThat(containsString("Index: 9"))); // using JUnitMatchers
71 * assertThat(caughtThrowable(), hasMessageThat(containsPattern("Index: \\d+"))); // using Mockito's Find</code>.
72 *
73 * @param <T>
74 * the throwable subclass
75 * @param stringMatcher
76 * a string matcher
77 *
78 * @return Returns a matcher that matches an throwable if the given string matcher matches the throwable message.
79 */
80 public static <T extends Throwable> Matcher<T> hasMessageThat(Matcher<String> stringMatcher) {
81 return new ThrowableMessageMatcher<>(stringMatcher);
82 }
83
84 /**
85 * EXAMPLE: <code>assertThat(caughtThrowable(), hasNoCause());</code>.
86 *
87 * @param <T>
88 * the throwable subclass
89 *
90 * @return Returns a matcher that matches the throwable if it does not have a {@link Throwable#getCause() cause}.
91 */
92 public static <T extends Throwable> Matcher<T> hasNoCause() {
93 return new ThrowableNoCauseMatcher<>();
94 }
95
96 }