Keep one frame from Assertions for clarity

mpkorstanje · mpkorstanje · commit e78114e6d579 · 2025-11-21T16:02:10.000+01:00
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertArrayEquals.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertArrayEquals.java
@@ -483,7 +483,7 @@ private static AssertionFailedError expectedArrayIsNullFailure(@Nullable Deque<I
 		return assertionFailure() //
 				.message(messageOrSupplier) //
 				.reason("expected array was <null>" + formatIndexes(indexes)) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.build();
 	}
 
@@ -496,7 +496,7 @@ private static AssertionFailedError actualArrayIsNullFailure(@Nullable Deque<Int
 		return assertionFailure() //
 				.message(messageOrSupplier) //
 				.reason("actual array was <null>" + formatIndexes(indexes)) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.build();
 	}
 
@@ -509,7 +509,7 @@ private static void assertArraysHaveSameLength(int expected, int actual, @Nullab
 					.reason("array lengths differ" + formatIndexes(indexes)) //
 					.expected(expected) //
 					.actual(actual) //
-					.trimStacktrace(Assertions.class) //
+					.trimStacktrace(Assertions.class, 1) //
 					.buildAndThrow();
 		}
 	}
@@ -522,7 +522,7 @@ private static void failArraysNotEqual(@Nullable Object expected, @Nullable Obje
 				.reason("array contents differ" + formatIndexes(indexes)) //
 				.expected(expected) //
 				.actual(actual) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.buildAndThrow();
 	}
 
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertDoesNotThrow.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertDoesNotThrow.java
@@ -87,7 +87,7 @@ public static AssertionFailedError createAssertionFailedError(@Nullable Object m
 				.message(messageOrSupplier) //
 				.reason("Unexpected exception thrown: " + t.getClass().getName() + buildSuffix(t.getMessage())) //
 				.cause(t) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.build();
 	}
 
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertEquals.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertEquals.java
@@ -198,7 +198,7 @@ private static void failNotEqual(@Nullable Object expected, @Nullable Object act
 				.message(messageOrSupplier) //
 				.expected(expected) //
 				.actual(actual) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.buildAndThrow();
 	}
 }
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertFalse.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertFalse.java
@@ -66,7 +66,7 @@ private static void failNotFalse(@Nullable Object messageOrSupplier) {
 				.message(messageOrSupplier) //
 				.expected(false) //
 				.actual(true) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.buildAndThrow();
 	}
 
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertInstanceOf.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertInstanceOf.java
@@ -56,7 +56,7 @@ private static <T> T assertInstanceOf(Class<T> expectedType, @Nullable Object ac
 					.expected(expectedType) //
 					.actual(actualValue == null ? null : actualValue.getClass()) //
 					.cause(actualValue instanceof Throwable t ? t : null) //
-					.trimStacktrace(Assertions.class) //
+					.trimStacktrace(Assertions.class, 1) //
 					.buildAndThrow();
 		}
 		return expectedType.cast(actualValue);
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertIterableEquals.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertIterableEquals.java
@@ -153,7 +153,7 @@ private static AssertionFailedError expectedIterableIsNullFailure(Deque<Integer>
 		return assertionFailure() //
 				.message(messageOrSupplier) //
 				.reason("expected iterable was <null>" + formatIndexes(indexes)) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.build();
 	}
 
