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