Support JSON sources for parametrized tests (#101 / #492)

This extension needs a JSON parser. In order not do pull in a
specific run-time dependency, it makes use of Gradle's feature
variants as described in CONTRIBUTING.md (including Checkstyle
rules). For now, only Jackson is supported as JSON parser. Other
parsers can be added in future versions if users need them.

Closes: #101
PR: #492

.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
+    }
+  ]
+}