Add @SpringConversion converter

docs/converters/spring-conversion.md

@@ -0,0 +1,30 @@
+---
+description: An argument converter using Spring Framework conversion service
+hide:
+  - toc
+---
+
+# `@SpringConversion`
+
+`@SpringConversion` is an annotation that converts arguments using the Spring Framework
+[`ConversionService`](https://docs.spring.io/spring-framework/reference/core/validation/convert.html).
+
+The converter uses Spring's
+[`DefaultConversionService`](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/convert/support/DefaultConversionService.html),
+which provides a wide range of built-in converters for common types including:
+
+* Primitives and their wrappers
+* Collections (List, Set, Map, etc.)
+* Arrays
+* Enums
+* Common value types (UUID, Currency, Locale, etc.)
+* And many more standard conversions
+
+The following examples demonstrate some of the supported conversions.
+
+| Source Type     | Target Declaration                       | Example                                                   |
+|-----------------|------------------------------------------|-----------------------------------------------------------|
+| `#!java String` | `#!java @SpringConversion List<Integer>` | `#!java "123, 456"` → `#!java List.of(123, 456)`          |
+| `#!java List`   | `#!java @SpringConversion List<Integer>` | `#!java List.of("123", "456")` → `#!java List.of(123, 456)` |
+
+For a complete list of supported conversions, refer to the [Spring Framework documentation](https://docs.spring.io/spring-framework/reference/core/validation/convert.html).

mkdocs.yml

@@ -89,5 +89,6 @@ nav:
     - converters/base64.md
     - converters/bytes.md
     - converters/hex.md
+    - converters/spring-conversion.md
   - javadoc.md
   - release-notes.md

pom.xml

@@ -37,6 +37,7 @@
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <!-- Dependency versions -->
     <junit-framework.version>5.13.4</junit-framework.version>
+    <spring-framework.version>5.3.39</spring-framework.version>
   </properties>
 
   <dependencyManagement>
@@ -57,6 +58,20 @@
       <artifactId>jspecify</artifactId>
       <version>1.0.0</version>
     </dependency>
+    <!-- Optional -->
+    <dependency>
+      <groupId>org.springframework</groupId>
+      <artifactId>spring-core</artifactId>
+      <version>${spring-framework.version}</version>
+      <optional>true</optional>
+    </dependency>
+    <!-- FIXME move to DefaultFormattingConversionService for @NumberFormat, @DurationFormat, and @DateTimeFormat? -->
+    <dependency>
+      <groupId>org.springframework</groupId>
+      <artifactId>spring-context</artifactId>
+      <version>${spring-framework.version}</version>
+      <optional>true</optional>
+    </dependency>
     <!-- Provided -->
     <dependency>
       <groupId>org.junit.jupiter</groupId>
@@ -228,6 +243,31 @@
           </execution>
         </executions>
       </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-enforcer-plugin</artifactId>
+        <version>3.6.2</version>
+        <configuration>
+          <rules>
+            <bannedDependencies>
+              <includes>
+                <include>org.jspecify:jspecify</include>
+              </includes>
+              <excludes>
+                <exclude>*:*:*:jar:compile</exclude>
+              </excludes>
+            </bannedDependencies>
+            <dependencyConvergence />
+          </rules>
+        </configuration>
+        <executions>
+          <execution>
+            <goals>
+              <goal>enforce</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
       <plugin>
         <groupId>org.codehaus.mojo</groupId>
         <artifactId>flatten-maven-plugin</artifactId>

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

@@ -0,0 +1,46 @@
+/*
+ * Copyright © 2025 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.springframework.core.MethodParameter;
+import org.springframework.core.convert.ConversionService;
+import org.springframework.core.convert.TypeDescriptor;
+import org.springframework.core.convert.support.DefaultConversionService;
+
+class SpringArgumentConverter implements ArgumentConverter {
+
+	private final ConversionService conversionService = new DefaultConversionService();
+
+	@Override
+	public @Nullable Object convert(Object source, ParameterContext context) throws ArgumentConversionException {
+		TypeDescriptor sourceType = TypeDescriptor.forObject(source);
+		TypeDescriptor targetType = new TypeDescriptor(MethodParameter.forParameter(context.getParameter()));
+		return conversionService.convert(source, sourceType, targetType);
+	}
+
+	@Override
+	public @Nullable Object convert(Object source, FieldContext context) throws ArgumentConversionException {
+		TypeDescriptor sourceType = TypeDescriptor.forObject(source);
+		TypeDescriptor targetType = new TypeDescriptor(context.getField());
+		return conversionService.convert(source, sourceType, targetType);
+	}
+
+}

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

@@ -0,0 +1,40 @@
+/*
+ * Copyright © 2025 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;
+
+/**
+ * {@link ConvertWith} composed annotation that converts arguments using the Spring
+ * {@link org.springframework.core.convert.ConversionService conversion service}.
+ *
+ * @see org.springframework.core.convert.ConversionService
+ * @see org.springframework.core.convert.support.DefaultConversionService
+ */
+@Target({ ElementType.ANNOTATION_TYPE, ElementType.PARAMETER, ElementType.FIELD })
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@ConvertWith(SpringArgumentConverter.class)
+@SuppressWarnings("exports")
+public @interface SpringConversion {
+
+}

src/main/java/module-info.java

@@ -21,11 +21,15 @@
  * @see org.junit.jupiter.params.ParameterizedClass
  * @see org.junit.jupiter.params.ParameterizedTest
  */
+@SuppressWarnings("requires-automatic")
 module io.github.scordio.junit.converters {
 
 	requires static transitive org.jspecify;
 
+	requires static spring.core;
+
 	requires org.junit.jupiter.params;
+	requires spring.context;
 
 	exports io.github.scordio.junit.converters;
 

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

@@ -0,0 +1,55 @@
+/*
+ * Copyright © 2025 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.SpringConversion;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+
+import java.util.List;
+import java.util.stream.Stream;
+
+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 SpringConversionIntegrationTests {
+
+	@Test
+	void should_convert_supported_values() {
+		executeTestsForClass(SupportedValuesTestCase.class).testEvents()
+			.assertStatistics(stats -> stats.started(2).succeeded(2));
+	}
+
+	static class SupportedValuesTestCase {
+
+		@ParameterizedTest
+		@MethodSource("springArguments")
+		void test(@SpringConversion List<Integer> strings, List<Integer> expected) {
+			assertThat(strings).isEqualTo(expected);
+		}
+
+		static Stream<Arguments> springArguments() {
+			return Stream.of( //
+					arguments("123, 456", List.of(123, 456)), //
+					arguments(List.of("123", "456"), List.of(123, 456)));
+		}
+
+	}
+
+}

src/test/java/module-info.java

@@ -13,11 +13,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
+@SuppressWarnings("requires-automatic")
 open module io.github.scordio.tests.junit.converters {
 
 	requires io.github.scordio.junit.converters;
 	requires org.assertj.core;
 	requires org.junit.jupiter.params;
 	requires org.junit.platform.testkit;
+    requires spring.core;
 
 }