Improving the project landing page

README.md

@@ -3,24 +3,102 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 # Testing MarkLogic
 
-marklogic-unit-test is an [ml-gradle bundle](https://github.com/marklogic-community/ml-gradle/wiki/Bundles) that allows
-a project to test MarkLogic code.  With one import a project immediately has access to:
+marklogic-unit-test is a testing framework that allows a project to test MarkLogic code.  With one import a project
+immediately has access to:
 
 1. A framework for writing and running MarkLogic unit tests, including several built in assertion functions
 1. A UI for viewing and running unit tests entirely within MarkLogic
 1. A REST endpoint to run and report unit tests with other tools
 
-Testing MarkLogic from a Java project is made easy with marklogic-junit:
+Testing MarkLogic from a Java project is made easy with marklogic-junit5:
 
 1. Write MarkLogic tests entirely from Java
-1. Easily integrate MarkLogic unit tests into your favorite Java testing frameworks
+1. Easily integrate MarkLogic unit tests into your JUnit 5 project
 
 # Start using marklogic-unit-test
 
-If you'd like to use marklogic-unit-test check out this 
-[ml-gradle example project](https://github.com/marklogic-community/ml-gradle/tree/dev/examples/unit-test-project). 
-You can use that project's build.gradle file as an example of how to use marklogic-unit-test in your own project.
+MarkLogic unit test can easily be integrated into your project as an [ml-bundle](https://github.com/marklogic-community/ml-gradle/wiki/Bundles).
+  The following steps will configure a project to import and use marklogic-unit-tests.
+
+If you'd like to skip straight to the end, you can check out a [working example project](https://github.com/marklogic-community/ml-gradle/tree/dev/examples/unit-test-project). 
+You can use that project's `build.gradle` file as an example of how to use marklogic-unit-test in your own project.
+
+### Add marklogic-unit-test to `build.gradle`
+
+```groovy
+buildscript {
+  repositories {
+    jcenter()
+    mavenLocal()
+  }
+  dependencies {
+    classpath "com.marklogic:marklogic-unit-test-client:1.0.beta"
+    classpath "com.marklogic:ml-gradle:3.14.0"
+  }
+}
+
+apply plugin: "com.marklogic.ml-gradle"
+
+repositories {
+  jcenter()
+}
+
+dependencies {
+  mlBundle "com.marklogic:marklogic-unit-test-modules:1.0.beta"
+}
+```
+
+### Add Test Properties to `gradle.properties`
+
+```properties
+// Settings for any ml-gradle project
+mlHost=localhost    // Assuming local development
+mlAppName=my-app    // Application name, defaults to my-app
+mlRestPort=8003     // Application Port, defaults to 8003
+mlUsername=         // Username used to manage MarkLogic
+mlPassword=         // Password used to manage MarkLogic
+
+
+// Settings specific to marklogic-unit-test
+mlTestRestPort=8004 // Testing port, view and run tests from this port
+
+// ml-gradle supports deploying to multiple environments (https://github.com/marklogic-community/ml-gradle/wiki/Configuring-ml-gradle#environment-based-properties).\
+// Add the following line to gradle-{env}.properties files for which you would like to deploy the tests. Typically
+// tests are only deployed to environments that execute automated tests, like local development and CI environments. 
+mlModulePaths=src/main/ml-modules,src/test/ml-modules
+```
+
+### Deploy tests using ml-gradle
+
+Now that the environment is configured to load tests and setup a test application servier its time to deploy everything.
+```sh
+./gradlew mlDeploy
+```
+
+To enable quicker feedback between code updates and automated test runs, use the mlWatch task to automatically deploy
+changes to MarkLogic
+```sh
+./gradlew mlWatch
+```
+
+### Access marklogic-unit-test UI
+
+Open a web browser to http://localhost:8004/test/.  This is where tests are selected, run, and results are displayed.
+
+If this is a project that's new to marklogic-unit-tests no test suites are displayed because there are no tests.
+
+### Creating a test suite
+
+Creating test suites is easy using the mlGenerateUnitTestSuite gradle task.  Run the following to setup a sample test suite:
+```sh
+./gradlew mlGenerateUnitTestSuite
+```
+
+Now a new test suite has been generated in `src/test/ml-modules/root/test/suites` called `SampleTestSuite`.
+
+If `mlWatch` is being used, refreshing the web browser at http://localhost:8004/test/ will now show the newly created
+`SampleTestSuite`.  The suite can be run using the Run Tests button at the top or bottom of the page.
 
 # Start using marklogic-junit
-Check out the [marklogic-junit sub-project](https://github.com/marklogic-community/marklogic-unit-test/tree/master/marklogic-junit)
-to get started using marklogic-junit.
+Check out the [marklogic-junit5 sub-project](https://github.com/marklogic-community/marklogic-unit-test/tree/master/marklogic-junit5)
+to get started using marklogic-junit5.

marklogic-junit/README.md → marklogic-junit5/README.md

@@ -36,7 +36,7 @@ public class SearchTest extends AbstractSpringMarkLogicTest {
 
 ## 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 
+If you'd like to use marklogic-junit5 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

marklogic-junit/build.gradle → marklogic-junit5/build.gradle

@@ -50,11 +50,11 @@ publishing {
 	publications {
 		mainJava(MavenPublication) {
 			from components.java
-      artifactId "marklogic-junit"
+      artifactId project.name
 		}
 		sourcesJava(MavenPublication) {
 			from components.java
-      artifactId "marklogic-junit"
+      artifactId project.name
 			artifact sourcesJar
 		}
 	}
@@ -70,7 +70,7 @@ if (project.hasProperty("myBintrayUser")) {
 			name = project.name
       userOrg = 'marklogic-community'
 			licenses = ["Apache-2.0"]
-			vcsUrl = "https://github.com/marklogic-community/" + project.name + ".git"
+			vcsUrl = "https://github.com/marklogic-community/marklogic-unit-test.git"
 			version {
 				name = project.version
 				released = new Date()

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

@@ -1,4 +1,4 @@
-This project shows an example of using both marklogic-junit and marklogic-unit-test within a 
+This project shows an example of using both marklogic-junit5 and marklogic-unit-test within a 
 Data Hub Framework version 4 project. 
 
 To try this out locally, first initialize the DHF project:

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

@@ -10,9 +10,9 @@ repositories {
 }
 
 dependencies {
-  mlRestApi "com.marklogic:marklogic-unit-test-modules:0.13.develop"
+  mlRestApi "com.marklogic:marklogic-unit-test-modules:1.0.beta"
 
-	testCompile "com.marklogic:marklogic-junit:0.13.develop"
+	testCompile "com.marklogic:marklogic-junit5:1.0.beta"
   testCompile "com.marklogic:marklogic-data-hub:4.2.2"
 
 	// Needed by Gradle 4.6+

marklogic-junit/examples/simple-ml-gradle/README.md → marklogic-junit5/examples/simple-ml-gradle/README.md

@@ -1,4 +1,4 @@
-This project shows a basic setup for writing JUnit tests with marklogic-junit against an application deployed 
+This project shows a basic setup for writing JUnit tests with marklogic-junit5 against an application deployed 
 with [ml-gradle](https://github.com/marklogic-community/ml-gradle). In addition, it includes an example of executing
 tests written using [marklogic-unit-test](https://github.com/marklogic-community/marklogic-unit-test) via JUnit.
 
@@ -21,9 +21,9 @@ This task should complete with an output of "BUILD SUCCESSFUL", with the JUnit t
 ./build/reports/tests/test/index.html . In this report, you'll also see how the 2 marklogic-unit-test modules - located under
 src/test/ml-modules - were both executed as separate tests. 
 
-## Using marklogic-junit in your own ml-gradle project
+## Using marklogic-junit5 in your own ml-gradle project
 
-Read through each of the following steps to use marklogic-junit in your own project.
+Read through each of the following steps to use marklogic-junit5 in your own project.
 
 ### Configure build.gradle
 
@@ -39,7 +39,7 @@ Next, add the following dependencies - this assumes you're using Gradle version
     dependencies {
       // existing dependencies
 
-      testCompile "com.marklogic:marklogic-junit:0.10.0"
+      testCompile "com.marklogic:marklogic-junit5:1.0.beta"
 
       testRuntime "org.junit.jupiter:junit-jupiter-engine:5.3.0"
 
@@ -60,7 +60,7 @@ If you haven't already, set the value of mlTestRestPort in gradle.properties to
     mlTestRestPort=8211
 
 If you haven't done this and run mlDeploy before, then run mlDeploy now to deploy a test app server and database that
-mirror your regular REST server and database (marklogic-junit depends on a REST server):
+mirror your regular REST server and database (marklogic-junit5 depends on a REST server):
 
     ./gradlew mlDeploy
 
@@ -72,14 +72,14 @@ log some information in certain tests.
 
 ### Create a test class and run it
 
-You're now ready to start writing JUnit 5 tests using marklogic-junit. See the src/test/java/org/example directory in 
+You're now ready to start writing JUnit 5 tests using marklogic-junit5. See the src/test/java/org/example directory in 
 this project for several examples of tests that write and read documents, search them, and make assertions (including 
 XPath expressions with custom namespace prefixes) on different aspects of documents.
 
 The key point here is that the tests in this project extend AbstractSpringMarkLogicTest. This class uses 
 [Spring's test support](https://docs.spring.io/spring/docs/current/spring-framework-reference/testing.html) to 
 execute JUnit 5 tests with all of Spring's support for dependency and configuration management. This class depends on 
-another class from marklogic-junit named SimpleTestConfig to create a DatabaseClient that connects to your test REST 
+another class from marklogic-junit5 named SimpleTestConfig to create a DatabaseClient that connects to your test REST 
 server. SimpleTestConfig assumes the following properties can be found in gradle.properties and gradle-local.properties:
 
 - mlUsername

marklogic-junit/examples/simple-ml-gradle/build.gradle → marklogic-junit5/examples/simple-ml-gradle/build.gradle

@@ -15,11 +15,11 @@ repositories {
 }
 
 dependencies {
-  mlBundle "com.marklogic:marklogic-unit-test-modules:0.13.develop"
+  mlBundle "com.marklogic:marklogic-unit-test-modules:1.0.beta"
 
 	compile "com.marklogic:marklogic-client-api:4.2.0"
 
-	testCompile "com.marklogic:marklogic-junit:0.13.develop"
+	testCompile "com.marklogic:marklogic-junit:1.0.beta"
 
 	// 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"

marklogic-junit/gradle.properties → marklogic-junit5/gradle.properties

@@ -4,4 +4,3 @@ mlUsername=admin
 mlPassword=changeme-in-gradle-local.properties
 mlHost=localhost
 mlTestRestPort=8000
-

marklogic-junit/src/main/java/com/marklogic/junit5/dhf/DataHubTestConfig.java → marklogic-junit5/src/main/java/com/marklogic/junit5/dhf/DataHubTestConfig.java

@@ -68,7 +68,7 @@ public DatabaseClientConfig databaseClientConfig() {
   }
 
   /**
-   * marklogic-junit depends on one of these for obtaining a DatabaseClient.
+   * marklogic-junit5 depends on one of these for obtaining a DatabaseClient.
    *
    * @return
    */

marklogic-junit/src/main/java/com/marklogic/junit5/dhf/DataHubUnitTestsTest.java → marklogic-junit5/src/main/java/com/marklogic/junit5/dhf/DataHubUnitTestsTest.java

@@ -8,8 +8,8 @@
 /**
  * This is a JUnit 5 parameterized test that invokes every test module defined by the REST endpoint provided by the
  * marklogic-unit-test framework - https://github.com/marklogic-community/marklogic-unit-test . This class is abstract
- * so that it is not run when executing tests for the marklogic-junit project - it is instead expected to be extended
- * in a project that depends on marklogic-junit.
+ * so that it is not run when executing tests for the marklogic-junit5 project - it is instead expected to be extended
+ * in a project that depends on marklogic-junit5.
  * <p>
  * To make use of this in your own project, simply create a class that extends this in your src/test/java directory (
  * or whatever you store the source of test classes) so that it'll be executed by your IDE / Maven / Gradle / etc.

marklogic-junit/src/main/java/com/marklogic/junit5/spring/MarkLogicUnitTestsTest.java → marklogic-junit5/src/main/java/com/marklogic/junit5/spring/MarkLogicUnitTestsTest.java

@@ -8,8 +8,8 @@
 /**
  * This is a JUnit 5 parameterized test that invokes every test module defined by the REST endpoint provided by the
  * marklogic-unit-test framework - https://github.com/marklogic-community/marklogic-unit-test . This class is abstract
- * so that it is not run when executing tests for the marklogic-junit project - it is instead expected to be extended
- * in a project that depends on marklogic-junit.
+ * so that it is not run when executing tests for the marklogic-junit5 project - it is instead expected to be extended
+ * in a project that depends on marklogic-junit5.
  * <p>
  * To make use of this in your own project, simply create a class that extends this in your src/test/java directory (
  * or whatever you store the source of test classes) so that it'll be executed by your IDE / Maven / Gradle / etc.

marklogic-unit-test-client/build.gradle

@@ -56,7 +56,7 @@ if (project.hasProperty("myBintrayUser")) {
 			name = project.name
 			userOrg = 'marklogic-community'
 			licenses = ["Apache-2.0"]
-			vcsUrl = "https://github.com/marklogic-community/" + project.name + ".git"
+			vcsUrl = "https://github.com/marklogic-community/marklogic-unit-test.git"
 			version {
 				name = project.version
 				released = new Date()

marklogic-unit-test-modules/build.gradle

@@ -56,7 +56,7 @@ if (project.hasProperty("myBintrayUser")) {
 			name = project.name
 			userOrg = 'marklogic-community'
 			licenses = ["Apache-2.0"]
-			vcsUrl = "https://github.com/marklogic-community/" + project.name + ".git"
+			vcsUrl = "https://github.com/marklogic-community/marklogic-unit-test.git"
 			version {
 				name = project.version
 				released = new Date()

settings.gradle

@@ -1 +1 @@
-include "marklogic-unit-test-modules", "marklogic-unit-test-client", "marklogic-junit"
+include "marklogic-unit-test-modules", "marklogic-unit-test-client", "marklogic-junit5"