Add mandatory media type for publishing files

Author: marcphilipp

documentation/src/test/java/example/TestReporterDemo.java

@@ -19,6 +19,7 @@
 
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.TestReporter;
+import org.junit.jupiter.api.extension.MediaType;
 import org.junit.jupiter.api.io.TempDir;
 import org.junit.jupiter.api.parallel.Execution;
 import org.junit.jupiter.api.parallel.ExecutionMode;
@@ -49,15 +50,21 @@ void reportMultipleKeyValuePairs(TestReporter testReporter) {
 	@Test
 	void reportFiles(TestReporter testReporter, @TempDir Path tempDir) throws Exception {
 
-		testReporter.publishFile("test1.txt", file -> Files.write(file, singletonList("Test 1")));
+		testReporter.publishFile("test1.txt", MediaType.TEXT_PLAIN_UTF_8,
+			file -> Files.write(file, singletonList("Test 1")));
 
 		Path existingFile = Files.write(tempDir.resolve("test2.txt"), singletonList("Test 2"));
-		testReporter.publishFile(existingFile);
+		testReporter.publishFile(existingFile, MediaType.TEXT_PLAIN_UTF_8);
 
-		testReporter.publishFile("test3", dir -> {
-			Path nestedFile = Files.createDirectory(dir).resolve("nested.txt");
-			Files.write(nestedFile, singletonList("Nested content"));
+		testReporter.publishDirectory("test3", dir -> {
+			Files.write(dir.resolve("nested1.txt"), singletonList("Nested content 1"));
+			Files.write(dir.resolve("nested2.txt"), singletonList("Nested content 2"));
 		});
+
+		Path existingDir = Files.createDirectory(tempDir.resolve("test4"));
+		Files.write(existingDir.resolve("nested1.txt"), singletonList("Nested content 1"));
+		Files.write(existingDir.resolve("nested2.txt"), singletonList("Nested content 2"));
+		testReporter.publishDirectory(existingDir);
 	}
 }
 // end::user_guide[]

junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestReporter.java

@@ -14,13 +14,18 @@
 import static org.apiguardian.api.API.Status.EXPERIMENTAL;
 import static org.apiguardian.api.API.Status.STABLE;
 
+import java.io.IOException;
+import java.io.UncheckedIOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.Collections;
 import java.util.Map;
+import java.util.stream.Stream;
 
 import org.apiguardian.api.API;
+import org.junit.jupiter.api.extension.MediaType;
 import org.junit.jupiter.api.function.ThrowingConsumer;
+import org.junit.platform.commons.util.Preconditions;
 
 /**
  * Parameters of type {@code TestReporter} can be injected into
@@ -88,29 +93,88 @@ default void publishEntry(String value) {
 	 * The file will be copied to the report output directory replacing any
 	 * potentially existing file with the same name.
 	 *
-	 * @param file the file to be attached; never {@code null} or blank
+	 * @param file      the file to be attached; never {@code null} or blank
+	 * @param mediaType the media type of the file; never {@code null}; use
+	 *                  {@link MediaType#APPLICATION_OCTET_STREAM} if unknown
 	 * @since 5.12
 	 */
 	@API(status = EXPERIMENTAL, since = "5.12")
-	default void publishFile(Path file) {
-		publishFile(file.getFileName().toString(), path -> Files.copy(file, path, REPLACE_EXISTING));
+	default void publishFile(Path file, MediaType mediaType) {
+		Preconditions.condition(Files.exists(file), () -> "file must exist: " + file);
+		Preconditions.condition(Files.isRegularFile(file), () -> "file must be a regular file: " + file);
+		publishFile(file.getFileName().toString(), mediaType, path -> Files.copy(file, path, REPLACE_EXISTING));
 	}
 
 	/**
-	 * Publish a file with the supplied name written by the supplied action and
-	 * attach it to the current test or container.
+	 * Publish the supplied directory and attach it to the current test or
+	 * container.
+	 * <p>
+	 * The entire directory will be copied to the report output directory
+	 * replacing any potentially existing files with the same name.
+	 *
+	 * @param directory the file to be attached; never {@code null} or blank
+	 * @since 5.12
+	 */
+	@API(status = EXPERIMENTAL, since = "5.12")
+	default void publishDirectory(Path directory) {
+		Preconditions.condition(Files.exists(directory), () -> "directory must exist: " + directory);
+		Preconditions.condition(Files.isDirectory(directory), () -> "directory must be a directory: " + directory);
+		publishDirectory(directory.getFileName().toString(), path -> {
+			try (Stream<Path> stream = Files.walk(directory)) {
+				stream.forEach(source -> {
+					Path destination = path.resolve(directory.relativize(source));
+					try {
+						if (Files.isDirectory(source)) {
+							Files.createDirectories(destination);
+						}
+						else {
+							Files.copy(source, destination, REPLACE_EXISTING);
+						}
+					}
+					catch (IOException e) {
+						throw new UncheckedIOException("Failed to copy files to the output directory", e);
+					}
+				});
+			}
+		});
+	}
+
+	/**
+	 * Publish a file or directory with the supplied name and media type written
+	 * by the supplied action and attach it to the current test or container.
+	 * <p>
+	 * The {@link Path} passed to the supplied action will be relative to the
+	 * report output directory, but it's up to the action to write the file.
+	 *
+	 * @param name      the name of the file to be attached; never {@code null}
+	 *                  or blank and must not contain any path separators
+	 * @param mediaType the media type of the file; never {@code null}; use
+	 *                  {@link MediaType#APPLICATION_OCTET_STREAM} if unknown
+	 * @param action    the action to be executed to write the file; never
+	 *                  {@code null}
+	 * @since 5.12
+	 */
+	@API(status = EXPERIMENTAL, since = "5.12")
+	default void publishFile(String name, MediaType mediaType, ThrowingConsumer<Path> action) {
+		throw new UnsupportedOperationException();
+	}
+
+	/**
+	 * Publish a directory with the supplied name written by the supplied action
+	 * and attach it to the current test or container.
 	 * <p>
 	 * The {@link Path} passed to the supplied action will be relative to the
-	 * report output directory, but it's up to the action to write the file or
-	 * directory.
+	 * report output directory and point to an existing directory, but it's up
+	 * to the action to write files to it.
 	 *
-	 * @param fileName the name of the file to be attached; never {@code null} or blank
-	 *                 and must not contain any path separators
-	 * @param action   the action to be executed to write the file; never {@code null}
+	 * @param name the name of the directory to be attached; never {@code null}
+	 *                 or blank and must not contain any path separators
+	 * @param action   the action to be executed to write the file; never
+	 *                 {@code null}
 	 * @since 5.12
 	 */
 	@API(status = EXPERIMENTAL, since = "5.12")
-	default void publishFile(String fileName, ThrowingConsumer<Path> action) {
+	default void publishDirectory(String name, ThrowingConsumer<Path> action) {
 		throw new UnsupportedOperationException();
 	}
 

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ExtensionContext.java

@@ -374,14 +374,32 @@ default void publishReportEntry(String value) {
 	 * The file will be resolved in the report output directory prior to
 	 * invoking the supplied action.
 	 *
-	 * @param fileName the name of the file to be attached; never {@code null} or blank
-	 *                 and must not contain any path separators
-	 * @param action   the action to be executed to write the file; never {@code null}
+	 * @param name      the name of the file to be attached; never {@code null}
+	 *                  or blank and must not contain any path separators
+	 * @param mediaType the media type of the file; never {@code null}; use
+	 *                  {@link MediaType#APPLICATION_OCTET_STREAM} if unknown
+	 * @param action    the action to be executed to write the file; never {@code null}
 	 * @since 5.12
 	 * @see org.junit.platform.engine.EngineExecutionListener#fileEntryPublished
 	 */
 	@API(status = EXPERIMENTAL, since = "5.12")
-	void publishFile(String fileName, ThrowingConsumer<Path> action);
+	void publishFile(String name, MediaType mediaType, ThrowingConsumer<Path> action);
+
+	/**
+	 * Publish a directory with the supplied name written by the supplied action
+	 * and attach it to the current test or container.
+	 * <p>
+	 * The directory will be resolved and created in the report output directory
+	 * prior to invoking the supplied action.
+	 *
+	 * @param name   the name of the directory to be attached; never {@code null}
+	 *               or blank and must not contain any path separators
+	 * @param action the action to be executed to write the file; never {@code null}
+	 * @since 5.12
+	 * @see org.junit.platform.engine.EngineExecutionListener#fileEntryPublished
+	 */
+	@API(status = EXPERIMENTAL, since = "5.12")
+	void publishDirectory(String name, ThrowingConsumer<Path> action);
 
 	/**
 	 * Get the {@link Store} for the supplied {@link Namespace}.

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/MediaType.java

@@ -0,0 +1,155 @@
+/*
+ * Copyright 2015-2024 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.jupiter.api.extension;
+
+import static java.nio.charset.StandardCharsets.UTF_8;
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
+
+import java.nio.charset.Charset;
+import java.nio.file.Path;
+import java.util.Objects;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import org.apiguardian.api.API;
+import org.junit.jupiter.api.TestReporter;
+import org.junit.jupiter.api.function.ThrowingConsumer;
+import org.junit.platform.commons.PreconditionViolationException;
+import org.junit.platform.commons.util.Preconditions;
+
+/**
+ * Represents a media type as defined by
+ * <a href="https://tools.ietf.org/html/rfc2045">RFC 2045</a>.
+ *
+ * @since 5.12
+ * @see TestReporter#publishFile(Path, MediaType)
+ * @see TestReporter#publishFile(String, MediaType, ThrowingConsumer)
+ * @see ExtensionContext#publishFile(String, MediaType, ThrowingConsumer)
+ */
+@API(status = EXPERIMENTAL, since = "5.12")
+public class MediaType {
+
+	private static final Pattern PATTERN;
+	static {
+		// https://datatracker.ietf.org/doc/html/rfc2045#section-5.1
+		String whitespace = "[ \t]*";
+		String token = "[0-9A-Za-z!#$%&'*+.^_`|~-]+";
+		String quotedString = "\"(?:[^\"\\\\]|\\.)*\"";
+		String parameter = ";" + whitespace + token + "=" + "(?:" + token + "|" + quotedString + ")";
+		PATTERN = Pattern.compile(token + "/" + token + "(?:" + whitespace + parameter + ")*");
+	}
+
+	/**
+	 * The {@code text/plain} media type.
+	 */
+	public static final MediaType TEXT_PLAIN = create("text", "plain");
+
+	/**
+	 * The {@code text/plain; charset=UTF-8} media type.
+	 */
+	public static final MediaType TEXT_PLAIN_UTF_8 = create("text", "plain", UTF_8);
+
+	/**
+	 * The {@code application/json} media type.
+	 */
+	public static final MediaType APPLICATION_JSON = create("application", "json");
+
+	/**
+	 * The {@code application/json; charset=UTF-8} media type.
+	 */
+	public static final MediaType APPLICATION_JSON_UTF_8 = create("application", "json", UTF_8);
+
+	/**
+	 * The {@code application/octet-stream} media type.
+	 */
+	public static final MediaType APPLICATION_OCTET_STREAM = create("application", "octet-stream");
+
+	/**
+	 * The {@code image/jpeg} media type.
+	 */
+	public static final MediaType IMAGE_JPEG = create("image", "jpeg");
+
+	/**
+	 * The {@code image/png} media type.
+	 */
+	public static final MediaType IMAGE_PNG = create("image", "png");
+
+	private final String value;
+
+	/**
+	 * Parse the given media type value.
+	 * <p>
+	 * Must be valid according to
+	 * <a href="https://tools.ietf.org/html/rfc2045">RFC 2045</a>.
+	 *
+	 * @param value the media type value to parse; never {@code null}
+	 * @return the parsed media type
+	 * @throws PreconditionViolationException if the value is not a valid media type
+	 */
+	public static MediaType parse(String value) {
+		return new MediaType(value);
+	}
+
+	/**
+	 * Create a media type with the given type and subtype.
+	 *
+	 * @param type the type; never {@code null}
+	 * @param subtype the subtype; never {@code null}
+	 * @return the media type
+	 */
+	public static MediaType create(String type, String subtype) {
+		Preconditions.notNull(type, "type must not be null");
+		Preconditions.notNull(subtype, "subtype must not be null");
+		return new MediaType(type + "/" + subtype);
+	}
+
+	/**
+	 * Create a media type with the given type, subtype, and charset.
+	 *
+	 * @param type the type; never {@code null}
+	 * @param subtype the subtype; never {@code null}
+	 * @param charset the charset; never {@code null}
+	 * @return the media type
+	 */
+	public static MediaType create(String type, String subtype, Charset charset) {
+		Preconditions.notNull(type, "type must not be null");
+		Preconditions.notNull(subtype, "subtype must not be null");
+		Preconditions.notNull(charset, "charset must not be null");
+		return new MediaType(type + "/" + subtype + "; charset=" + charset.name());
+	}
+
+	private MediaType(String value) {
+		Matcher matcher = PATTERN.matcher(Preconditions.notNull(value, "value must not be null"));
+		Preconditions.condition(matcher.matches(), () -> "Invalid media type: '" + value + "'");
+		this.value = value;
+	}
+
+	/**
+	 * {@return string representation of this media type}
+	 */
+	@Override
+	public String toString() {
+		return value;
+	}
+
+	@Override
+	public boolean equals(Object o) {
+		if (o == null || getClass() != o.getClass())
+			return false;
+		MediaType that = (MediaType) o;
+		return Objects.equals(this.value, that.value);
+	}
+
+	@Override
+	public int hashCode() {
+		return Objects.hashCode(value);
+	}
+}