Collection Assertions

/**
 * Creates an IterableSubject for asserting about Iterable collections.
 * @param actual the Iterable under test
 */
public static IterableSubject assertThat(Iterable<?> actual);

/**
 * Fails if the collection is not empty.
 */
public void isEmpty();

/**
 * Fails if the collection is empty.
 */
public void isNotEmpty();

/**
 * Fails if the collection does not have the specified size.
 * @param expectedSize the expected number of elements
 */
public void hasSize(int expectedSize);

List<String> emptyList = new ArrayList<>();
List<String> colors = Arrays.asList("red", "green", "blue");

assertThat(emptyList).isEmpty();
assertThat(colors).isNotEmpty();
assertThat(colors).hasSize(3);

/**
 * Fails if the collection does not contain the specified element.
 * @param element the element that should be present
 */
public void contains(Object element);

/**
 * Fails if the collection contains the specified element.
 * @param element the element that should not be present
 */
public void doesNotContain(Object element);

/**
 * Fails if the collection contains duplicate elements.
 */
public void containsNoDuplicates();

List<String> fruits = Arrays.asList("apple", "banana", "cherry");

assertThat(fruits).contains("apple");
assertThat(fruits).doesNotContain("orange");

List<String> noDuplicates = Arrays.asList("a", "b", "c");
assertThat(noDuplicates).containsNoDuplicates();

/**
 * Fails if the collection is not equal to the expected object.
 * For collections, this performs element-by-element comparison.
 * @param expected the expected collection
 */
public void isEqualTo(Object expected);

/**
 * Fails if the collection does not contain at least one of the specified elements.
 * @param first the first element to check
 * @param rest additional elements to check
 */
public void containsAnyOf(Object first, Object... rest);

/**
 * Fails if the collection does not contain at least one element from the given iterable.
 * @param expected the iterable containing elements to check
 */
public void containsAnyIn(Iterable<?> expected);

/**
 * Fails if the collection does not contain at least one element from the given array.
 * @param expected the array containing elements to check
 */
public void containsAnyIn(Object[] expected);

/**
 * Fails if the collection contains any of the specified elements.
 * @param first the first element to check
 * @param rest additional elements to check
 */
public void containsNoneOf(Object first, Object... rest);

/**
 * Fails if the collection contains any element from the given iterable.
 * @param excluded the iterable containing elements that should not be present
 */
public void containsNoneIn(Iterable<?> excluded);

/**
 * Fails if the collection contains any element from the given array.
 * @param excluded the array containing elements that should not be present
 */
public void containsNoneIn(Object[] excluded);

List<String> colors = Arrays.asList("red", "green", "blue");
List<String> primaryColors = Arrays.asList("red", "blue", "yellow");
List<String> badColors = Arrays.asList("brown", "gray");

// At least one match
assertThat(colors).containsAnyOf("red", "purple", "orange");
assertThat(colors).containsAnyIn(primaryColors);
assertThat(colors).containsAnyIn(new String[]{"red", "yellow"});

// No matches
assertThat(colors).containsNoneOf("purple", "orange", "pink");
assertThat(colors).containsNoneIn(badColors);
assertThat(colors).containsNoneIn(new String[]{"brown", "gray"});

/**
 * Fails if the collection is not empty.
 */
public Ordered containsExactly();

/**
 * Fails if the collection does not contain exactly the specified elements.
 * @param first the first expected element
 * @param rest additional expected elements
 */
public Ordered containsExactly(Object first, Object... rest);

/**
 * Fails if the collection does not contain exactly the elements in the given iterable.
 * @param expected the iterable containing the expected elements
 */
public Ordered containsExactlyElementsIn(Iterable<?> expected);

/**
 * Fails if the collection does not contain exactly the elements in the given array.
 * @param expected the array containing the expected elements
 */
public Ordered containsExactlyElementsIn(Object[] expected);

List<String> empty = new ArrayList<>();
List<String> colors = Arrays.asList("red", "green", "blue");
List<String> moreColors = Arrays.asList("red", "green", "blue", "yellow");

