Support JSON as source for parametrized tests arguments

.infra/checkstyle/import-control.xml

@@ -4,5 +4,15 @@
 <import-control pkg="org.junitpioneer">
 
 	<allow pkg=".*" regex="true" />
+	<disallow pkg="com.fasterxml.jackson.*" regex="true"/>
+
+	<subpackage name="jupiter.json">
+		<file name="JacksonNode.java">
+			<allow pkg="com.fasterxml.jackson.*" regex="true" />
+		</file>
+		<file name="JacksonJsonConverter.java">
+			<allow pkg="com.fasterxml.jackson.*" regex="true" />
+		</file>
+	</subpackage>
 
 </import-control>

README.md

@@ -116,6 +116,10 @@ Thank you for your efforts! 🙏
 
 The least we can do is to thank them and list some of their accomplishments here (in lexicographic order).
 
+#### 2022
+
+* [Filip Hrisafov](https://github.com/filiphr) contributed the [JSON Argument Source](https://junit-pioneer.org/docs/json-argument-source/) support (#101 / #492)
+
 #### 2021
 
 * [Cory Thomas](https://github.com/dump247) contributed the `minSuccess` attribute in [retrying tests](https://junit-pioneer.org/docs/retrying-test/) (#408 / #430)

build.gradle.kts

@@ -43,6 +43,9 @@ java {
 	}
 	withJavadocJar()
 	withSourcesJar()
+	registerFeature("jackson") {
+		usingSourceSet(sourceSets["main"])
+	}
 }
 
 repositories {
@@ -58,6 +61,7 @@ dependencies {
 	implementation(group = "org.junit.jupiter", name = "junit-jupiter-params")
 	implementation(group = "org.junit.platform", name = "junit-platform-commons")
 	implementation(group = "org.junit.platform", name = "junit-platform-launcher")
+	"jacksonImplementation"(group = "com.fasterxml.jackson.core", name = "jackson-databind", version = "2.13.2")
 
 	testImplementation(group = "org.junit.jupiter", name = "junit-jupiter-engine")
 	testImplementation(group = "org.junit.platform", name = "junit-platform-testkit")
@@ -252,9 +256,15 @@ tasks {
 				useJUnitJupiter()
 			}
 			val demoTests by registering(JvmTestSuite::class) {
-				dependencies { implementation(project) }
+				dependencies {
+					implementation(project)
+					implementation("com.fasterxml.jackson.core:jackson-databind:2.13.2")
+				}
 
-				sources { java { srcDir("src/demo/java") } }
+				sources {
+					java { srcDir("src/demo/java") }
+					resources { srcDir("src/demo/resources") }
+				}
 				targets { all { testTask.configure {
 					shouldRunAfter(test)
 					filter {

docs/docs-nav.yml

@@ -18,6 +18,8 @@
         url: /docs/disable-parameterized-tests/
       - title: "Issue information"
         url: /docs/issue/
+      - title: "JSON Argument Source"
+        url: /docs/json-argument-source
       - title: "Publishing Report Entries"
         url: /docs/report-entries/
       - title: "Range Sources"

docs/json-argument-source.adoc

@@ -0,0 +1,150 @@
+:page-title: JSON Argument Source
+:page-description: Extends JUnit Jupiter with `@JsonFileSource`, a parametrized test that creates test based on a JSON Source
+:xp-demo-dir: ../src/demo/java
+:json-demo: {xp-demo-dir}/org/junitpioneer/jupiter/json/JsonArgumentSourceExtensionDemo.java
+:jedi: {xp-demo-dir}/org/junitpioneer/jupiter/json/Jedi.java
+
+The JSON argument sources let you provide arguments for parameterized tests from JSON.
+There are three annotations:
+
+* `@JsonSource` for lenient inline JSON
+* `@JsonFileSource` for JSON files from the local file system
+* `@JsonClasspathSource` for JSON files from the classpath
+
+There are various ways how the method arguments for a single parametrized test are provided.
+By default the root of the source will be treated as candidate for the test arguments.
+If the root is an object then the entire object will be one argument, if the root is an array then every element of the array will be one argument.
+
+It is also possible to use a nested array from the provided JSON to access the source for the test arguments.
+The `JsonFileSource#data` can be used to tell the extraction mechanism to use the element with that name to look for the source of the data.
+
+Depending on the test method parameters, the extraction of the values might differ.
+
+== Method Arguments
+
+=== Single Argument Methods
+
+If the method has a single argument, the JSON object argument will be converted to that type.
+
+.Argument type
+[source,java]
+----
+include::{jedi}[tag=class]
+----
+
+.JSON Source File
+[source,json]
+----
+[
+  {
+    "name": "Luke",
+    "height": 172
+  },
+  {
+    "name": "Yoda",
+    "height": 66
+  }
+]
+----
+
+[source,java]
+----
+include::{json-demo}[tag=classpath_source,indent=0]
+----
+
+[source,java]
+----
+include::{json-demo}[tag=inline_source,indent=0]
+----
+
+This parametrized test will generate the following test executions:
+
+* [1] Jedi {name='Luke', height=172}
+* [2] Jedi {name='Yoda', height=66}
+
+It is also possible to extract only a single element from each argument object by using the `@Property` annotation.
+
+[source,java]
+----
+include::{json-demo}/[tag=classpath_source_with_property,indent=0]
+----
+
+[source,java]
+----
+include::{json-demo}[tag=inline_source_with_property,indent=0]
+----
+
+This parametrized test will generate the following tests:
+
+* [1] Luke
+* [2] Yoda
+
+=== Multiple Argument Methods
+
+If the method has multiple arguments, each JSON object argument will be deconstructed to each of the method arguments.
+By default, the method argument name will be used for locating the element that needs to be taken from the JSON object.
+You can also use `@Property` to give the name of the element that needs to be extracted.
+
+[IMPORTANT]
+====
+If your test sources are not compiled using the `--parameters` flag then the names of the arguments will not be like they are written in the source code.
+In that the situation you need to use `@Property` instead.
+====
+
+Using the same `jedis.json` and the following test
+
+[source,java]
+----
+include::{json-demo}[tag=classpath_source_deconstruct_from_array,indent=0]
+----
+
+[source,java]
+----
+include::{json-demo}[tag=inline_source_deconstruct_from_array,indent=0]
+----
+
+This parametrized test will generate the following tests:
+
+* [1] Luke, 172
+* [2] Yoda, 66
+
+== Extracting nested array
+
+Sometimes we want to extract a nested array instead of the root element.
+For this purpose `JsonClasspathSource#data` can be used.
+
+.Jedi with nested array
+[source,json]
+----
+{
+  "name": "Luke",
+  "height": 172,
+  "vehicles": [
+    {
+      "name": "Snowspeeder",
+      "length": 4.5
+    },
+    {
+      "name": "Imperial Speeder Bike",
+      "length": 3
+    }
+  ]
+}
+----
+
+Here we want to test the vehicles.
+The test for this will look like:
+
+[source,java]
+----
+include::{json-demo}[tag=classpath_source_nested_data,indent=0]
+----
+
+This parametrized test will generate the following tests:
+
+* [1] Snowspeeder, 4.5
+* [2] Imperial Speeder Bike, 3
+
+== Thread-Safety
+
+This extension is safe to use during https://junit.org/junit5/docs/current/user-guide/#writing-tests-parallel-execution[parallel test execution].

src/demo/java/org/junitpioneer/jupiter/json/Jedi.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2016-2021 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
+ *
+ * http://www.eclipse.org/legal/epl-v20.html
+ */
+
+package org.junitpioneer.jupiter.json;
+
+// tag::class[]
+public class Jedi {
+
+	public String name;
+	public String height;
+
+	@Override
+	public String toString() {
+		return "Jedi {" + "name='" + name + '\'' + ", height=" + height + '}';
+	}
+
+}
+// end::class[]

src/demo/java/org/junitpioneer/jupiter/json/JsonArgumentSourceExtensionDemo.java

@@ -0,0 +1,99 @@
+/*
+ * Copyright 2016-2021 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
+ *
+ * http://www.eclipse.org/legal/epl-v20.html
+ */
+
+package org.junitpioneer.jupiter.json;
+
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.params.ParameterizedTest;
+
+class JsonArgumentSourceExtensionDemo {
+
+	@Nested
+	class ClasspathDemo {
+
+		// tag::classpath_source[]
+		@ParameterizedTest
+		@JsonClasspathSource("jedis.json")
+		void singleJedi(Jedi jedi) {
+			// YOUR TEST CODE HERE
+		}
+		// end::classpath_source[]
+
+		// tag::classpath_source_with_property[]
+		@ParameterizedTest
+		@JsonClasspathSource("jedis.json")
+		void singleJediProperty(@Property("name") String jediName) {
+			// YOUR TEST CODE HERE
+		}
+		// end::classpath_source_with_property[]
+
+		// tag::classpath_source_deconstruct_from_array[]
+		@ParameterizedTest
+		@JsonClasspathSource("jedis.json")
+		void deconstructFromArray(@Property("name") String name, @Property("height") int height) {
+			// YOUR TEST CODE HERE
+		}
+		// end::classpath_source_deconstruct_from_array[]
+
+		// tag::classpath_source_nested_data[]
+		@ParameterizedTest
+		@JsonClasspathSource(value = "luke.json", data = "vehicles")
+		void lukeVehicles(@Property("name") String name, @Property("length") double length) {
+			// YOUR TEST CODE HERE
+		}
+		// end::classpath_source_nested_data[]
+
+	}
+
+	@Nested
+	class InlineDemo {
+
+		// @formatter:off
+		// tag::inline_source[]
+		@ParameterizedTest
+		@JsonSource("["
+				+ "  { name: 'Luke', height: 172  },"
+				+ "  { name: 'Yoda', height: 66 }"
+				+ "]")
+		void singleJedi(Jedi jedi) {
+			// YOUR TEST CODE HERE
+		}
+		// end::inline_source[]
+		// @formatter:on
+
+		// @formatter:off
+		// tag::inline_source_with_property[]
+		@ParameterizedTest
+		@JsonSource({
+				"{ name: 'Luke', height: 172  }",
+				"{ name: 'Yoda', height: 66 }"
+		})
+		void singleJediProperty(@Property("name") String jediName) {
+			// YOUR TEST CODE HERE
+		}
+		// end::inline_source_with_property[]
+		// @formatter:on
+
+		// @formatter:off
+		// tag::inline_source_deconstruct_from_array[]
+		@ParameterizedTest
+		@JsonSource({
+				"{ name: 'Yoda', height: 66 }",
+				"{ name: 'Luke', height: 172 }",
+		})
+		void deconstructFromArray(@Property("name") String name, @Property("height") int height) {
+			// YOUR TEST CODE HERE
+		}
+		// @formatter:on
+		// end::inline_source_deconstruct_from_array[]
+
+	}
+
+}

src/demo/java/org/junitpioneer/jupiter/json/package-info.java

@@ -0,0 +1,5 @@
+/**
+ * Package containing demonstration tests for corresponding package in the main project.
+ */
+
+package org.junitpioneer.jupiter.json;

src/demo/resources/jedis.json

@@ -0,0 +1,10 @@
+[
+  {
+    "name": "Luke",
+    "height": 172
+  },
+  {
+    "name": "Yoda",
+    "height": 66
+  }
+]

src/demo/resources/luke.json

@@ -0,0 +1,14 @@
+{
+  "name": "Luke",
+  "height": 172,
+  "vehicles": [
+    {
+      "name": "Snowspeeder",
+      "length": 4.5
+    },
+    {
+      "name": "Imperial Speeder Bike",
+      "length": 3
+    }
+  ]
+}