Centralize exit code declaration

Co-authored-by: Marc Philipp <[email protected]>

Author: sormuras

documentation/src/docs/asciidoc/user-guide/running-tests.adoc

@@ -748,10 +748,12 @@ include::{consoleLauncherDiscoverOptionsFile}[]
 ===== Executing tests
 
 .Exit Code
-NOTE: The `{ConsoleLauncher}` exits with a status code of `1` if any containers or tests
-failed. If no tests are discovered and the `--fail-if-no-tests` command-line option is
-supplied, the `ConsoleLauncher` exits with a status code of `2`. Otherwise, the exit code
-is `0`.
+NOTE: On successful runs, the `{ConsoleLauncher}` exits with a status code of `0`.
+All non-zero codes indicate an error of some sort. For example, status code `1`
+is returned if any containers or tests failed. If no tests are discovered and the
+`--fail-if-no-tests` command-line option is supplied, the `ConsoleLauncher` exits
+with a status code of `2`. Unexpected or invalid user input yields a status code
+of `3`. An exit code of `-1` indicates an unspecified error condition.
 
 ----
 include::{consoleLauncherExecuteOptionsFile}[]

junit-platform-console/src/main/java/org/junit/platform/console/command/BaseCommand.java

@@ -59,14 +59,14 @@ static CommandLine initialize(CommandLine commandLine) {
 		return commandLine //
 				.setParameterExceptionHandler((ex, args) -> {
 					defaultParameterExceptionHandler.handleParseException(ex, args);
-					return CommandResult.FAILURE;
+					return ExitCode.ANY_ERROR;
 				}) //
 				.setExecutionExceptionHandler((ex, cmd, __) -> {
 					commandLine.getErr().println(cmd.getColorScheme().richStackTraceString(ex));
 					commandLine.getErr().println();
 					commandLine.getErr().flush();
 					cmd.usage(commandLine.getOut());
-					return CommandResult.FAILURE;
+					return ExitCode.ANY_ERROR;
 				}) //
 				.setCaseInsensitiveEnumValuesAllowed(true) //
 				.setAtFileCommentChar(null);

junit-platform-console/src/main/java/org/junit/platform/console/command/CommandResult.java

@@ -22,23 +22,8 @@
  */
 @API(status = INTERNAL, since = "1.10")
 public class CommandResult<T> {
-
-	/**
-	 * Exit code indicating successful execution.
-	 */
-	public static final int SUCCESS = 0;
-
-	/**
-	 * Exit code indicating any failure(s).
-	 */
-	protected static final int FAILURE = -1;
-
 	public static <T> CommandResult<T> success() {
-		return create(SUCCESS, null);
-	}
-
-	public static <T> CommandResult<T> failure() {
-		return create(FAILURE, null);
+		return create(ExitCode.SUCCESS, null);
 	}
 
 	public static <T> CommandResult<T> create(int exitCode, @Nullable T value) {

junit-platform-console/src/main/java/org/junit/platform/console/command/ExecuteTestsCommand.java

@@ -10,7 +10,9 @@
 
 package org.junit.platform.console.command;
 
-import static org.junit.platform.console.command.CommandResult.SUCCESS;
+import static org.junit.platform.console.command.ExitCode.NO_TESTS_FOUND;
+import static org.junit.platform.console.command.ExitCode.SUCCESS;
+import static org.junit.platform.console.command.ExitCode.TEST_FAILED;
 
 import java.io.PrintWriter;
 import java.nio.file.Path;
@@ -34,17 +36,6 @@
 		description = "Execute tests" //
 )
 class ExecuteTestsCommand extends BaseCommand<TestExecutionSummary> implements CommandLine.IExitCodeGenerator {
-
-	/**
-	 * Exit code indicating test failure(s)
-	 */
-	private static final int TEST_FAILED = 1;
-
-	/**
-	 * Exit code indicating no tests found
-	 */
-	private static final int NO_TESTS_FOUND = 2;
-
 	private final ConsoleTestExecutor.Factory consoleTestExecutorFactory;
 
 	@Mixin

junit-platform-console/src/main/java/org/junit/platform/console/command/ExitCode.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2015-2025 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * https://www.eclipse.org/legal/epl-v20.html
+ */
+
+package org.junit.platform.console.command;
+
+/**
+ * Well-known exit codes of the {@code junit} tool.
+ *
+ * @since 6.0.1
+ */
+final class ExitCode {
+	/**
+	 * Exit code indicating a successful tool run.
+	 */
+	public static final int SUCCESS = 0;
+
+	/**
+	 * Exit code indicating an unsuccessful run.
+	 */
+	public static final int ANY_ERROR = -1;
+
+	/**
+	 * Exit code indicating test failure(s).
+	 */
+	public static final int TEST_FAILED = 1;
+
+	/**
+	 * Exit code indicating no tests found.
+	 */
+	public static final int NO_TESTS_FOUND = 2;
+
+	/**
+	 * Exit code indicating invalid user input.
+	 */
+	public static final int INVALID_INPUT = 3;
+
+	private ExitCode() {
+	}
+}

junit-platform-console/src/main/java/org/junit/platform/console/command/MainCommand.java

@@ -39,8 +39,8 @@
 		footer = "For more information, please refer to the JUnit User Guide at%n" //
 				+ "@|underline https://docs.junit.org/${junit.docs.version}/user-guide/|@", //
 		scope = CommandLine.ScopeType.INHERIT, //
-		exitCodeOnInvalidInput = CommandResult.FAILURE, //
-		exitCodeOnExecutionException = CommandResult.FAILURE, //
+		exitCodeOnInvalidInput = ExitCode.INVALID_INPUT, //
+		exitCodeOnExecutionException = ExitCode.ANY_ERROR, //
 		versionProvider = ManifestVersionProvider.class //
 )
 class MainCommand implements Runnable, IExitCodeGenerator {