Core Assertions

/**
 * Begins a call chain with the fluent Truth API. If the check made by the chain fails, 
 * it will throw AssertionError.
 */
public static StandardSubjectBuilder assert_();

/**
 * Begins an assertion that, if it fails, will prepend the given message to the failure message.
 * @param messageToPrepend custom message to prepend to failure
 */
public static StandardSubjectBuilder assertWithMessage(String messageToPrepend);

/**
 * Begins an assertion with a formatted message using Strings.lenientFormat (supports %s only).
 * @param format format string
 * @param args arguments for format string
 */
public static StandardSubjectBuilder assertWithMessage(String format, Object... args);

import static com.google.common.truth.Truth.assertThat;
import static com.google.common.truth.Truth.assertWithMessage;

// Basic assertion
assertThat("actual").isEqualTo("expected");

// With custom message
assertWithMessage("Expected user to be active").that(user.isActive()).isTrue();

// With formatted message
assertWithMessage("User %s should have role %s", user.getName(), expectedRole)
    .that(user.getRole())
    .isEqualTo(expectedRole);

/**
 * Creates a Subject for asserting about any Object.
 * @param actual the object under test
 */
public static Subject assertThat(Object actual);

/**
 * Fails if the subject is not null.
 */
public void isNull();

/**
 * Fails if the subject is null.
 */
public void isNotNull();

/**
 * Fails if the subject is not equal to the given object (according to equals()).
 * @param expected the expected value
 */
public void isEqualTo(Object expected);

/**
 * Fails if the subject is equal to the given object (according to equals()).
 * @param expected the value that should not equal the subject
 */
public void isNotEqualTo(Object expected);

/**
 * Fails if the subject is not the same instance as the given object (== comparison).
 * @param expected the expected instance
 */
public void isSameInstanceAs(Object expected);

/**
 * Fails if the subject is the same instance as the given object (== comparison).
 * @param expected the instance that should not be the same as the subject
 */
public void isNotSameInstanceAs(Object expected);

// Null checks
assertThat(value).isNotNull();
assertThat(nullValue).isNull();

// Equality checks
assertThat("hello").isEqualTo("hello");
assertThat(42).isNotEqualTo(43);

// Identity checks
String str1 = "hello";
String str2 = "hello";
assertThat(str1).isSameInstanceAs(str1);  // Same reference
assertThat(str1).isNotSameInstanceAs(str2);  // Different references

/**
 * Fails if the subject is not an instance of the given class.
 * @param clazz the expected type
 */
public void isInstanceOf(Class<?> clazz);

/**
 * Fails if the subject is an instance of the given class.
 * @param clazz the type that the subject should not be an instance of
 */
public void isNotInstanceOf(Class<?> clazz);

assertThat("hello").isInstanceOf(String.class);
assertThat(42).isInstanceOf(Number.class);
assertThat("hello").isNotInstanceOf(Integer.class);

// Useful for polymorphic types
Animal animal = new Dog();
assertThat(animal).isInstanceOf(Dog.class);

/**
 * Fails if the subject is not equal to any element in the given iterable.
 * @param iterable the collection that should contain the subject
 */
public void isIn(Iterable<?> iterable);

/**
 * Fails if the subject is equal to any element in the given iterable.
 * @param iterable the collection that should not contain the subject
 */
public void isNotIn(Iterable<?> iterable);

/**
 * Fails if the subject is not equal to any of the given elements.
 * @param first the first element to check
 * @param rest additional elements to check
 */
public void isAnyOf(Object first, Object... rest);

/**
 * Fails if the subject is equal to any of the given elements.
 * @param first the first element to check
 * @param rest additional elements to check
 */
public void isNoneOf(Object first, Object... rest);

List<String> validColors = Arrays.asList("red", "green", "blue");
assertThat("red").isIn(validColors);
assertThat("yellow").isNotIn(validColors);

// Multiple value checks
assertThat(statusCode).isAnyOf(200, 201, 202);
assertThat(errorCode).isNoneOf(400, 401, 403, 404);