// Exact empty match
assertThat(empty).containsExactly();

// Exact element match (order doesn't matter by default)
assertThat(colors).containsExactly("blue", "red", "green");
assertThat(colors).containsExactlyElementsIn(Arrays.asList("green", "blue", "red"));
assertThat(colors).containsExactlyElementsIn(new String[]{"blue", "green", "red"});

// With ordering constraint
assertThat(colors).containsExactly("red", "green", "blue").inOrder();
assertThat(colors).containsExactlyElementsIn(Arrays.asList("red", "green", "blue")).inOrder();

/**
 * Fails if the collection does not contain at least the specified elements.
 * @param first the first required element
 * @param rest additional required elements
 */
public void containsAtLeast(Object first, Object... rest);

/**
 * Fails if the collection does not contain at least the elements in the given iterable.
 * @param expected the iterable containing the required elements
 */
public void containsAtLeastElementsIn(Iterable<?> expected);

/**
 * Fails if the collection does not contain at least the elements in the given array.
 * @param expected the array containing the required elements
 */
public void containsAtLeastElementsIn(Object[] expected);

List<String> colors = Arrays.asList("red", "green", "blue", "yellow", "purple");

// Must contain at least these elements (can have more)
assertThat(colors).containsAtLeast("red", "blue");
assertThat(colors).containsAtLeastElementsIn(Arrays.asList("green", "yellow"));
assertThat(colors).containsAtLeastElementsIn(new String[]{"red", "purple"});

/**
 * Fails if the elements are not in natural order (according to Comparable).
 */
public void isInOrder();

/**
 * Fails if the elements are not in order according to the given comparator.
 * @param comparator the comparator to use for ordering
 */
public void isInOrder(Comparator<?> comparator);

/**
 * Fails if the elements are not in strict natural order (no equal adjacent elements).
 */
public void isInStrictOrder();

/**
 * Fails if the elements are not in strict order according to the given comparator.
 * @param comparator the comparator to use for ordering
 */
public void isInStrictOrder(Comparator<?> comparator);

import java.util.Comparator;

List<Integer> numbers = Arrays.asList(1, 2, 3, 4, 5);
List<Integer> strictNumbers = Arrays.asList(1, 3, 5, 7, 9);
List<String> words = Arrays.asList("apple", "banana", "cherry");

// Natural ordering
assertThat(numbers).isInOrder();
assertThat(strictNumbers).isInStrictOrder();
assertThat(words).isInOrder();

// Custom comparator ordering
List<String> byLength = Arrays.asList("cat", "dog", "elephant");
assertThat(byLength).isInOrder(Comparator.comparing(String::length));

// Reverse ordering
List<String> reversed = Arrays.asList("zebra", "monkey", "cat");
assertThat(reversed).isInOrder(Comparator.reverseOrder());

/**
 * Starts a method chain for a check in which the actual elements are compared to expected 
 * elements using the given Correspondence.
 * @param correspondence the correspondence to use for element comparison
 */
public <A, E> UsingCorrespondence<A, E> comparingElementsUsing(Correspondence<? super A, ? super E> correspondence);

/**
 * Starts a method chain for a check in which the actual elements are compared to expected
 * elements using the given correspondence and displays diffs using the provided formatter.
 * @param formatter the formatter to use for displaying diffs between elements
 */
public <T> UsingCorrespondence<T, T> formattingDiffsUsing(DiffFormatter<? super T, ? super T> formatter);

import com.google.common.truth.Correspondence;

// Compare strings ignoring case
Correspondence<String, String> CASE_INSENSITIVE = 
    Correspondence.from((actual, expected) -> actual.equalsIgnoreCase(expected), "ignoring case");

List<String> actualNames = Arrays.asList("Alice", "BOB", "charlie");
List<String> expectedNames = Arrays.asList("alice", "bob", "Charlie");

assertThat(actualNames)
    .comparingElementsUsing(CASE_INSENSITIVE)
    .containsExactlyElementsIn(expectedNames);

