Merge pull request #200 from marklogic-community/release/1.4.0

Release/1.4.0

Author: rjrudin

build.gradle

@@ -4,7 +4,7 @@ subprojects {
   apply plugin: "signing"
 
   group = "com.marklogic"
-  version = "1.3.0"
+  version = "1.4.0"
 
   java {
     sourceCompatibility = 1.8
@@ -16,6 +16,10 @@ subprojects {
 
     // For local development
     mavenLocal()
+
+    maven {
+      url "https://nexus.marklogic.com/repository/maven-snapshots/"
+    }
   }
 
   dependencies {

docs/assertion-functions.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Assertion functions
-nav_order: 6
+nav_order: 7
 permalink: /docs/assertions
 ---
 
@@ -47,14 +47,15 @@ assert-same-values($expected as item()*, $actual as item()*)
 assert-same-values($expected as item()*, $actual as item()*, $message as xs:string*)
 assert-throws-error($function as xdmp:function)
 assert-throws-error($function as xdmp:function, $error-code as xs:string?)
-assert-throws-error($function as xdmp:function, $param1 as item()*, $error-code as xs:string?)
-assert-throws-error($function as xdmp:function, $param1 as item()*, $param2 as item()*, $error-code as xs:string?)
-assert-throws-error($function as xdmp:function, $param1 as item()*, $param2 as item()*, $param3 as item()*, $error-code as xs:string?)
-assert-throws-error($function as xdmp:function, $param1 as item()*, $param2 as item()*, $param3 as item()*, $param4 as item()*, $error-code as xs:string?)
-assert-throws-error($function as xdmp:function, $param1 as item()*, $param2 as item()*, $param3 as item()*, $param4 as item()*, $param5 as item()*, $error-code as xs:string?)
-assert-throws-error($function as xdmp:function, $param1 as item()*, $param2 as item()*, $param3 as item()*, $param4 as item()*, $param5 as item()*, $param6 as item()*, $error-code as xs:string?)
+* assert-throws-error($function as xdmp:function, $param1 as item()*, $error-code as xs:string?)
+* assert-throws-error($function as xdmp:function, $param1 as item()*, $param2 as item()*, $error-code as xs:string?)
+* assert-throws-error($function as xdmp:function, $param1 as item()*, $param2 as item()*, $param3 as item()*, $error-code as xs:string?)
+* assert-throws-error($function as xdmp:function, $param1 as item()*, $param2 as item()*, $param3 as item()*, $param4 as item()*, $error-code as xs:string?)
+* assert-throws-error($function as xdmp:function, $param1 as item()*, $param2 as item()*, $param3 as item()*, $param4 as item()*, $param5 as item()*, $error-code as xs:string?)
+* assert-throws-error($function as xdmp:function, $param1 as item()*, $param2 as item()*, $param3 as item()*, $param4 as item()*, $param5 as item()*, $param6 as item()*, $error-code as xs:string?)
 assert-throws-error-with-message($function as xdmp:function, $expected-error-code as xs:string, $expected-message as xs:string)
 assert-throws-error-with-message($function as xdmp:function, $expected-error-code as xs:string, $expected-message as xs:string, $message as xs:string*)
 assert-true($conditions as xs:boolean*)
 assert-true($conditions as xs:boolean*, $message as xs:string?)
 ```
+- Note: Functions marked with * are deprecated and will be removed in the 2.0 release of marklogic-unit-test. Please use the assert-throws-error function that requires a function to be passed to it.

docs/debugging-tests.md

@@ -0,0 +1,89 @@
+---
+layout: default
+title: Debugging tests
+nav_order: 5
+permalink: /docs/debugging
+---
+
+Like all unit testing frameworks, marklogic-unit-test is intended to speed up the cycle of developing, testing, and 
+fixing code. A critical aspect of that is understanding why a test failed and how to fix it. This page provides 
+guidance on how you can write your tests to ensure they can be easily debugged by any member of your development 
+team. 
+
+## Development setup
+
+Before looking at how to write tests, you should ensure that you can change your application code and test the 
+changes as quickly as possible. As mentioned in the [Getting started guide](/docs), ml-gradle supports 
+[watching for module changes](https://github.com/marklogic/ml-gradle/wiki/Watching-for-module-changes) so that when 
+you modify either an application module file or test module file, the file will be immediately loaded into your 
+application's modules database. This allows you to test your changes as quickly as possible.
+
+To enable this, simply run the following Gradle task in its own terminal window:
+
+    ./gradlew -i mlWatch
+
+The Gradle "-i" flag - for info-level logging - results in each modified file being logged when it is loaded into 
+MarkLogic. 
+
+## Test assertion messages
+
+Each [assertion function](/docs/assertions) in marklogic-unit-test supports an assertion message as its final argument. 
+These are recommended for when the intent of an assertion is not readily apparent from the two values being compared. 
+
+For example, consider the following assertion:
+
+    const actual = someLib.something();
+    test.assertEqual(3, actual);
+
+If that assertion fails because "actual" has a value of 2, marklogic-unit-test will throw the following error:
+
+    expected: 3 actual: 2 (ASSERT-EQUAL-FAILED)
+
+However, this doesn't explain why "3" is the expected value. The optional 3rd argument in `test.assertEqual` 
+provides a test developer with a chance to explain why the value is expected - e.g.:
+
+    const actual = someLib.something();
+    test.assertEqual(3, actual, "Due to such-and-such reason, 3 should be returned");
+
+The "such-and-such reason" would of course be replaced with a meaningful explanation in your test. 
+marklogic-unit-test will then include this message in the failure message:
+
+    Due to such-and-such reason, 3 should be returned; expected: 3 actual: 2 (ASSERT-EQUAL-FAILED)
+
+## Using log statements
+
+While tools such as [mlxprs](https://github.com/marklogic/mlxprs) exist to leverage the debugging capabilities within
+MarkLogic, you may often find it helpful to include log statements both in your application module and in your test 
+module. These can log the value of certain variables that are not returned by the function being tested but whose 
+values provide insight into how the application code is behaving. 
+
+For JavaScript code, use the following:
+
+    const value = someLib.something();
+    console.log("The value", value);
+
+And for XQuery code, use the following:
+
+    let $value := someLib:something()
+    let $_ := xdmp:log(("The value", $value))
+
+You can add these statements to your tests as well. 
+
+Log messages will then appear in the MarkLogic log file named "PORT_ErrorLog.txt", where "PORT" is the port number 
+of the MarkLogic app server that you are running the tests against.
+
+## Examining the Gradle test report
+
+When running tests via Gradle - either via `./gradlew test` or `./gradlew mlUnitTest` - one or more test failures will 
+result in the task failing with the location of the test report being logged. The test report allows you to see details
+on each test, including the failed assertion message and stacktrace for each failed test. 
+
+When running `./gradlew test`, the test report will be available at "build/reports/tests/tests/index.html". You can 
+open this file in a web browser to see the results; it is recommended to keep that window open and simply refresh it 
+after re-running the Gradle `test` task. 
+
+When running `./gradlew mlUnitTest`, the test report is a set of JUnit-formatted XML files available at 
+"build/test-results/marklogic-unit-test". This approach does not result in an HTML web page that can be viewed in a web
+browser, but each XML file will contain the results for the tests in a particular suite, including the failed assertion 
+messages and stacktrace for each failed test.
+

docs/getting-started.md

@@ -30,7 +30,7 @@ adding the following configuration to the project's `build.gradle` file:
 
 ```
 dependencies {
-  mlBundle "com.marklogic:marklogic-unit-test-modules:1.3.0"
+  mlBundle "com.marklogic:marklogic-unit-test-modules:1.4.0"
 }
 ```
 
@@ -49,7 +49,7 @@ buildscript {
     mavenCentral()
   }
   dependencies {
-    classpath "com.marklogic:marklogic-unit-test-client:1.3.0"
+    classpath "com.marklogic:marklogic-unit-test-client:1.4.0"
   }
 }
 ```

docs/loading-test-data.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Loading test data
-nav_order: 5
+nav_order: 6
 permalink: /docs/loading
 ---
 

docs/running-tests.md

@@ -19,7 +19,7 @@ buildscript {
     mavenCentral()
   }
   dependencies {
-    classpath "com.marklogic:marklogic-unit-test-client:1.3.0"
+    classpath "com.marklogic:marklogic-unit-test-client:1.4.0"
   }
 }
 ```

examples/getting-started/build.gradle

@@ -3,7 +3,7 @@ buildscript {
     mavenCentral()
   }
   dependencies {
-    classpath "com.marklogic:marklogic-unit-test-client:1.3.0"
+    classpath "com.marklogic:marklogic-unit-test-client:1.4.0"
   }
 }
 
@@ -17,5 +17,5 @@ repositories {
 }
 
 dependencies {
-  mlBundle "com.marklogic:marklogic-unit-test-modules:1.3.0"
+  mlBundle "com.marklogic:marklogic-unit-test-modules:1.4.0"
 }

examples/test-examples/build.gradle

@@ -3,19 +3,19 @@ buildscript {
     mavenCentral()
   }
   dependencies {
-    classpath "com.marklogic:marklogic-unit-test-client:1.3.0"
+    classpath "com.marklogic:marklogic-unit-test-client:1.4.0"
   }
 }
 
 plugins {
   id "net.saliman.properties" version "1.5.2"
-  id "com.marklogic.ml-gradle" version "4.5.2"
+  id "com.marklogic.ml-gradle" version "4.6.0"
 }
 
 repositories {
   mavenCentral()
 }
 
 dependencies {
-  mlBundle "com.marklogic:marklogic-unit-test-modules:1.3.0"
+  mlBundle "com.marklogic:marklogic-unit-test-modules:1.4.0"
 }

marklogic-junit5/build.gradle

@@ -4,12 +4,12 @@ plugins {
 
 dependencies {
   api project(":marklogic-unit-test-client")
-  api "com.marklogic:ml-javaclient-util:4.5.0"
+  api "com.marklogic:ml-javaclient-util:4.6.0"
   api "org.jdom:jdom2:2.0.6.1"
-  api "org.junit.jupiter:junit-jupiter:5.9.2"
-  api "org.springframework:spring-context:5.3.24"
-  api "org.springframework:spring-test:5.3.24"
-  api "com.fasterxml.jackson.core:jackson-databind:2.14.1"
+  api "org.junit.jupiter:junit-jupiter:5.10.0"
+  api "org.springframework:spring-context:5.3.29"
+  api "org.springframework:spring-test:5.3.29"
+  api "com.fasterxml.jackson.core:jackson-databind:2.15.2"
   api 'org.slf4j:slf4j-api:1.7.36'
 
   implementation "jaxen:jaxen:2.0.0"

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

@@ -36,7 +36,7 @@ Next, add the following dependencies:
     dependencies {
       // existing dependencies
       
-      testImplementation "com.marklogic:marklogic-junit5:1.3.0"
+      testImplementation "com.marklogic:marklogic-junit5:1.4.0"
             
       // Forcing Spring to use logback instead of commons-logging
       testImplementation "ch.qos.logback:logback-classic:1.3.5"
@@ -107,8 +107,8 @@ You'll still be able to leverage all of the testing support in AbstractMarkLogic
 If you'd like to write and execute marklogic-unit-test test modules, add the following to your build.gradle file as well (grab
 the latest version for both dependencies):
 
-    mlBundle "com.marklogic:marklogic-unit-test-modules:1.3.0"
-    testImplementation "com.marklogic:marklogic-unit-test-client:1.3.0"
+    mlBundle "com.marklogic:marklogic-unit-test-modules:1.4.0"
+    testImplementation "com.marklogic:marklogic-unit-test-client:1.4.0"
 
 In addition, add the following to gradle.properties so that you can store test modules in a directory separate from 
 your application modules: