Issue #3166: detailed docmentation provided for redirecting standard streams

Author: Oyster-zx

documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-reporting.adoc

@@ -164,6 +164,11 @@ $ java -jar junit-platform-console-standalone-{platform-version}.jar <OPTIONS> \
  --redirect-stderr=bar.txt
 ----
 
+If both the `--redirect-stdout` and `--redirect-stderr` parameters point to the same
+file, the output will be merged into that file.
+
+The default charset is used for writing to the files.
+
 [[junit-platform-reporting-legacy-xml]]
 ==== Legacy XML format
 

junit-platform-console/src/main/java/org/junit/platform/console/options/TestConsoleOutputOptions.java

@@ -75,22 +75,22 @@ public void setTheme(Theme theme) {
 this.theme = theme;
 }
 
-@API(status = INTERNAL, since = "5.12")
+@API(status = INTERNAL, since = "1.13")
 public Path getStdoutPath() {
 return this.stdoutPath;
 }
 
-@API(status = INTERNAL, since = "5.12")
+@API(status = INTERNAL, since = "1.13")
 public void setStdoutPath(Path stdoutPath) {
 this.stdoutPath = stdoutPath;
 }
 
-@API(status = INTERNAL, since = "5.12")
+@API(status = INTERNAL, since = "1.13")
 public Path getStderrPath() {
 return this.stderrPath;
 }
 
-@API(status = INTERNAL, since = "5.12")
+@API(status = INTERNAL, since = "1.13")
 public void setStderrPath(Path stderrPath) {
 this.stderrPath = stderrPath;
 }

junit-platform-console/src/main/java/org/junit/platform/console/tasks/StdStreamHandler.java

@@ -30,6 +30,14 @@ private boolean isSameFile(Path path1, Path path2) {
 return (path1.normalize().toAbsolutePath().equals(path2.normalize().toAbsolutePath()));
 }
 
+/**
+ * Redirects standard output (stdout) and standard error (stderr) to the specified file paths.
+ * If the paths are the same, both streams are redirected to the same file.
+ * The default charset is used for writing to the files.
+ *
+ * @param stdoutPath The file path for standard output. {@code null} means no redirection.
+ * @param stderrPath The file path for standard error. {@code null} means no redirection.
+ */
 public void redirectStdStreams(Path stdoutPath, Path stderrPath) {
 if (isSameFile(stdoutPath, stderrPath)) {
 try {
@@ -71,11 +79,15 @@ public void redirectStdStreams(Path stdoutPath, Path stderrPath) {
 
 @Override
 public void close() {
-if (stdout != null) {
-stdout.close();
+try {
+if (stdout != null) {
+stdout.close();
+}
 }
-if (stderr != null) {
-stderr.close();
+finally {
+if (stderr != null) {
+stderr.close();
+}
 }
 }
 }

platform-tests/src/test/java/org/junit/platform/console/ConsoleLauncherIntegrationTests.java

@@ -19,11 +19,15 @@
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.util.stream.Stream;
 
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
 import org.junit.jupiter.params.provider.ValueSource;
+import org.junit.platform.console.options.StdStreamTestCase;
 
 /**
  * @since 1.0
@@ -98,32 +102,37 @@ void executeScanModules(final String line) {
 assertEquals(0, new ConsoleLauncherWrapper().execute(args1).getTestsFoundCount());
 }
 
+private static Stream<Arguments> redirectStreamParams() {
+return Stream.of(
+Arguments.of("--redirect-stdout", StdStreamTestCase.getStdoutOutputFileSize()),
+Arguments.of("--redirect-stderr", StdStreamTestCase.getStderrOutputFileSize())
+);
+}
+
 @ParameterizedTest
-@ValueSource(strings = { "--redirect-stdout", "--redirect-stderr" })
-void executeWithRedirectedStdStream(String redirectedStream, @TempDir Path tempDir) throws IOException {
+@MethodSource("redirectStreamParams")
+void executeWithRedirectedStdStream(String redirectedStream, int outputFileSize, @TempDir Path tempDir)
+throws IOException {
 Path outputFile = tempDir.resolve("output.txt");
-var line = String.format(
-"execute -e junit-jupiter --select-method org.junit.platform.console.options.StdStreamTestCase#printTest "
-+ "%s %s",
-redirectedStream, outputFile);
+var line = String.format("execute -e junit-jupiter --select-class %s %s %s",
+StdStreamTestCase.class.getName(), redirectedStream, outputFile);
 var args = line.split(" ");
 new ConsoleLauncherWrapper().execute(args);
 
 assertTrue(Files.exists(outputFile), "File does not exist.");
-assertEquals(20, Files.size(outputFile), "Invalid file size.");
+assertEquals(outputFileSize, Files.size(outputFile), "Invalid file size.");
 }
 
 @Test
 void executeWithRedirectedStdStreamsToSameFile(@TempDir Path tempDir) throws IOException {
 Path outputFile = tempDir.resolve("output.txt");
 var line = String.format(
-"execute -e junit-jupiter --select-method org.junit.platform.console.options.StdStreamTestCase#printTest "
-+ "--redirect-stdout %s --redirect-stderr %s",
-outputFile, outputFile);
+"execute -e junit-jupiter --select-class %s --redirect-stdout %s --redirect-stderr %s",
+StdStreamTestCase.class.getName(), outputFile, outputFile);
 var args = line.split(" ");
 new ConsoleLauncherWrapper().execute(args);
 
 assertTrue(Files.exists(outputFile), "File does not exist.");
-assertEquals(40, Files.size(outputFile), "Invalid file size.");
+assertEquals(StdStreamTestCase.getStdoutOutputFileSize() + StdStreamTestCase.getStderrOutputFileSize(), Files.size(outputFile), "Invalid file size.");
 }
 }

platform-tests/src/test/java/org/junit/platform/console/options/StdStreamTestCase.java

@@ -14,9 +14,20 @@
 
 public class StdStreamTestCase {
 
+private static final String STDOUT_DATA = "Writing to STDOUT...";
+private static final String STDERR_DATA = "Writing to STDERR...";
+
+public static int getStdoutOutputFileSize() {
+return STDOUT_DATA.length();
+}
+
+public static int getStderrOutputFileSize() {
+return STDERR_DATA.length();
+}
+
 @Test
 void printTest() {
-System.out.print("Writing to STDOUT...");
-System.err.print("Writing to STDERR...");
+System.out.print(STDOUT_DATA);
+System.err.print(STDERR_DATA);
 }
 }