Created IsUnmodifiableCollection class to improve mismatch description

The mismatch description provided by anyOf() is not helpful (it just
calls toString() on the item being tested).  This is not a fault but
just a limitation of what it can do in the general case.

By providing a custom IsUnmodifiableCollection Matcher class we can
produce a better mismatch description.

Author: rmcdouga

hamcrest/src/main/java/org/hamcrest/collection/IsUnmodifiable.java

@@ -27,7 +27,7 @@ public class IsUnmodifiable {
      * @return The matcher
      */
     public static <E> Matcher<Collection<? extends E>> isUnmodifiableCollection() {
-        return anyOf(isUnmodifiableJdkCollection(), allOf(not(isModifiableJdkCollection()), isUnmodifiableCustomCollection()));
+        return new IsUnmodifiableCollection<>();
     }
 
     /**
@@ -62,6 +62,47 @@ public static <E> Matcher<Collection<? extends E>> isUnmodifiableCustomCollectio
         return new IsUnmodifiableCustomCollection<>();
     }
 
+    private static class IsUnmodifiableCollection<E> extends TypeSafeDiagnosingMatcher<Collection<? extends E>> {
+        private final Matcher<Collection<? extends E>> isUnmodifiableJdkCollection;
+        private final Matcher<Collection<? extends E>> isModifiableJdkCollection;
+        private final Matcher<Collection<? extends E>> isUnmodifiableCustomCollection;
+        
+        private IsUnmodifiableCollection() {
+            this(IsUnmodifiable.isUnmodifiableJdkCollection(), IsUnmodifiable.isModifiableJdkCollection(), IsUnmodifiable.isUnmodifiableCustomCollection());
+        }
+        
+        private IsUnmodifiableCollection(Matcher<Collection<? extends E>> isUnmodifiableJdkCollection,
+                                        Matcher<Collection<? extends E>> isModifiableJdkCollection,
+                                        Matcher<Collection<? extends E>> isUnmodifiableCustomCollection) {
+            this.isUnmodifiableJdkCollection = isUnmodifiableJdkCollection;
+            this.isModifiableJdkCollection = isModifiableJdkCollection;
+            this.isUnmodifiableCustomCollection = isUnmodifiableCustomCollection;
+        }
+
+        @Override
+        public void describeTo(Description description) {
+            description.appendText("unmodifiable collection");
+        }
+
+        @Override
+        protected boolean matchesSafely(Collection<? extends E> collection, Description mismatchDescription) {
+            if (isUnmodifiableJdkCollection.matches(collection)) {
+                return true;    // It's a known unmodifiable collection, so shortcut the remaining tests
+            }
+            if (isModifiableJdkCollection.matches(collection)) {
+                // If it's a known modifiable collection, then fail
+                mismatchDescription.appendText(collection.getClass().getName() + " is a known modifiable JDK collection");
+               return false;
+            }
+            if (!isUnmodifiableCustomCollection.matches(collection)) {
+                // If we are able to modify the collection, then fail
+                isUnmodifiableCustomCollection.describeMismatch(collection, mismatchDescription);
+                return false;
+            }
+            return true;
+        }
+    }
+    
     private static class IsUnmodifiableJdkCollection<E> extends TypeSafeDiagnosingMatcher<Collection<? extends E>> {
         private static final Set<String> KNOWN_UNMODIFIABLE_COLLECTIONS = 
                 Set.of("java.util.ImmutableCollections", 

hamcrest/src/test/java/org/hamcrest/collection/IsUnmodifiableTest.java

@@ -5,6 +5,7 @@
 import static org.hamcrest.collection.IsUnmodifiable.*;
 
 import org.hamcrest.test.AbstractMatcherTest;
+import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.Arguments;
@@ -70,23 +71,27 @@ protected Matcher<?> createMatcher() {
         return isUnmodifiableCollection();
     }
 
+    @DisplayName("IsUnmodifiableCollection() matches known unmodifiable JDK collections")
     @ParameterizedTest(name = "{1}")
     @FieldSource("JDK_KNOWN_UNMODIFIABLE_COLLECTIONS")
     public void testIsUnmodifiableMatchesKnownJdkUnmodifiableCollections(Collection<?> collection, String className) {
         assertMatches("truly unmodifiable JDK Collection (" + className + ")", isUnmodifiableCollection(), collection);
     }
 
+    @DisplayName("IsUnmodifiableCollection() mismatches known modifiable JDK collections")
     @ParameterizedTest(name = "{1}")
     @FieldSource("JDK_KNOWN_MODIFIABLE_COLLECTIONS")
     public void testIsUnmodifiableMismatchesKnownJdkModifiableCollections(Collection<?> collection, String className) {
         assertMismatchDescription(className + " is a known modifiable JDK collection", isUnmodifiableCollection(), collection);
     }
 
+    @DisplayName("IsUnmodifiableCollection() matches unmodifiable custom collection")
     @Test
     public void testIsUnmodifiableMatchesUnmodifiableCustomList() {
          assertMatches("truly unmodifiable list", isUnmodifiableCollection(), new CustomUnmodifiableList<>(Arrays.asList(1, 2, 3)));
     }
 
+    @DisplayName("IsUnmodifiableCollection() mismatches modifiable custom collection")
     @ParameterizedTest
     @FieldSource("ERROR_CONDITIONS")
     public void testIsUnmodifiableMismatchesModifiableCustomList(ModificationErrorCondition errorCondition) {
@@ -104,18 +109,21 @@ public void testIsUnmodifiableMismatchesModifiableCustomList(ModificationErrorCo
 
     // isUnmodifiableJdkCollection() tests
 
+    @DisplayName("IsUnmodifiableJdkCollection() matches known unmodifiable JDK collections")
     @ParameterizedTest(name = "{1}")
     @FieldSource("JDK_KNOWN_UNMODIFIABLE_COLLECTIONS")
     public void testIsUnmodifiableJdkCollectionMatchesKnownJdkUnmodifiableCollections(Collection<?> collection, String className) {
         assertMatches("truly unmodifiable JDK Collection (" + className + ")", isUnmodifiableJdkCollection(), collection);
     }
 
+    @DisplayName("IsUnmodifiableJdkCollection() mismatches known modifiable JDK collections")
     @ParameterizedTest(name = "{1}")
     @FieldSource("JDK_KNOWN_MODIFIABLE_COLLECTIONS")
     public void testIsUnmodifiableJdkCollectionMismatchesKnownJdkModifiableCollections(Collection<?> collection, String className) {
         assertMismatchDescription(className + " is not a known unmodifiable JDK collection", isUnmodifiableJdkCollection(), collection);
     }
 
+    @DisplayName("IsUnmodifiableJdkCollection() mismatches unmodifiable custom collection")
     @Test
     public void testIsUnmodifiableJdkCollectionMismatchesUnmodifiableCustomList() {
          CustomUnmodifiableList<Integer> testList = new CustomUnmodifiableList<>(Arrays.asList(1, 2, 3));
@@ -124,30 +132,35 @@ public void testIsUnmodifiableJdkCollectionMismatchesUnmodifiableCustomList() {
 
     // isModifiableJdkCollection() tests
 
+    @DisplayName("IsModifiableJdkCollection() mismatches known unmodifiable JDK collections")
     @ParameterizedTest(name = "{1}")
     @FieldSource("JDK_KNOWN_UNMODIFIABLE_COLLECTIONS")
     public void testIsModifiableJdkCollectionMatchesKnownJdkUnmodifiableCollections(Collection<?> collection, String className) {
         assertMismatchDescription(className + " is not a known modifiable JDK collection", isModifiableJdkCollection(), collection);
     }
 
+    @DisplayName("IsModifiableJdkCollection() matches known modifiable JDK collections")
     @ParameterizedTest(name = "{1}")
     @FieldSource("JDK_KNOWN_MODIFIABLE_COLLECTIONS")
     public void testIsModifiableJdkCollectionMatchesKnownJdkModifiableCollections(Collection<?> collection, String className) {
         assertMatches("truly unmodifiable JDK Collection (" + className + ")", isModifiableJdkCollection(), collection);
     }
 
+    @DisplayName("IsModifiableJdkCollection() mismatches modifiable custom collection")
     @Test
-    public void testIsModifiableJdkCollectionMismatchesUnmodifiableCustomList() {
-         CustomUnmodifiableList<Integer> testList = new CustomUnmodifiableList<>(Arrays.asList(1, 2, 3));
-         assertMismatchDescription(CustomUnmodifiableList.class.getName() + " is not a known modifiable JDK collection", isModifiableJdkCollection(), testList);
+    public void testIsModifiableJdkCollectionMismatchesModifiableCustomList() {
+         CustomModifiableList<Integer> testList = new CustomModifiableList<>(Arrays.asList(1, 2, 3), Set.of());
+         assertMismatchDescription(CustomModifiableList.class.getName() + " is not a known modifiable JDK collection", isModifiableJdkCollection(), testList);
     }
 
     // isUnmodifiableCustomCollection() tests
+    @DisplayName("IsUnmodifiableCustomCollection() matches unmodifiable custom collection")
     @Test
     public void testisUnmodifiableCustomCollectionMatchesUnmodifiableCustomList() {
          assertMatches("truly unmodifiable list", isUnmodifiableCustomCollection(), new CustomUnmodifiableList<>(Arrays.asList(1, 2, 3)));
     }
 
+    @DisplayName("IsUnmodifiableCustomCollection() mismatches modifiable custom collection")
     @ParameterizedTest
     @FieldSource("ERROR_CONDITIONS")
     public void testIsUnmodifiableCustomCollectionMismatchesModifiableCustomList(ModificationErrorCondition errorCondition) {