com.fitbur.assertj.api.Descriptable Maven / Gradle / Ivy
/**
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
* an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
* specific language governing permissions and limitations under the License.
*
* Copyright 2012-2016 the original author or authors.
*/
package com.fitbur.assertj.api;
import com.fitbur.assertj.description.Description;
/**
* An object that has a description.
*
* @param the "self" type of this assertion class. Please read "Emulating 'self types' using Java Generics to simplify fluent API implementation"
* for more details.
*
* @author Alex Ruiz
* @author Yvonne Wang
* @author Mikhail Mazursky
*/
public interface Descriptable> {
/**
* Sets the description of the assertion that is going to be called after.
*
* You must set it before calling the assertion otherwise it is ignored as the failing assertion breaks
* the chained call by throwing an AssertionError.
*
* The description follows {@link String#format(String, Object...)} syntax.
*
* Example :
*
try {
* // set a bad age to Mr Frodo which is really 33 years old.
* frodo.setAge(50);
* // specify a test description (call as() before the assertion !), it supports String format syntax.
* assertThat(frodo.getAge()).as("check %s's age", frodo.getName()).isEqualTo(33);
* } catch (AssertionError e) {
* assertThat(e).hasMessage("[check Frodo's age] expected:<[33]> but was:<[50]>");
* }
*
* @param description the new description to set.
* @param args optional parameter if description is a format String.
* @return {@code this} object.
* @throws NullPointerException if the description is {@code null}.
* @see #describedAs(String, Object...)
*/
S as(String description, Object... args);
/**
* Sets the description of the assertion that is going to be called after.
*
* You must set it before calling the assertion otherwise it is ignored as the failing assertion breaks
* the chained call by throwing an AssertionError.
*
* This overloaded version of "describedAs" offers more flexibility than the one taking a {@code String} by allowing
* users to pass their own implementation of a description. For example, a description that creates its value lazily,
* only when an assertion failure occurs.
*
*
* @param description the new description to set.
* @return {@code this} object.
* @throws NullPointerException if the description is {@code null}.
* @see #describedAs(Description)
*/
S as(Description description);
/**
* Sets the description of the assertion that is going to be called after.
*
* You must set it before calling the assertion otherwise it is ignored as the failing assertion breaks
* the chained call by throwing an AssertionError.
*
* Alias for {@link #as(String, Object...)} since "as" is a keyword in Groovy.
*
* @param description the new description to set.
* @return {@code this} object.
* @throws NullPointerException if the description is {@code null}.
*/
S describedAs(String description, Object... args);
/**
* Sets the description of the assertion that is going to be called after.
*
* You must set it before calling the assertion otherwise it is ignored as the failing assertion breaks
* the chained call by throwing an AssertionError.
*
* This overloaded version of "describedAs" offers more flexibility than the one taking a {@code String} by allowing
* users to pass their own implementation of a description. For example, a description that creates its value lazily,
* only when an assertion failure occurs.
*
*
* @param description the new description to set.
* @return {@code this} object.
* @throws NullPointerException if the description is {@code null}.
*/
S describedAs(Description description);
}