1 /* 2 * Copyright (c) 2011 Google, Inc. 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 * http://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.google.common.truth; 17 18 /** 19 * Defines what to do when a check fails. 20 * 21 * <p>This type does not appear directly in a fluent assertion chain, but you choose a {@code 22 * FailureStrategy} by choosing which method to call at the beginning of the chain. 23 * 24 * <p>Built-in strategies include: 25 * 26 * <ul> 27 * <li>{@linkplain Truth#assert_ assertions} 28 * <li>{@linkplain Expect expectations} 29 * <li>{@linkplain TruthJUnit#assume assumptions} 30 * <li>(and some useful only to people who implement custom subjects, described below) 31 * </ul> 32 * 33 * <p>For more information about the fluent chain, see <a href="https://truth.dev/faq#full-chain">this 34 * FAQ entry</a>. 35 * 36 * <h3>For people extending Truth</h3> 37 * 38 * <p>Custom {@code FailureStrategy} implementations are unusual. If you think you need one, 39 * consider these alternatives: 40 * 41 * <ul> 42 * <li>To test a custom subject, use {@link ExpectFailure}. 43 * <li>To create subjects for other objects related to your actual value (for chained assertions), 44 * use {@link Subject#check(String, Object...)}, which preserves the existing {@code 45 * FailureStrategy} and other context. 46 * <li>To return a no-op subject after a previous assertion has failed (for chained assertions), 47 * use {@link Subject#ignoreCheck} 48 * </ul> 49 * 50 * <p>When you really do need to create your own strategy, rather than expose your {@code 51 * FailureStrategy} instance to users, expose a {@link StandardSubjectBuilder} instance using {@link 52 * StandardSubjectBuilder#forCustomFailureStrategy 53 * StandardSubjectBuilder.forCustomFailureStrategy(STRATEGY)}. 54 */ 55 public interface FailureStrategy { 56 /** 57 * Handles a failure. The parameter is an {@code AssertionError} or subclass thereof, and it 58 * contains information about the failure, which may include: 59 * 60 * <ul> 61 * <li>message: {@link Throwable#getMessage getMessage()} 62 * <li>cause: {@link Throwable#getCause getCause()} 63 * <li>actual and expected values: {@link org.junit.ComparisonFailure#getActual}, {@link 64 * org.junit.ComparisonFailure#getExpected} 65 * <li>stack trace: {@link Throwable#getStackTrace} 66 * </ul> 67 * 68 * <!-- TODO(cpovirk): suppressed exceptions someday? --> 69 * 70 * <p>We encourage implementations to record as much of this information as practical in the 71 * exceptions they may throw or the other records they may make. 72 */ fail(AssertionError failure)73 void fail(AssertionError failure); 74 } 75