Add @Elements converter

Author: scordio

src/main/java/io/github/scordio/junit/converters/Elements.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright © 2025-present Stefano Cordio
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.scordio.junit.converters;
+
+import org.junit.jupiter.params.converter.ConvertWith;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * {@code @Elements} is a {@link ConvertWith} composed annotation that converts
+ * collection-like string representations to JDK collection types.
+ * <p>
+ * The following target types are supported:
+ *
+ * <ul>
+ * <li>One-dimensional {@code int}, {@code long}, and {@code double} arrays</li>
+ * <li>One-dimensional primitive and object arrays &mdash; for example {@code Integer[]},
+ * {@code String[]}, etc.</li>
+ * <li>{@link java.util.Collection}</li>
+ * <li>{@link java.util.List}</li>
+ * <li>{@link java.util.Set}</li>
+ * </ul>
+ *
+ * <p>
+ * The elements should be separated by a comma, and each element is converted using
+ * JUnit's {@link org.junit.platform.commons.support.conversion.ConversionSupport
+ * conversion capabilities}.
+ *
+ * @see org.junit.platform.commons.support.conversion.ConversionSupport
+ */
+@Target({ ElementType.ANNOTATION_TYPE, ElementType.PARAMETER, ElementType.FIELD })
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@ConvertWith(ElementsArgumentConverter.class)
+@SuppressWarnings("exports")
+public @interface Elements {
+
+}

src/main/java/io/github/scordio/junit/converters/ElementsArgumentConverter.java