@@ -166,7 +166,7 @@ private static AssertionFailedError actualIterableIsNullFailure(Deque<Integer> i
 		return assertionFailure() //
 				.message(messageOrSupplier) //
 				.reason("actual iterable was <null>" + formatIndexes(indexes)) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.build();
 	}
 
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertLinesMatch.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertLinesMatch.java
@@ -193,7 +193,7 @@ void fail(String format, Object... args) {
 					.expected(join(newLine, expectedLines)) //
 					.actual(join(newLine, actualLines)) //
 					.includeValuesInMessage(false) //
-					.trimStacktrace(Assertions.class) //
+					.trimStacktrace(Assertions.class, 1) //
 					.buildAndThrow();
 		}
 	}
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertNotEquals.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertNotEquals.java
@@ -279,7 +279,7 @@ private static void failEqual(@Nullable Object actual, @Nullable Object messageO
 		assertionFailure() //
 				.message(messageOrSupplier) //
 				.reason("expected: not equal but was: <" + actual + ">") //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.buildAndThrow();
 	}
 
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertNotNull.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertNotNull.java
@@ -52,7 +52,7 @@ private static void failNull(@Nullable Object messageOrSupplier) {
 		assertionFailure() //
 				.message(messageOrSupplier) //
 				.reason("expected: not <null>") //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.buildAndThrow();
 	}
 }
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertNotSame.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertNotSame.java
@@ -49,7 +49,7 @@ private static void failSame(@Nullable Object actual, @Nullable Object messageOr
 		assertionFailure() //
 				.message(messageOrSupplier) //
 				.reason("expected: not same but was: <" + actual + ">") //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.buildAndThrow();
 	}
 
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertNull.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertNull.java
@@ -53,7 +53,7 @@ private static void failNotNull(@Nullable Object actual, @Nullable Object messag
 				.message(messageOrSupplier) //
 				.expected(null) //
 				.actual(actual) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.buildAndThrow();
 	}
 
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertSame.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertSame.java
@@ -51,7 +51,7 @@ private static void failNotSame(@Nullable Object expected, @Nullable Object actu
 				.message(messageOrSupplier) //
 				.expected(expected) //
 				.actual(actual) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.buildAndThrow();
 	}
 
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertThrows.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertThrows.java
@@ -65,14 +65,14 @@ private static <T extends Throwable> T assertThrows(Class<T> expectedType, Execu
 						.actual(actualException.getClass()) //
 						.reason("Unexpected exception type thrown") //
 						.cause(actualException) //
-						.trimStacktrace(Assertions.class) //
+						.trimStacktrace(Assertions.class, 1) //
 						.build();
 			}
 		}
 		throw assertionFailure() //
 				.message(messageOrSupplier) //
 				.reason("Expected %s to be thrown, but nothing was thrown.".formatted(getCanonicalName(expectedType))) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.build();
 	}
 
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertThrowsExactly.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertThrowsExactly.java
@@ -65,15 +65,15 @@ private static <T extends Throwable> T assertThrowsExactly(Class<T> expectedType
 						.actual(actualException.getClass()) //
 						.reason("Unexpected exception type thrown") //
 						.cause(actualException) //
-						.trimStacktrace(Assertions.class) //
+						.trimStacktrace(Assertions.class, 1) //
 						.build();
 			}
 		}
 
 		throw assertionFailure() //
 				.message(messageOrSupplier) //
 				.reason("Expected %s to be thrown, but nothing was thrown.".formatted(getCanonicalName(expectedType))) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.build();
 	}
 
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertTimeout.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertTimeout.java
@@ -82,7 +82,7 @@ static void assertTimeout(Duration timeout, Executable executable, Supplier<@Nul
 					.message(messageOrSupplier) //
 					.reason("execution exceeded timeout of " + timeoutInMillis + " ms by "
 							+ (timeElapsed - timeoutInMillis) + " ms") //
-					.trimStacktrace(Assertions.class) //
+					.trimStacktrace(Assertions.class, 1) //
 					.buildAndThrow();
 		}
 		return result;
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertTimeoutPreemptively.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertTimeoutPreemptively.java
@@ -73,7 +73,7 @@ private static AssertionFailedError createAssertionFailure(Duration timeout,
 				.message(messageSupplier) //
 				.reason("execution timed out after " + timeout.toMillis() + " ms") //
 				.cause(cause) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.build();
 	}
 
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertTrue.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertTrue.java
@@ -66,7 +66,7 @@ private static void failNotTrue(@Nullable Object messageOrSupplier) {
 				.message(messageOrSupplier) //
 				.expected(true) //
 				.actual(false) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.buildAndThrow();
 	}
 
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertionFailureBuilder.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertionFailureBuilder.java
@@ -19,6 +19,7 @@
 
 import org.apiguardian.api.API;
 import org.jspecify.annotations.Nullable;
+import org.junit.platform.commons.util.Preconditions;
 import org.junit.platform.commons.util.StringUtils;
 import org.opentest4j.AssertionFailedError;
 