// Compare objects by specific field
Correspondence<Person, String> BY_NAME = 
    Correspondence.transforming(Person::getName, "by name");

List<Person> people = Arrays.asList(new Person("Alice"), new Person("Bob"));
assertThat(people)
    .comparingElementsUsing(BY_NAME)
    .containsExactly("Alice", "Bob");

// Testing filtered results
List<User> users = getAllUsers();
List<User> activeUsers = users.stream()
    .filter(User::isActive)
    .collect(toList());

assertThat(activeUsers).isNotEmpty();
assertThat(activeUsers).hasSize(expectedActiveCount);
assertThat(activeUsers).containsAtLeast(knownActiveUser1, knownActiveUser2);

// Testing transformation results
List<String> names = users.stream()
    .map(User::getName)
    .collect(toList());

assertThat(names).containsNoDuplicates();
assertThat(names).containsAtLeastElementsIn(expectedNames);
assertThat(names).isInOrder(String.CASE_INSENSITIVE_ORDER);

// Testing set operations
Set<String> set1 = Set.of("a", "b", "c");
Set<String> set2 = Set.of("b", "c", "d");
Set<String> intersection = Sets.intersection(set1, set2);

assertThat(intersection).containsExactly("b", "c");
assertThat(intersection).hasSize(2);

/**
 * Subject class for making assertions about Iterable collections.
 */
public class IterableSubject extends Subject {
    /**
     * Constructor for IterableSubject.
     * @param metadata failure metadata for context
     * @param actual the Iterable under test
     */
    protected IterableSubject(FailureMetadata metadata, Iterable<?> actual);
}

/**
 * Interface returned by containsExactly methods to enforce ordering constraints.
 */
public interface Ordered {
    /**
     * Enforces that the elements appear in the specified order.
     */
    void inOrder();
}

/**
 * Result of comparingElementsUsing() providing custom element comparison methods.
 */
public class UsingCorrespondence<A, E> {
    /**
     * Fails if the iterable does not contain exactly the specified elements using the correspondence.
     * @param expected the expected elements
     */
    public Ordered containsExactly(E... expected);
    
    /**
     * Fails if the iterable does not contain exactly the elements in the given iterable using the correspondence.
     * @param expected the iterable containing expected elements
     */
    public Ordered containsExactlyElementsIn(Iterable<? extends E> expected);
    
    /**
     * Fails if the iterable does not contain at least the specified elements using the correspondence.
     * @param expected the required elements
     */
    public void containsAtLeast(E... expected);
    
    /**
     * Fails if the iterable does not contain at least the elements in the given iterable using the correspondence.
     * @param expected the iterable containing required elements
     */
    public void containsAtLeastElementsIn(Iterable<? extends E> expected);
    
    /**
     * Fails if the iterable does not contain any of the specified elements using the correspondence.
     * @param expected the elements to check for
     */
    public void containsAnyOf(E... expected);
    
    /**
     * Fails if the iterable contains any of the specified elements using the correspondence.
     * @param excluded the elements that should not be present
     */
    public void containsNoneOf(E... excluded);
    
    /**
     * Fails if the iterable does not contain the expected element using the correspondence.
     * @param expected the element that should be present
     */
    public void contains(E expected);
    
    /**
     * Fails if the iterable contains the excluded element using the correspondence.
     * @param excluded the element that should not be present
     */
    public void doesNotContain(E excluded);
    
    /**
     * Specifies functions to derive keys from actual and expected elements for diff display.
     * @param actualKeyFunction function to derive keys from actual elements
     * @param expectedKeyFunction function to derive keys from expected elements
     */
    public UsingCorrespondence<A, E> displayingDiffsPairedBy(
        Function<? super A, ?> actualKeyFunction, Function<? super E, ?> expectedKeyFunction);
    
    /**
     * Specifies a function to derive keys from expected elements for diff display.
     * @param keyFunction function to derive keys from expected elements
     */
    public UsingCorrespondence<A, E> displayingDiffsPairedBy(Function<? super E, ?> keyFunction);
}