@@ -0,0 +1,98 @@
+/*
+ * Copyright © 2025-present Stefano Cordio
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.scordio.junit.converters;
+
+import org.jspecify.annotations.Nullable;
+import org.junit.jupiter.api.extension.ParameterContext;
+import org.junit.jupiter.params.converter.ArgumentConversionException;
+import org.junit.jupiter.params.converter.ArgumentConverter;
+import org.junit.jupiter.params.support.FieldContext;
+import org.junit.platform.commons.support.conversion.ConversionSupport;
+
+import java.lang.reflect.Array;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.List;
+import java.util.Objects;
+import java.util.Set;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+class ElementsArgumentConverter implements ArgumentConverter {
+
+	@Override
+	public final Object convert(@Nullable Object source, ParameterContext context) throws ArgumentConversionException {
+		return doConvert(source, context.getParameter().getParameterizedType());
+	}
+
+	@Override
+	public final Object convert(@Nullable Object source, FieldContext context) throws ArgumentConversionException {
+		return doConvert(source, context.getField().getGenericType());
+	}
+
+	private Object doConvert(@Nullable Object source, Type targetType) throws ArgumentConversionException {
+		Objects.requireNonNull(source, "'null' is not supported");
+
+		if (!(source instanceof String)) {
+			throw new ArgumentConversionException(
+					String.format("Source type %s is not supported", source.getClass().getTypeName()));
+		}
+
+		String[] elements = ((String) source).split(",");
+
+		Stream<String> stream = Arrays.stream(elements).map(String::trim);
+
+		if (targetType instanceof Class) {
+			Class<?> clazz = (Class<?>) targetType;
+			if (clazz.isArray()) {
+				return convertArray(stream, clazz.getComponentType());
+			}
+		}
+		if (targetType instanceof ParameterizedType) {
+			return convertCollection(stream, (ParameterizedType) targetType);
+		}
+
+		throw new ArgumentConversionException(
+				String.format("Target type %s is not supported", targetType.getTypeName()));
+	}
+
+	private static Object convertArray(Stream<String> stream, Class<?> componentType) {
+		List<String> strings = stream.collect(Collectors.toList());
+		Object array = Array.newInstance(componentType, strings.size());
+		for (int i = 0; i < strings.size(); i++) {
+			Array.set(array, i, ConversionSupport.convert(strings.get(i), componentType, null));
+		}
+		return array;
+	}
+
+	private static Collection<?> convertCollection(Stream<String> stream, ParameterizedType parameterizedType) {
+		Type rawType = parameterizedType.getRawType();
+		Class<?> elementType = (Class<?>) parameterizedType.getActualTypeArguments()[0];
+		Stream<?> convertedStream = stream.map(value -> ConversionSupport.convert(value, elementType, null));
+
+		if (rawType == List.class || rawType == Collection.class || rawType == Iterable.class) {
+			return convertedStream.collect(Collectors.toList());
+		}
+		if (rawType == Set.class) {
+			return convertedStream.collect(Collectors.toSet());
+		}
+		throw new IllegalArgumentException(
+				String.format("Target type %s is not supported", parameterizedType.getTypeName()));
+	}
+
+}

src/main/java/module-info.java

@@ -29,6 +29,7 @@
 	requires static spring.core;
 
 	requires org.junit.jupiter.params;
+	requires org.junit.platform.commons;
 
 	exports io.github.scordio.junit.converters;
 

src/test/java/io/github/scordio/tests/junit/converters/ElementsIntegrationTests.java

@@ -0,0 +1,165 @@
+/*
+ * Copyright © 2025-present Stefano Cordio
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.scordio.tests.junit.converters;
+
+import io.github.scordio.junit.converters.Elements;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.FieldSource;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Set;
+
+import static io.github.scordio.tests.junit.converters.JupiterEngineTestKit.executeTestsForClass;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.params.provider.Arguments.arguments;
+
+class ElementsIntegrationTests {
+
+	@Test
+	void should_convert_supported_values() {
+		executeTestsForClass(SupportedValuesTestCase.class).testEvents()
+			.assertStatistics(stats -> stats.started(16).succeeded(16));
+	}
+
+	static class SupportedValuesTestCase {
+
+		@ParameterizedTest
+		@FieldSource
+		void array_of_primitive_booleans(@Elements boolean[] elements, boolean[] expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> array_of_primitive_booleans = List.of(arguments("true, false", new boolean[] { true, false }));
+
+		@ParameterizedTest
+		@FieldSource
+		void array_of_primitive_chars(@Elements char[] elements, char[] expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> array_of_primitive_chars = List.of(arguments("a, b, c", new char[] { 'a', 'b', 'c' }));
+
+		@ParameterizedTest
+		@FieldSource
+		void array_of_primitive_bytes(@Elements byte[] elements, byte[] expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> array_of_primitive_bytes = List.of(arguments("1, 2, 3", new byte[] { 1, 2, 3 }));
+
+		@ParameterizedTest
+		@FieldSource
+		void array_of_primitive_shorts(@Elements short[] elements, short[] expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> array_of_primitive_shorts = List.of(arguments("1, 2, 3", new short[] { 1, 2, 3 }));
+
+		@ParameterizedTest
+		@FieldSource
+		void array_of_primitive_integers(@Elements int[] elements, int[] expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> array_of_primitive_integers = List.of(arguments("1, 2, 3", new int[] { 1, 2, 3 }));
+
+		@ParameterizedTest
+		@FieldSource
+		void array_of_primitive_longs(@Elements long[] elements, long[] expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> array_of_primitive_longs = List.of(arguments("1, 2, 3", new long[] { 1L, 2L, 3L }));
+
+		@ParameterizedTest
+		@FieldSource
+		void array_of_primitive_floats(@Elements float[] elements, float[] expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> array_of_primitive_floats = List.of(arguments("1, 2, 3", new float[] { 1.0f, 2.0f, 3.0f }));
+
+		@ParameterizedTest
+		@FieldSource
+		void array_of_primitive_doubles(@Elements double[] elements, double[] expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> array_of_primitive_doubles = List.of(arguments("1, 2, 3", new double[] { 1.0, 2.0, 3.0 }));
+
+		@ParameterizedTest
+		@FieldSource
+		void array_of_integers(@Elements Integer[] elements, Integer[] expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> array_of_integers = List.of(arguments("1, 2, 3", new Integer[] { 1, 2, 3 }));
+
+		@ParameterizedTest
+		@FieldSource
+		void array_of_strings(@Elements String[] elements, String[] expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> array_of_strings = List.of(arguments("a, b, c", new String[] { "a", "b", "c" }));
+
+		@ParameterizedTest
+		@FieldSource
+		void iterable_of_integers(@Elements Iterable<Integer> elements, Iterable<Integer> expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> iterable_of_integers = List.of(arguments("1, 2, 3", List.of(1, 2, 3)));
+
+		@ParameterizedTest
+		@FieldSource
+		void collection_of_integers(@Elements Collection<Integer> elements, Collection<Integer> expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> collection_of_integers = List.of(arguments("1, 2, 3", List.of(1, 2, 3)));
+
+		@ParameterizedTest
+		@FieldSource
+		void list_of_integers(@Elements List<Integer> elements, List<Integer> expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> list_of_integers = List.of(arguments("1, 2, 3", List.of(1, 2, 3)));
+
+		@ParameterizedTest
+		@FieldSource
+		void set_of_integers(@Elements Set<Integer> elements, Set<Integer> expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> set_of_integers = List.of(arguments("1, 2, 3", Set.of(1, 2, 3)));
+
+		@ParameterizedTest
+		@FieldSource
+		void list_of_strings(@Elements List<String> elements, List<String> expected) {
+			assertThat(elements).isEqualTo(expected);
+		}
+
+		static List<?> list_of_strings = List.of( //
+				arguments("a, b, c", List.of("a", "b", "c")), //
+				arguments(" a, b ,c ", List.of("a", "b", "c")));
+
+	}
+
+}