@@ -48,7 +49,9 @@ public class AssertionFailureBuilder {
 
 	private boolean includeValuesInMessage = true;
 
-	private @Nullable Class<?> trimStackTraceTo;
+	private @Nullable Class<?> trimStackTraceBefore;
+
+	private int trimStackTraceRetain;
 
 	/**
 	 * Create a new {@code AssertionFailureBuilder}.
@@ -135,17 +138,21 @@ public AssertionFailureBuilder includeValuesInMessage(boolean includeValuesInMes
 	}
 
 	/**
-	 * Set class to trim from the stacktrace.
+	 * Set target and depth for trimming stacktrace.
 	 *
-	 * <p>To improve the readability of assertion failures, stack-frames up to
-	 * and including any frames from {@code to} are trimmed from the stacktrace.
+	 * <p>Removes all but {@code retain - 1} frames before the last frame from
+	 * {@code target}. If {@code retain} is zero, all frames before the last frame from
+	 * {@code target} are trimmed.
 	 *
-	 * @param to class to prune from the stacktrace.
+	 * @param target class to trim from the stacktrace
+	 * @param retain depth of trimming, must be non-negative
 	 * @return this builder for method chaining
 	 */
 	@API(status = EXPERIMENTAL, since = "6.1")
-	public AssertionFailureBuilder trimStacktrace(@Nullable Class<?> to) {
-		this.trimStackTraceTo = to;
+	public AssertionFailureBuilder trimStacktrace(@Nullable Class<?> target, int retain) {
+		Preconditions.condition(retain >= 0, "retain must have a non-negative value");
+		this.trimStackTraceBefore = target;
+		this.trimStackTraceRetain = retain;
 		return this;
 	}
 
@@ -183,11 +190,11 @@ public AssertionFailedError build() {
 	}
 
 	private void maybeTrimStackTrace(Throwable throwable) {
-		if (trimStackTraceTo == null) {
+		if (trimStackTraceBefore == null) {
 			return;
 		}
 
-		var pruneTargetClassName = trimStackTraceTo.getName();
+		var pruneTargetClassName = trimStackTraceBefore.getName();
 		var stackTrace = throwable.getStackTrace();
 
 		int lastIndexOf = -1;
@@ -200,12 +207,16 @@ private void maybeTrimStackTrace(Throwable throwable) {
 		}
 
 		if (lastIndexOf != -1) {
-			int from = Math.min(lastIndexOf + 1, stackTrace.length);
+			int from = clamp(lastIndexOf + 1 - trimStackTraceRetain, stackTrace.length);
 			var pruned = Arrays.copyOfRange(stackTrace, from, stackTrace.length);
 			throwable.setStackTrace(pruned);
 		}
 	}
 
+	private static int clamp(int value, int max) {
+		return Math.max(0, Math.min(value, max));
+	}
+
 	private static @Nullable String nullSafeGet(@Nullable Object messageOrSupplier) {
 		if (messageOrSupplier == null) {
 			return null;
diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertionUtils.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertionUtils.java
@@ -35,15 +35,15 @@ private AssertionUtils() {
 	@Contract(" -> fail")
 	static void fail() {
 		throw assertionFailure() //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.build();
 	}
 
 	@Contract("_ -> fail")
 	static void fail(@Nullable String message) {
 		throw assertionFailure() //
 				.message(message) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.build();
 	}
 
@@ -52,23 +52,23 @@ static void fail(@Nullable String message, @Nullable Throwable cause) {
 		throw assertionFailure() //
 				.message(message) //
 				.cause(cause) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.build();
 	}
 
 	@Contract("_ -> fail")
 	static void fail(@Nullable Throwable cause) {
 		throw assertionFailure() //
 				.cause(cause) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.build();
 	}
 
 	@Contract("_ -> fail")
 	static void fail(Supplier<@Nullable String> messageSupplier) {
 		throw assertionFailure() //
 				.message(nullSafeGet(messageSupplier)) //
-				.trimStacktrace(Assertions.class) //
+				.trimStacktrace(Assertions.class, 1) //
 				.build();
 	}
 
diff --git a/junit-jupiter-api/src/main/kotlin/org/junit/jupiter/api/Assertions.kt b/junit-jupiter-api/src/main/kotlin/org/junit/jupiter/api/Assertions.kt
@@ -363,7 +363,8 @@ inline fun <R> assertDoesNotThrow(executable: () -> R): R {
         throw assertionFailure()
             .reason("Unexpected exception thrown: ${t.javaClass.getName()}$suffix")
             .cause(t)
-            .trimStacktrace(AssertionFailureBuilder::class.java)
+            // we don't want to retain any frames from the AssertionFailureBuilder
+            .trimStacktrace(AssertionFailureBuilder::class.java, 0)
             .build()
     }
 }
@@ -421,7 +422,8 @@ inline fun <R> assertDoesNotThrow(
             .message(message())
             .reason("Unexpected exception thrown: ${t.javaClass.getName()}$suffix")
             .cause(t)
-            .trimStacktrace(AssertionFailureBuilder::class.java)
+            // we don't want to retain any frames from the AssertionFailureBuilder
+            .trimStacktrace(AssertionFailureBuilder::class.java, 0)
             .build()
     }
 }
diff --git a/jupiter-tests/src/test/java/org/junit/jupiter/api/AssertionFailureBuilderTest.java b/jupiter-tests/src/test/java/org/junit/jupiter/api/AssertionFailureBuilderTest.java
diff --git a/platform-tests/src/test/java/org/junit/platform/StackTracePruningTests.java b/platform-tests/src/test/java/org/junit/platform/StackTracePruningTests.java

Original file line number	Diff line number	Diff line change
`@@ -87,7 +87,7 @@ public static AssertionFailedError createAssertionFailedError(@Nullable Object m`
`87`	`87`	`.message(messageOrSupplier) //`
`88`	`88`	`.reason("Unexpected exception thrown: " + t.getClass().getName() + buildSuffix(t.getMessage())) //`
`89`	`89`	`.cause(t) //`
`90`		`- .trimStacktrace(Assertions.class) //`
	`90`	`+ .trimStacktrace(Assertions.class, 1) //`
`91`	`91`	`.build();`
`92`	`92`	`}`
`93`	`93`
Original file line number	Diff line number	Diff line change
`@@ -198,7 +198,7 @@ private static void failNotEqual(@Nullable Object expected, @Nullable Object act`
`198`	`198`	`.message(messageOrSupplier) //`
`199`	`199`	`.expected(expected) //`
`200`	`200`	`.actual(actual) //`
`201`		`- .trimStacktrace(Assertions.class) //`
	`201`	`+ .trimStacktrace(Assertions.class, 1) //`
`202`	`202`	`.buildAndThrow();`
`203`	`203`	`}`
`204`	`204`	`}`
Original file line number	Diff line number	Diff line change
`@@ -66,7 +66,7 @@ private static void failNotFalse(@Nullable Object messageOrSupplier) {`
`66`	`66`	`.message(messageOrSupplier) //`
`67`	`67`	`.expected(false) //`
`68`	`68`	`.actual(true) //`
`69`		`- .trimStacktrace(Assertions.class) //`
	`69`	`+ .trimStacktrace(Assertions.class, 1) //`
`70`	`70`	`.buildAndThrow();`
`71`	`71`	`}`
`72`	`72`
Original file line number	Diff line number	Diff line change
`@@ -56,7 +56,7 @@ private static <T> T assertInstanceOf(Class<T> expectedType, @Nullable Object ac`
`56`	`56`	`.expected(expectedType) //`
`57`	`57`	`.actual(actualValue == null ? null : actualValue.getClass()) //`
`58`	`58`	`.cause(actualValue instanceof Throwable t ? t : null) //`
`59`		`- .trimStacktrace(Assertions.class) //`
	`59`	`+ .trimStacktrace(Assertions.class, 1) //`
`60`	`60`	`.buildAndThrow();`
`61`	`61`	`}`
`62`	`62`	`return expectedType.cast(actualValue);`
Original file line number	Diff line number	Diff line change
`@@ -193,7 +193,7 @@ void fail(String format, Object... args) {`
`193`	`193`	`.expected(join(newLine, expectedLines)) //`
`194`	`194`	`.actual(join(newLine, actualLines)) //`
`195`	`195`	`.includeValuesInMessage(false) //`
`196`		`- .trimStacktrace(Assertions.class) //`
	`196`	`+ .trimStacktrace(Assertions.class, 1) //`
`197`	`197`	`.buildAndThrow();`
`198`	`198`	`}`
`199`	`199`	`}`
Original file line number	Diff line number	Diff line change
`@@ -279,7 +279,7 @@ private static void failEqual(@Nullable Object actual, @Nullable Object messageO`
`279`	`279`	`assertionFailure() //`
`280`	`280`	`.message(messageOrSupplier) //`
`281`	`281`	`.reason("expected: not equal but was: <" + actual + ">") //`
`282`		`- .trimStacktrace(Assertions.class) //`
	`282`	`+ .trimStacktrace(Assertions.class, 1) //`
`283`	`283`	`.buildAndThrow();`
`284`	`284`	`}`
`285`	`285`
Original file line number	Diff line number	Diff line change
`@@ -52,7 +52,7 @@ private static void failNull(@Nullable Object messageOrSupplier) {`
`52`	`52`	`assertionFailure() //`
`53`	`53`	`.message(messageOrSupplier) //`
`54`	`54`	`.reason("expected: not <null>") //`
`55`		`- .trimStacktrace(Assertions.class) //`
	`55`	`+ .trimStacktrace(Assertions.class, 1) //`
`56`	`56`	`.buildAndThrow();`
`57`	`57`	`}`
`58`	`58`	`}`
Original file line number	Diff line number	Diff line change
`@@ -49,7 +49,7 @@ private static void failSame(@Nullable Object actual, @Nullable Object messageOr`
`49`	`49`	`assertionFailure() //`
`50`	`50`	`.message(messageOrSupplier) //`
`51`	`51`	`.reason("expected: not same but was: <" + actual + ">") //`
`52`		`- .trimStacktrace(Assertions.class) //`
	`52`	`+ .trimStacktrace(Assertions.class, 1) //`
`53`	`53`	`.buildAndThrow();`
`54`	`54`	`}`
`55`	`55`