/**
 * Creates a ClassSubject for asserting about Class objects.
 * @param actual the Class under test
 */
public static ClassSubject assertThat(Class<?> actual);

/**
 * Fails if this class or interface is not the same as, or a subclass or subinterface of, the given class.
 * @param supertype the expected supertype
 */
public void isAssignableTo(Class<?> supertype);

assertThat(String.class).isAssignableTo(Object.class);
assertThat(ArrayList.class).isAssignableTo(List.class);
assertThat(Integer.class).isAssignableTo(Number.class);

/**
 * Given a factory for some Subject class, returns a builder whose that(actual) method 
 * creates instances of that class.
 * @param factory factory for creating custom subjects
 */
public static <S extends Subject, T> SimpleSubjectBuilder<S, T> assertAbout(Subject.Factory<S, T> factory);

/**
 * A generic, advanced method of extension of Truth to new types.
 * @param factory factory for creating custom subject builders
 */
public static <CustomSubjectBuilderT extends CustomSubjectBuilder> CustomSubjectBuilderT assertAbout(
    CustomSubjectBuilder.Factory<CustomSubjectBuilderT> factory);

/**
 * Factory interface for creating Subject instances.
 */
public interface Subject.Factory<SubjectT extends Subject, ActualT> {
    /**
     * Creates a new Subject.
     * @param metadata failure metadata for context
     * @param actual the value under test
     */
    SubjectT createSubject(FailureMetadata metadata, ActualT actual);
}

/**
 * Returns a new instance that invokes the given FailureStrategy when a check fails.
 * @param failureStrategy custom failure handling strategy
 */
public static StandardSubjectBuilder forCustomFailureStrategy(FailureStrategy failureStrategy);

/**
 * Sets a custom message to be prepended to failure messages.
 * @param message the message to prepend
 */
public StandardSubjectBuilder withMessage(String message);

/**
 * Sets a formatted custom message to be prepended to failure messages.
 * @param format format string using lenient formatting (supports %s only)
 * @param args arguments for the format string
 */
public StandardSubjectBuilder withMessage(String format, Object... args);

/**
 * Creates a SimpleSubjectBuilder for the given Subject factory.
 * @param factory the Subject factory
 */
public <S extends Subject, A> SimpleSubjectBuilder<S, A> about(Subject.Factory<S, A> factory);

/**
 * Creates a custom subject builder.
 * @param factory the CustomSubjectBuilder factory
 */
public <CustomSubjectBuilderT extends CustomSubjectBuilder> CustomSubjectBuilderT about(
    CustomSubjectBuilder.Factory<CustomSubjectBuilderT> factory);

/**
 * Triggers an immediate failure with the current message context.
 */
public void fail();

/**
 * Base class for all Truth subjects providing common assertion methods.
 */
public class Subject {
    /**
     * Constructor for use by subclasses.
     * @param metadata failure metadata containing context information
     * @param actual the value under test
     */
    protected Subject(FailureMetadata metadata, Object actual);
    
    /**
     * Factory interface for creating Subject instances.
     */
    public interface Factory<SubjectT extends Subject, ActualT> {
        SubjectT createSubject(FailureMetadata metadata, ActualT actual);
    }
}

/**
 * Builder class for configuring and creating Subject instances.
 */
public class StandardSubjectBuilder {
    // Methods documented above
}

/**
 * Builder for specific Subject types created via Subject.Factory.
 */
public class SimpleSubjectBuilder<S extends Subject, T> {
    /**
     * Creates a Subject instance of the specified type.
     * @param actual the value under test
     */
    public S that(T actual);
}

/**
 * Strategy interface for handling assertion failures.
 */
@FunctionalInterface
public interface FailureStrategy {
    /**
     * Handle an assertion failure.
     * @param failure the AssertionError to handle
     */
    void fail(AssertionError failure);
}

/**
 * Metadata container for failure context information.
 */
public class FailureMetadata {
    /**
     * Creates FailureMetadata with the given failure strategy.
     * @param failureStrategy the strategy for handling failures
     */
    public static FailureMetadata forFailureStrategy(FailureStrategy failureStrategy);
}