Merged marklogic-junit library into marklogic-unit-test

gradle.properties

@@ -1,2 +1,2 @@
 group=com.marklogic
-version=0.12.0
+version=0.13.develop

marklogic-junit/README.md

@@ -0,0 +1,46 @@
+## Easy JUnit 5 testing with MarkLogic
+
+Want to write JUnit 5 tests that verify the behavior of endpoints in [MarkLogic](https://www.marklogic.com/), 
+including applications using the [Data Hub Framework](https://marklogic.github.io/marklogic-data-hub/)? 
+This library makes that as simple as possible by providing the following support:
+
+1. Connect to MarkLogic with the [MarkLogic Java Client](https://developer.marklogic.com/products/java) by reusing
+configuration you've already defined in your project
+1. Clear your test database before a test run so it always runs in a known state
+1. Easily read and make assertions on JSON and XML documents, including support for XPath-based assertions
+1. Easily integrate [marklogic-unit-test](https://github.com/marklogic-community/marklogic-unit-test) tests into a JUnit test suite
+
+Below is a simple example of a JUnit test that writes a couple documents, runs a search on them, and then reads them 
+back and verifies the contents of each document:
+
+```
+public class SearchTest extends AbstractSpringMarkLogicTest {
+
+	@Test
+	public void twoDocuments() {
+		getDatabaseClient().newXMLDocumentManager().write("/test/1.xml", new StringHandle("<message>Hello world</message>"));
+		getDatabaseClient().newJSONDocumentManager().write("/test/2.json", new StringHandle("{\"message\":\"Hello world\"}"));
+
+		QueryManager queryManager = getDatabaseClient().newQueryManager();
+		SearchHandle searchHandle = queryManager.search(queryManager.newStringDefinition(), new SearchHandle());
+		assertEquals(2, searchHandle.getTotalResults());
+
+		XmlNode xml = readXmlDocument("/test/1.xml");
+		xml.assertElementValue("/message", "Hello world");
+
+		JsonNode json = readJsonDocument("/test/2.json");
+		assertEquals("Hello world", json.get("message").asText());
+	}
+}
+```
+
+## Getting started on an ml-gradle project
+
+If you'd like to use marklogic-junit on a regular ml-gradle project (not a DHF project), then 
+start with the ml-gradle example project to see a working example with instructions on how to get started. 
+
+## Getting started on a Data Hub Framework project
+
+If you're working on a Data Hub Framework (DHF) project and you're like to start writing JUnit tests to verify your application 
+features, then check out the DHF example project to see a working example with instructions on how to get started.
+

marklogic-junit/build.gradle

@@ -0,0 +1,79 @@
+plugins {
+	id "java"
+	id "maven-publish"
+	id "com.jfrog.bintray" version "1.8.0"
+	id "com.github.jk1.dependency-license-report" version "0.3.11"
+	id "net.saliman.properties" version "1.4.6"
+}
+
+sourceCompatibility = "1.8"
+targetCompatibility = "1.8"
+
+repositories {
+	jcenter()
+}
+
+dependencies {
+  compile project(":marklogic-unit-test-client")
+	compile "com.marklogic:ml-javaclient-util:3.11.0"
+	compile "jaxen:jaxen:1.1.6"
+	compile "org.junit.jupiter:junit-jupiter-api:5.4.1"
+	compile "org.junit.jupiter:junit-jupiter-params:5.4.1"
+	compile "org.springframework:spring-context:5.0.8.RELEASE"
+	compile "org.springframework:spring-test:5.0.8.RELEASE"
+
+	// Support for DHF is provided, but a client must specify their own version of the DHF library to use
+	compileOnly ("com.marklogic:marklogic-data-hub:4.2.2") {
+		exclude module: "ml-javaclient-util"
+	}
+
+	// Needed by Gradle 4.6+ - see https://www.petrikainulainen.net/programming/testing/junit-5-tutorial-running-unit-tests-with-gradle/
+	testRuntime "org.junit.jupiter:junit-jupiter-engine:5.4.1"
+
+	// Forcing Spring to use logback instead of commons-logging
+	testRuntime "ch.qos.logback:logback-classic:1.1.8"
+	testRuntime group: "org.slf4j", name: "jcl-over-slf4j", version: "1.7.22"
+	testRuntime group: "org.slf4j", name: "slf4j-api", version: "1.7.22"
+}
+
+// Needed by Gradle 4.6+ - see https://www.petrikainulainen.net/programming/testing/junit-5-tutorial-running-unit-tests-with-gradle/
+test {
+	useJUnitPlatform()
+}
+
+task sourcesJar(type: Jar, dependsOn: classes) {
+	classifier "sources"
+	from sourceSets.main.allJava
+}
+
+publishing {
+	publications {
+		mainJava(MavenPublication) {
+			from components.java
+      artifactId "marklogic-junit"
+		}
+		sourcesJava(MavenPublication) {
+			from components.java
+      artifactId "marklogic-junit"
+			artifact sourcesJar
+		}
+	}
+}
+
+if (project.hasProperty("myBintrayUser")) {
+	bintray {
+		user = myBintrayUser
+		key = myBintrayKey
+		publications = ["mainJava", "sourcesJava"]
+		pkg {
+			repo = "maven"
+			name = project.name
+			licenses = ["Apache-2.0"]
+			vcsUrl = "https://github.com/marklogic-community/" + project.name + ".git"
+			version {
+				name = project.version
+				released = new Date()
+			}
+		}
+	}
+}

marklogic-junit/examples/simple-dhf4/.gitignore

@@ -0,0 +1,8 @@
+.gradle
+out
+build
+*.iml
+gradle-local.properties
+src/main
+gradle.properties
+.tmp

marklogic-junit/examples/simple-dhf4/README.md

@@ -0,0 +1,33 @@
+This project shows an example of using both marklogic-junit and marklogic-unit-test within a 
+Data Hub Framework version 4 project. 
+
+To try this out locally, first initialize the DHF project:
+
+    ./gradlew hubInit
+
+Then add the following lines to gradle.properties:
+
+```
+mlModulePaths=src/main/ml-modules,src/test/ml-modules
+mlTestDbName=data-hub-TEST
+mlTestDbFilename=final-database.json
+mlTestServerFilename=final-server.json
+mlTestServerName=data-hub-TEST
+mlTestPort=8015
+mlTestUsername=someuser
+mlTestPassword=someuser's password
+```
+
+You can now deploy both the normal DHF application and the test resources defined in build.gradle via:
+
+    ./gradlew mlDeploy testDeploy
+
+There are two marklogic-unit-test test modules under ./src/main/ml-modules/root/test. You can run these 
+via Gradle:
+
+    ./gradlew test
+
+And Gradle should report "BUILD SUCCESSFUL" as none of the tests should fail.
+
+Or import this project into your favorite IDE and execute "RunDataHubUnitTestsTest". Each test module 
+will be executed as a separate JUnit test. 

marklogic-junit/examples/simple-dhf4/build.gradle

@@ -0,0 +1,118 @@
+plugins {
+	id 'net.saliman.properties' version '1.4.6'
+	id 'com.marklogic.ml-data-hub' version '4.2.2'
+  id 'java'
+}
+
+repositories {
+	jcenter()
+  mavenLocal()
+}
+
+dependencies {
+  mlRestApi "com.marklogic:marklogic-unit-test-modules:0.13.develop"
+
+	testCompile "com.marklogic:marklogic-junit:0.13.develop"
+  testCompile "com.marklogic:marklogic-data-hub:4.2.2"
+
+	// Needed by Gradle 4.6+
+	testRuntime "org.junit.jupiter:junit-jupiter-engine:5.3.0"
+}
+
+// Needed by Gradle 4.6+ - see https://www.petrikainulainen.net/programming/testing/junit-5-tutorial-running-unit-tests-with-gradle/
+test {
+  useJUnitPlatform()
+}
+
+
+/**
+ * Tasks for setting up a test database and a test app server that mirror either your final or staging database and
+ * app server, and then loading hub and user modules via the test app server so that REST options are accessible to it.
+ * Depends on the following properties being set:
+ *
+ * - mlTestDbFilename = the name of the file to use for constructing a database - either final-database.json or staging-database.json
+ * - mlTestDbName = the name for the test database
+ * - mlTestServerFilename = the name of the file to use for constructing an app server - either final-server.json or staging-server.json
+ * - mlTestServerName = the name of the test app server
+ * - mlTestPort = the port to assign to the test app server
+ */
+
+task hubDeployTestDatabase(type: com.marklogic.gradle.task.MarkLogicTask) {
+  doLast {
+    println "Deploying a test database with name ${mlTestDbName} based on configuration file named ${mlTestDbFilename}"
+    new DeployHubTestDatabaseCommand(hubConfig, mlTestDbFilename, mlTestDbName).execute(mlCommandContext)
+  }
+}
+
+task hubDeployTestServer(type: com.marklogic.gradle.task.MarkLogicTask) {
+  doLast {
+    println "Deploying a test server with name ${mlTestServerName} and port ${mlTestPort}, connected to content database ${mlTestDbName}, based on configuration file named ${mlTestServerFilename}"
+    new DeployHubTestServerCommand(mlTestServerFilename, mlTestServerName, Integer.parseInt(mlTestPort), mlTestDbName).execute(mlCommandContext);
+  }
+}
+
+task testDeploy {
+  description = "Deploy a test database and a test server"
+  dependsOn = ["hubDeployTestDatabase", "hubDeployTestServer"]
+}
+hubDeployTestServer.mustRunAfter hubDeployTestDatabase
+
+task hubUndeployTestResources(type: com.marklogic.gradle.task.MarkLogicTask) {
+  description = "Undeploys the test server and database that were created via testDeploy"
+  doLast {
+    mlAdminManager.invokeActionRequiringRestart({
+      new com.marklogic.mgmt.resource.appservers.ServerManager(mlManageClient).deleteByIdField(mlTestServerName)
+      return true
+    })
+    new com.marklogic.mgmt.resource.databases.DatabaseManager(mlManageClient).deleteByName(mlTestDbName)
+  }
+}
+mlUndeploy.dependsOn hubUndeployTestResources
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import com.fasterxml.jackson.databind.node.ObjectNode
+import com.fasterxml.jackson.databind.node.TextNode
+import com.marklogic.hub.HubConfig
+
+import java.util.regex.Pattern
+
+class DeployHubTestDatabaseCommand extends com.marklogic.hub.deploy.commands.DeployHubDatabaseCommand {
+  String testDatabaseName
+
+  DeployHubTestDatabaseCommand(HubConfig config, String databaseFilename, String testDatabaseName) {
+    super(config, null, databaseFilename)
+    this.testDatabaseName = testDatabaseName
+  }
+
+  @Override
+  protected String copyFileToString(File f) {
+    String payload = super.copyFileToString(f)
+    ObjectNode node = new ObjectMapper().readTree(payload)
+    node.set("database-name", new TextNode(testDatabaseName))
+    return node.toString()
+  }
+}
+
+class DeployHubTestServerCommand extends com.marklogic.hub.deploy.commands.DeployHubOtherServersCommand {
+  String serverName
+  int port
+  String contentDatabaseName
+
+  DeployHubTestServerCommand(String serverFilenamePattern, String serverName, int port, String contentDatabaseName) {
+    super()
+    setResourceFilenamesIncludePattern(Pattern.compile(serverFilenamePattern))
+    this.serverName = serverName
+    this.port = port
+    this.contentDatabaseName = contentDatabaseName
+  }
+
+  @Override
+  protected String copyFileToString(File f) {
+    String payload = super.copyFileToString(f)
+    ObjectNode node = new ObjectMapper().readTree(payload)
+    node.set("server-name", new TextNode(serverName))
+    node.set("port", new TextNode(port + ""))
+    node.set("content-database", new TextNode(contentDatabaseName))
+    return node.toString()
+  }
+}

marklogic-junit/examples/simple-dhf4/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-4.10-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists