Compare the types of the expected and actual values even if their String representation spans multiple lines.

Author: cowwoc

README.md

@@ -3,7 +3,7 @@
 
 # <img src="docs/checklist.svg" width=64 height=64 alt="checklist"> Requirements API
 
-[![API](https://img.shields.io/badge/api_docs-5B45D5.svg)](https://cowwoc.github.io/requirements.java/10.6/)
+[![API](https://img.shields.io/badge/api_docs-5B45D5.svg)](https://cowwoc.github.io/requirements.java/10.7/)
 [![Changelog](https://img.shields.io/badge/changelog-A345D5.svg)](docs/changelog.md)
 [![javascript, typescript](https://img.shields.io/badge/other%20languages-javascript,%20typescript-457FD5.svg)](../../../requirements.js)
 
@@ -22,7 +22,7 @@ To get started, add this Maven dependency:
 <dependency>
   <groupId>com.github.cowwoc.requirements</groupId>
   <artifactId>java</artifactId>
-  <version>10.6</version>
+  <version>10.7</version>
 </dependency>
 ```
 
@@ -152,14 +152,14 @@ This library offers the following features:
 Designed for discovery using your favorite IDE's auto-complete feature.
 The main entry points are:
 
-* [requireThat(value, name)](https://cowwoc.github.io/requirements.java/10.6/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#requireThat(T,java.lang.String))
+* [requireThat(value, name)](https://cowwoc.github.io/requirements.java/10.7/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#requireThat(T,java.lang.String))
   for method preconditions.
-  * [that(value, name)](https://cowwoc.github.io/requirements.java/10.6/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#that(T,java.lang.String))
+  * [that(value, name)](https://cowwoc.github.io/requirements.java/10.7/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#that(T,java.lang.String))
     for [class invariants, method postconditions and private methods](docs/features.md#assertion-support). 
-  * [checkIf(value, name)](https://cowwoc.github.io/requirements.java/10.6/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#checkIf(T,java.lang.String))
+  * [checkIf(value, name)](https://cowwoc.github.io/requirements.java/10.7/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#checkIf(T,java.lang.String))
     for multiple failures and customized error handling.
 
-See the [API documentation](https://cowwoc.github.io/requirements.java/10.6/) for more details.
+See the [API documentation](https://cowwoc.github.io/requirements.java/10.7/) for more details.
 
 ## Best practices
 

docs/changelog.md

@@ -2,6 +2,10 @@ Minor updates involving cosmetic changes have been omitted from this list.
 
 See https://github.com/cowwoc/requirements.java/commits/main for a full list.
 
+## Version 10.7 - 2025/01/03
+
+* Compare the types of the expected and actual values even if their String representation spans multiple lines.
+
 ## Version 10.6 - 2025/01/01
 
 * Added `StringValidator.matches(Pattern)`.

docs/features.md

@@ -174,7 +174,7 @@ requireThat(nameToAge, "nameToAge").
 ## String diff
 
 When
-a [String comparison](https://cowwoc.github.io/requirements.java/10.6/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/type/component/ObjectValidatorComponent#isEqualTo(java.lang.Object))
+a [String comparison](https://cowwoc.github.io/requirements.java/10.7/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/type/component/ObjectValidatorComponent#isEqualTo(java.lang.Object))
 fails, the library outputs a diff of the values being compared.
 
 Depending on the terminal capability, you will see a [textual](textual_diff.md) or a [colored](colored_diff.md) diff.
@@ -188,7 +188,7 @@ terminal.
 
 The use of colors is disabled by default if stdin or stdout are redirected, even if ANSI colors are supported.
 To enable colors,
-invoke [GlobalConfiguration.terminalEncoding(TerminalEncoding)](https://cowwoc.github.io/requirements.java/10.6/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/GlobalConfiguration.html#terminalEncoding(com.github.cowwoc.requirements10.java.TerminalEncoding)).
+invoke [GlobalConfiguration.terminalEncoding(TerminalEncoding)](https://cowwoc.github.io/requirements.java/10.7/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/GlobalConfiguration.html#terminalEncoding(com.github.cowwoc.requirements10.java.TerminalEncoding)).
 
 ## Returning the value after validation
 

docs/supported_libraries.md

@@ -1,11 +1,11 @@
 Each module uses a separate class pair for validation. For example, 
-[DefaultJavaValidators](https://cowwoc.github.io/requirements.java/10.6/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html)
+[DefaultJavaValidators](https://cowwoc.github.io/requirements.java/10.7/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html)
 and
-[JavaValidators](https://cowwoc.github.io/requirements.java/10.6/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/JavaValidators.html)
+[JavaValidators](https://cowwoc.github.io/requirements.java/10.7/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/JavaValidators.html)
 validate the core Java API. Similarly,
-[DefaultGuavaValidators](https://cowwoc.github.io/requirements.java/10.6/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/guava/DefaultGuavaValidators.html)
+[DefaultGuavaValidators](https://cowwoc.github.io/requirements.java/10.7/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/guava/DefaultGuavaValidators.html)
 and
-[GuavaValidators](https://cowwoc.github.io/requirements.java/10.6/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/guava/GuavaValidators.html)
+[GuavaValidators](https://cowwoc.github.io/requirements.java/10.7/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/guava/GuavaValidators.html)
 validate the Guava API.
 
 The following table lists validators for third-party libraries: 

java/src/main/java/com/github/cowwoc/requirements10/java/internal/message/ValidatorMessages.java

@@ -53,8 +53,8 @@ public static MessageBuilder isEqualToFailed(AbstractValidator<?, ?> validator,
 		StringMappers stringMappers = validator.configuration().stringMappers();
 		String name = validator.getName();
 		Object value = validator.getValueOrDefault(null);
-		if (value == null || unnecessaryDiff(value, stringMappers) ||
-			unnecessaryDiff(expected, stringMappers))
+		if (value == null || diffIsUnnecessary(value, stringMappers) ||
+			diffIsUnnecessary(expected, stringMappers))
 		{
 			// 1. One of the values is short and simple enough to make a diff unnecessary.
 			//
@@ -88,7 +88,7 @@ public static MessageBuilder isEqualToFailed(AbstractValidator<?, ?> validator,
 	 * @param stringMappers the configuration used to map contextual values to a String
 	 * @return true if the value is short and simple enough to forego a diff
 	 */
-	private static boolean unnecessaryDiff(Object value, StringMappers stringMappers)
+	private static boolean diffIsUnnecessary(Object value, StringMappers stringMappers)
 	{
 		String valueForDiff = stringMappers.toString(value);
 		return valueForDiff.length() < MINIMUM_LENGTH_FOR_DIFF &&

java/src/main/java/com/github/cowwoc/requirements10/java/internal/message/diff/ContextGenerator.java

@@ -19,8 +19,8 @@
 import java.util.Objects;
 import java.util.SequencedMap;
 
-import static com.github.cowwoc.requirements10.java.internal.util.ValidationTarget.valid;
 import static com.github.cowwoc.requirements10.java.internal.util.ValidationTarget.invalid;
+import static com.github.cowwoc.requirements10.java.internal.util.ValidationTarget.valid;
 
 /**
  * Generates the contextual information to add to the exception message.
@@ -299,28 +299,44 @@ private List<MessageSection> getContextOfObjects()
 		assert actualValue.isValid() || expectedValue.isValid() :
 			"actualValue and expectedValue were both undefined";
 
+		// Calculate the diff
 		StringMappers stringMappers = configuration.stringMappers();
 		String actualAsString = actualValue.map(stringMappers::toString).or("");
 		String expectedAsString = expectedValue.map(stringMappers::toString).or("");
 		DiffResult lines = diffGenerator.diff(actualAsString, expectedAsString);
-		boolean diffLinesExist = !lines.getDiffLines().isEmpty();
 
+		// Don't show diff lines for boolean values
+		if (actualValue.map(v -> v instanceof Boolean).or(false) ||
+			expectedValue.map(v -> v instanceof Boolean).or(false))
+		{
+			return getContextForSingleLine(lines);
+		}
+
+		List<MessageSection> context = new ArrayList<>();
+		context.addAll(diffToMessageSections(lines));
+		context.addAll(compareTypes(lines));
+		return context;
+	}
+
+	/**
+	 * @param lines the difference between the actual and expected value
+	 * @return the difference represented as an exception message
+	 */
+	private List<MessageSection> diffToMessageSections(DiffResult lines)
+	{
 		// When comparing multiline strings, this method is invoked one line at a time. If the actual or expected
 		// value is invalid, it indicates that one of the values contains more lines than the other. The value
 		// with fewer lines will be considered invalid on a per-line basis.
 		int numberOfLines = Math.max(lines.getActualLines().size(), lines.getExpectedLines().size());
-		// Don't diff boolean values
-		if (!allowDiff || numberOfLines == 1 ||
-			actualValue.map(v -> v instanceof Boolean).or(false) ||
-			expectedValue.map(v -> v instanceof Boolean).or(false))
-		{
+		if (!allowDiff || numberOfLines == 1)
 			return getContextForSingleLine(lines);
-		}
+
 		int actualLineNumber = 0;
 		int expectedLineNumber = 0;
 		List<String> actualLines = lines.getActualLines();
 		List<String> expectedLines = lines.getExpectedLines();
 		List<Boolean> equalLines = lines.getEqualLines();
+		boolean diffLinesExist = !lines.getDiffLines().isEmpty();
 
 		// Indicates if the previous line was equal
 		boolean skippedEqualLines = false;
@@ -421,20 +437,11 @@ private List<MessageSection> getContextForSingleLine(DiffResult lines)
 		else
 			diffLine = "";
 
+		// We need to check if the values are equal because some collection elements may be equal even if the
+		// overall collections differ.
 		List<MessageSection> context = new ArrayList<>();
 		context.add(getDiffSection(actualName, actualAsString, diffLine, expectedName, expectedAsString));
-
-		if (!actualValue.equals(expectedValue) && stringRepresentationsAreEqual(lines))
-		{
-			// If the String representation of the values is equal, output getClass(), hashCode(),
-			// or System.identityHashCode() to figure out why they differ.
-			List<MessageSection> optionalContext = compareTypes();
-			if (!optionalContext.isEmpty())
-			{
-				context.add(new StringSection(""));
-				context.addAll(optionalContext);
-			}
-		}
+		context.addAll(compareTypes(lines));
 		return context;
 	}
 
@@ -448,11 +455,20 @@ private boolean stringRepresentationsAreEqual(DiffResult lines)
 	}
 
 	/**
-	 * @return the difference between the expected and actual values
+	 * If the values differ but their string representation is the same adds lines which compare getClass(),
+	 * hashCode() and/or System.identityHashCode() to figure out why they differ.
+	 *
+	 * @param lines the difference between the actual and expected value
+	 * @return an empty List if the values are equal or the string representations differ
 	 * @throws AssertionError if {@code actualName} or {@code expectedName} are null
 	 */
-	private List<MessageSection> compareTypes()
+	private List<MessageSection> compareTypes(DiffResult lines)
 	{
+		// We need to check if the values are equal because some collection elements may be equal even if the
+		// overall collections differ.
+		if (actualValue.equals(expectedValue) || !stringRepresentationsAreEqual(lines))
+			return List.of();
+
 		assert actualValue.isValid() : "actualValue was undefined";
 		assert expectedValue.isValid() : "expectedValue was undefined";
 		Object actualValueOrNull = actualValue.orThrow(AssertionError::new);
@@ -462,35 +478,45 @@ private List<MessageSection> compareTypes()
 		String expectedClassName = getClassName(getClass(actualValueOrNull));
 		if (!actualClassName.equals(expectedClassName))
 		{
-			return new ContextGenerator(scope, configuration, actualName + ".class", expectedName + ".class").
-				actualValue(actualClassName).
-				expectedValue(expectedClassName).
-				allowDiff(false).
-				build();
+			List<MessageSection> context = new ArrayList<>();
+			context.add(new StringSection(""));
+			context.addAll(
+				new ContextGenerator(scope, configuration, actualName + ".class", expectedName + ".class").
+					actualValue(actualClassName).
+					expectedValue(expectedClassName).
+					allowDiff(false).
+					build());
+			return context;
 		}
 		// Do not use config.toString() for hashCode values because their exact value does not matter, just the
 		// fact that they are different.
 		int actualHashCode = Objects.hashCode(actualValueOrNull);
 		int expectedHashCode = Objects.hashCode(expectedValueOrNull);
 		if (actualHashCode != expectedHashCode)
 		{
-			return new ContextGenerator(scope, configuration, actualName + ".hashCode",
+			List<MessageSection> context = new ArrayList<>();
+			context.add(new StringSection(""));
+			context.addAll(new ContextGenerator(scope, configuration, actualName + ".hashCode",
 				expectedName + ".hashCode").
 				actualValue(actualHashCode).
 				expectedValue(expectedHashCode).
 				allowDiff(false).
-				build();
+				build());
+			return context;
 		}
 		int actualIdentityHashCode = System.identityHashCode(actualValueOrNull);
 		int expectedIdentityHashCode = System.identityHashCode(expectedValueOrNull);
 		if (actualIdentityHashCode != expectedIdentityHashCode)
 		{
-			return new ContextGenerator(scope, configuration, actualName + ".identityHashCode",
+			List<MessageSection> context = new ArrayList<>();
+			context.add(new StringSection(""));
+			context.addAll(new ContextGenerator(scope, configuration, actualName + ".identityHashCode",
 				expectedName + ".identityHashCode").
 				actualValue(actualIdentityHashCode).
 				expectedValue(expectedIdentityHashCode).
 				allowDiff(false).
-				build();
+				build());
+			return context;
 		}
 		return List.of();
 	}

test/src/test/java/com/github/cowwoc/requirements10/test/java/ObjectTest.java

@@ -8,7 +8,6 @@
 import com.github.cowwoc.requirements10.java.internal.scope.ApplicationScope;
 import com.github.cowwoc.requirements10.java.validator.IntegerValidator;
 import com.github.cowwoc.requirements10.test.TestValidators;
-import com.github.cowwoc.requirements10.test.TestValidatorsImpl;
 import com.github.cowwoc.requirements10.test.scope.TestApplicationScope;
 import org.testng.annotations.Test;
 
@@ -104,8 +103,8 @@ public void isEqualTo_differentHashCode()
 		{
 			TestValidators validators = TestValidators.of(scope);
 
-			SameToStringDifferentHashCode actual = new SameToStringDifferentHashCode();
-			SameToStringDifferentHashCode expected = new SameToStringDifferentHashCode();
+			SameLineWithDifferentHashCode actual = new SameLineWithDifferentHashCode();
+			SameLineWithDifferentHashCode expected = new SameLineWithDifferentHashCode();
 			validators.requireThat(actual, "actual").isEqualTo(expected);
 		}
 	}
@@ -117,9 +116,9 @@ public void isEqualTo_differentIdentityHashCode()
 		{
 			TestValidators validators = TestValidators.of(scope);
 
-			SameToStringAndHashCodeDifferentIdentity actual = new SameToStringAndHashCodeDifferentIdentity();
-			SameToStringAndHashCodeDifferentIdentity expected =
-				new SameToStringAndHashCodeDifferentIdentity();
+			SameLineAndHashCodeWithDifferentIdentity actual = new SameLineAndHashCodeWithDifferentIdentity();
+			SameLineAndHashCodeWithDifferentIdentity expected =
+				new SameLineAndHashCodeWithDifferentIdentity();
 			validators.requireThat(actual, "actual").isEqualTo(expected);
 		}
 	}

test/src/test/java/com/github/cowwoc/requirements10/test/java/SameToStringAndHashCodeDifferentIdentity.java renamed to test/src/test/java/com/github/cowwoc/requirements10/test/java/SameLineAndHashCodeWithDifferentIdentity.java

@@ -5,9 +5,9 @@
 package com.github.cowwoc.requirements10.test.java;
 
 /**
- * A class whose instances have the same toString() and hashCode() values but are never equal.
+ * A class whose instances have the same single-line toString() and hashCode() values but are never equal.
  */
-public final class SameToStringAndHashCodeDifferentIdentity
+public final class SameLineAndHashCodeWithDifferentIdentity
 {
 	@Override
 	public String toString()

test/src/test/java/com/github/cowwoc/requirements10/test/java/SameToStringDifferentHashCode.java renamed to test/src/test/java/com/github/cowwoc/requirements10/test/java/SameLineWithDifferentHashCode.java

@@ -5,9 +5,9 @@
 package com.github.cowwoc.requirements10.test.java;
 
 /**
- * A class whose instances have the same toString() value but are never equal.
+ * A class whose instances have the same single-line toString() but are never equal.
  */
-public final class SameToStringDifferentHashCode
+public final class SameLineWithDifferentHashCode
 {
 	@Override
 	public String toString()

test/src/test/java/com/github/cowwoc/requirements10/test/java/SameMultilineWithDifferentHashCode.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2017 Gili Tzabari
+ * Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
+ */
+package com.github.cowwoc.requirements10.test.java;
+
+/**
+ * A class whose instances have the same multiline toString() but are never equal.
+ */
+public final class SameMultilineWithDifferentHashCode
+{
+	@Override
+	public String toString()
+	{
+		return """
+			line1
+			line2
+			line3
+			SameMultilineWithDifferentHashCode.toString()""";
+	}
+}