Skip to content

Introduce @Contract annotation #4741

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Introduce @Contract annotation #4741

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1efe0d2
Introduce `@Contract` annotation
marcphilipp Jul 9, 2025
b99e301
Add `@Contract` annotations and simplify code
marcphilipp Jul 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions gradle/plugins/common/src/main/kotlin/junitbuild.java-nullability-conventions.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,8 @@ tasks.withType<JavaCompile>().configureEach {
enable()
}
isJSpecifyMode = true
customContractAnnotations.add("org.junit.platform.commons.annotation.Contract")
checkContracts = true
}
}
}
Expand Down
4 changes: 4 additions & 0 deletions junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertFalse.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
import java.util.function.Supplier;

import org.jspecify.annotations.Nullable;
import org.junit.platform.commons.annotation.Contract;

/**
* {@code AssertFalse} is a collection of utility methods that support asserting
Expand All @@ -29,16 +30,19 @@ private AssertFalse() {
/* no-op */
}

@Contract("true -> fail")
static void assertFalse(boolean condition) {
assertFalse(condition, (String) null);
}

@Contract("true, _ -> fail")
static void assertFalse(boolean condition, @Nullable String message) {
if (condition) {
failNotFalse(message);
}
}

@Contract("true, _ -> fail")
static void assertFalse(boolean condition, Supplier<@Nullable String> messageSupplier) {
if (condition) {
failNotFalse(messageSupplier);
Expand Down
4 changes: 4 additions & 0 deletions junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertInstanceOf.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
import java.util.function.Supplier;

import org.jspecify.annotations.Nullable;
import org.junit.platform.commons.annotation.Contract;

/**
* {@code AssertInstanceOf} is a collection of utility methods that support
Expand All @@ -29,14 +30,17 @@ private AssertInstanceOf() {
/* no-op */
}

@Contract("_, null -> fail")
static <T> T assertInstanceOf(Class<T> expectedType, @Nullable Object actualValue) {
return assertInstanceOf(expectedType, actualValue, (Object) null);
}

@Contract("_, null, _ -> fail")
static <T> T assertInstanceOf(Class<T> expectedType, @Nullable Object actualValue, @Nullable String message) {
return assertInstanceOf(expectedType, actualValue, (Object) message);
}

@Contract("_, null, _ -> fail")
static <T> T assertInstanceOf(Class<T> expectedType, @Nullable Object actualValue,
Supplier<@Nullable String> messageSupplier) {
return assertInstanceOf(expectedType, actualValue, (Object) messageSupplier);
Expand Down
4 changes: 4 additions & 0 deletions junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertNotNull.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
import java.util.function.Supplier;

import org.jspecify.annotations.Nullable;
import org.junit.platform.commons.annotation.Contract;

/**
* {@code AssertNotNull} is a collection of utility methods that support asserting
Expand All @@ -28,16 +29,19 @@ private AssertNotNull() {
/* no-op */
}

@Contract("null -> fail")
static void assertNotNull(@Nullable Object actual) {
assertNotNull(actual, (String) null);
}

@Contract("null, _ -> fail")
static void assertNotNull(@Nullable Object actual, @Nullable String message) {
if (actual == null) {
failNull(message);
}
}

@Contract("null, _ -> fail")
static void assertNotNull(@Nullable Object actual, Supplier<@Nullable String> messageSupplier) {
if (actual == null) {
failNull(messageSupplier);
Expand Down
4 changes: 4 additions & 0 deletions junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertNull.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
import java.util.function.Supplier;

import org.jspecify.annotations.Nullable;
import org.junit.platform.commons.annotation.Contract;

/**
* {@code AssertNull} is a collection of utility methods that support asserting
Expand All @@ -28,16 +29,19 @@ private AssertNull() {
/* no-op */
}

@Contract("!null -> fail")
static void assertNull(@Nullable Object actual) {
assertNull(actual, (String) null);
}

@Contract("!null, _ -> fail")
static void assertNull(@Nullable Object actual, @Nullable String message) {
if (actual != null) {
failNotNull(actual, message);
}
}

@Contract("!null, _ -> fail")
static void assertNull(@Nullable Object actual, Supplier<@Nullable String> messageSupplier) {
if (actual != null) {
failNotNull(actual, messageSupplier);
Expand Down
4 changes: 4 additions & 0 deletions junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertTrue.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
import java.util.function.Supplier;

import org.jspecify.annotations.Nullable;
import org.junit.platform.commons.annotation.Contract;

/**
* {@code AssertTrue} is a collection of utility methods that support asserting
Expand All @@ -29,16 +30,19 @@ private AssertTrue() {
/* no-op */
}

@Contract("false -> fail")
static void assertTrue(boolean condition) {
assertTrue(condition, (String) null);
}

@Contract("false, _ -> fail")
static void assertTrue(boolean condition, @Nullable String message) {
if (!condition) {
failNotTrue(message);
}
}

@Contract("false, _ -> fail")
static void assertTrue(boolean condition, Supplier<@Nullable String> messageSupplier) {
if (!condition) {
failNotTrue(messageSupplier);
Expand Down
6 changes: 6 additions & 0 deletions junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertionUtils.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
import java.util.function.Supplier;

import org.jspecify.annotations.Nullable;
import org.junit.platform.commons.annotation.Contract;
import org.junit.platform.commons.util.UnrecoverableExceptions;
import org.opentest4j.AssertionFailedError;

Expand All @@ -31,22 +32,27 @@ private AssertionUtils() {
/* no-op */
}

@Contract(" -> fail")
static void fail() {
throw new AssertionFailedError();
}

@Contract("_ -> fail")
static void fail(@Nullable String message) {
throw new AssertionFailedError(message);
}

@Contract("_, _ -> fail")
static void fail(@Nullable String message, @Nullable Throwable cause) {
throw new AssertionFailedError(message, cause);
}

@Contract("_ -> fail")
static void fail(@Nullable Throwable cause) {
throw new AssertionFailedError(null, cause);
}

@Contract("_ -> fail")
static void fail(Supplier<@Nullable String> messageSupplier) {
throw new AssertionFailedError(nullSafeGet(messageSupplier));
}
Expand Down
21 changes: 21 additions & 0 deletions junit-jupiter-api/src/main/java/org/junit/jupiter/api/Assertions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
import org.jspecify.annotations.Nullable;
import org.junit.jupiter.api.function.Executable;
import org.junit.jupiter.api.function.ThrowingSupplier;
import org.junit.platform.commons.annotation.Contract;
import org.opentest4j.MultipleFailuresError;

/**
Expand Down Expand Up @@ -116,6 +117,7 @@ protected Assertions() {
* <p>See Javadoc for {@link #fail(String)} for an explanation of this method's
* generic return type {@code V}.
*/
@Contract(" -> fail")
@SuppressWarnings({ "NullAway", "TypeParameterUnusedInFormals" })
public static <V> V fail() {
AssertionUtils.fail();
Expand All @@ -136,6 +138,7 @@ public static <V> V fail() {
* Stream.of().map(entry -> fail("should not be called"));
* }</pre>
*/
@Contract("_ -> fail")
@SuppressWarnings({ "NullAway", "TypeParameterUnusedInFormals" })
public static <V> V fail(@Nullable String message) {
AssertionUtils.fail(message);
Expand All @@ -149,6 +152,7 @@ public static <V> V fail(@Nullable String message) {
* <p>See Javadoc for {@link #fail(String)} for an explanation of this method's
* generic return type {@code V}.
*/
@Contract("_, _ -> fail")
@SuppressWarnings({ "NullAway", "TypeParameterUnusedInFormals" })
public static <V> V fail(@Nullable String message, @Nullable Throwable cause) {
AssertionUtils.fail(message, cause);
Expand All @@ -161,6 +165,7 @@ public static <V> V fail(@Nullable String message, @Nullable Throwable cause) {
* <p>See Javadoc for {@link #fail(String)} for an explanation of this method's
* generic return type {@code V}.
*/
@Contract("_ -> fail")
@SuppressWarnings({ "NullAway", "TypeParameterUnusedInFormals" })
public static <V> V fail(@Nullable Throwable cause) {
AssertionUtils.fail(cause);
Expand All @@ -174,6 +179,7 @@ public static <V> V fail(@Nullable Throwable cause) {
* <p>See Javadoc for {@link #fail(String)} for an explanation of this method's
* generic return type {@code V}.
*/
@Contract("_ -> fail")
@SuppressWarnings({ "NullAway", "TypeParameterUnusedInFormals" })
public static <V> V fail(Supplier<@Nullable String> messageSupplier) {
AssertionUtils.fail(messageSupplier);
Expand All @@ -185,6 +191,7 @@ public static <V> V fail(Supplier<@Nullable String> messageSupplier) {
/**
* <em>Assert</em> that the supplied {@code condition} is {@code true}.
*/
@Contract("false -> fail")
public static void assertTrue(boolean condition) {
AssertTrue.assertTrue(condition);
}
Expand All @@ -193,6 +200,7 @@ public static void assertTrue(boolean condition) {
* <em>Assert</em> that the supplied {@code condition} is {@code true}.
* <p>If necessary, the failure message will be retrieved lazily from the supplied {@code messageSupplier}.
*/
@Contract("false, _ -> fail")
public static void assertTrue(boolean condition, Supplier<@Nullable String> messageSupplier) {
AssertTrue.assertTrue(condition, messageSupplier);
}
Expand All @@ -216,6 +224,7 @@ public static void assertTrue(BooleanSupplier booleanSupplier, @Nullable String
* <em>Assert</em> that the supplied {@code condition} is {@code true}.
* <p>Fails with the supplied failure {@code message}.
*/
@Contract("false, _ -> fail")
public static void assertTrue(boolean condition, @Nullable String message) {
AssertTrue.assertTrue(condition, message);
}
Expand All @@ -233,6 +242,7 @@ public static void assertTrue(BooleanSupplier booleanSupplier, Supplier<@Nullabl
/**
* <em>Assert</em> that the supplied {@code condition} is {@code false}.
*/
@Contract("true -> fail")
public static void assertFalse(boolean condition) {
AssertFalse.assertFalse(condition);
}
Expand All @@ -241,6 +251,7 @@ public static void assertFalse(boolean condition) {
* <em>Assert</em> that the supplied {@code condition} is {@code false}.
* <p>Fails with the supplied failure {@code message}.
*/
@Contract("true, _ -> fail")
public static void assertFalse(boolean condition, @Nullable String message) {
AssertFalse.assertFalse(condition, message);
}
Expand All @@ -249,6 +260,7 @@ public static void assertFalse(boolean condition, @Nullable String message) {
* <em>Assert</em> that the supplied {@code condition} is {@code false}.
* <p>If necessary, the failure message will be retrieved lazily from the supplied {@code messageSupplier}.
*/
@Contract("true, _ -> fail")
public static void assertFalse(boolean condition, Supplier<@Nullable String> messageSupplier) {
AssertFalse.assertFalse(condition, messageSupplier);
}
Expand Down Expand Up @@ -281,6 +293,7 @@ public static void assertFalse(BooleanSupplier booleanSupplier, Supplier<@Nullab
/**
* <em>Assert</em> that {@code actual} is {@code null}.
*/
@Contract("!null -> fail")
public static void assertNull(@Nullable Object actual) {
AssertNull.assertNull(actual);
}
Expand All @@ -289,6 +302,7 @@ public static void assertNull(@Nullable Object actual) {
* <em>Assert</em> that {@code actual} is {@code null}.
* <p>Fails with the supplied failure {@code message}.
*/
@Contract("!null, _ -> fail")
public static void assertNull(@Nullable Object actual, @Nullable String message) {
AssertNull.assertNull(actual, message);
}
Expand All @@ -297,6 +311,7 @@ public static void assertNull(@Nullable Object actual, @Nullable String message)
* <em>Assert</em> that {@code actual} is {@code null}.
* <p>If necessary, the failure message will be retrieved lazily from the supplied {@code messageSupplier}.
*/
@Contract("!null, _ -> fail")
public static void assertNull(@Nullable Object actual, Supplier<@Nullable String> messageSupplier) {
AssertNull.assertNull(actual, messageSupplier);
}
Expand All @@ -306,6 +321,7 @@ public static void assertNull(@Nullable Object actual, Supplier<@Nullable String
/**
* <em>Assert</em> that {@code actual} is not {@code null}.
*/
@Contract("null -> fail")
public static void assertNotNull(@Nullable Object actual) {
AssertNotNull.assertNotNull(actual);
}
Expand All @@ -314,6 +330,7 @@ public static void assertNotNull(@Nullable Object actual) {
* <em>Assert</em> that {@code actual} is not {@code null}.
* <p>Fails with the supplied failure {@code message}.
*/
@Contract("null, _ -> fail")
public static void assertNotNull(@Nullable Object actual, @Nullable String message) {
AssertNotNull.assertNotNull(actual, message);
}
Expand All @@ -322,6 +339,7 @@ public static void assertNotNull(@Nullable Object actual, @Nullable String messa
* <em>Assert</em> that {@code actual} is not {@code null}.
* <p>If necessary, the failure message will be retrieved lazily from the supplied {@code messageSupplier}.
*/
@Contract("null, _ -> fail")
public static void assertNotNull(@Nullable Object actual, Supplier<@Nullable String> messageSupplier) {
AssertNotNull.assertNotNull(actual, messageSupplier);
}
Expand Down Expand Up @@ -3696,6 +3714,7 @@ public static void assertTimeoutPreemptively(Duration timeout, Executable execut
* @since 5.8
*/
@API(status = STABLE, since = "5.10")
@Contract("_, null -> fail")
public static <T> T assertInstanceOf(Class<T> expectedType, @Nullable Object actualValue) {
return AssertInstanceOf.assertInstanceOf(expectedType, actualValue);
}
Expand All @@ -3712,6 +3731,7 @@ public static <T> T assertInstanceOf(Class<T> expectedType, @Nullable Object act
* @since 5.8
*/
@API(status = STABLE, since = "5.10")
@Contract("_, null, _ -> fail")
public static <T> T assertInstanceOf(Class<T> expectedType, @Nullable Object actualValue,
@Nullable String message) {
return AssertInstanceOf.assertInstanceOf(expectedType, actualValue, message);
Expand All @@ -3729,6 +3749,7 @@ public static <T> T assertInstanceOf(Class<T> expectedType, @Nullable Object act
*
* @since 5.8
*/
@Contract("_, null, _ -> fail")
@API(status = STABLE, since = "5.10")
public static <T> T assertInstanceOf(Class<T> expectedType, @Nullable Object actualValue,
Supplier<@Nullable String> messageSupplier) {
Expand Down
Loading
Loading