diff --git a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc b/documentation/src/docs/asciidoc/user-guide/running-tests.adoc index 5d5e9ce0c826..c1d6684f4cda 100644 --- a/documentation/src/docs/asciidoc/user-guide/running-tests.adoc +++ b/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}[] diff --git a/junit-platform-console/src/main/java/org/junit/platform/console/command/BaseCommand.java b/junit-platform-console/src/main/java/org/junit/platform/console/command/BaseCommand.java index 30a53d6e6169..99c9872107cf 100644 --- a/junit-platform-console/src/main/java/org/junit/platform/console/command/BaseCommand.java +++ b/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); diff --git a/junit-platform-console/src/main/java/org/junit/platform/console/command/CommandResult.java b/junit-platform-console/src/main/java/org/junit/platform/console/command/CommandResult.java index 93285654aca3..3d104c59258e 100644 --- a/junit-platform-console/src/main/java/org/junit/platform/console/command/CommandResult.java +++ b/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 { - - /** - * 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 CommandResult success() { - return create(SUCCESS, null); - } - - public static CommandResult failure() { - return create(FAILURE, null); + return create(ExitCode.SUCCESS, null); } public static CommandResult create(int exitCode, @Nullable T value) { diff --git a/junit-platform-console/src/main/java/org/junit/platform/console/command/ExecuteTestsCommand.java b/junit-platform-console/src/main/java/org/junit/platform/console/command/ExecuteTestsCommand.java index 130d6c65b011..e7c8bf37a16a 100644 --- a/junit-platform-console/src/main/java/org/junit/platform/console/command/ExecuteTestsCommand.java +++ b/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 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 diff --git a/junit-platform-console/src/main/java/org/junit/platform/console/command/ExitCode.java b/junit-platform-console/src/main/java/org/junit/platform/console/command/ExitCode.java new file mode 100644 index 000000000000..6e3a60a80c1f --- /dev/null +++ b/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() { + } +} diff --git a/junit-platform-console/src/main/java/org/junit/platform/console/command/MainCommand.java b/junit-platform-console/src/main/java/org/junit/platform/console/command/MainCommand.java index 3d49ffb18175..224afd8887fe 100644 --- a/junit-platform-console/src/main/java/org/junit/platform/console/command/MainCommand.java +++ b/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 {