Merge branch 'release/1.3.0'

Author: rjrudin

docs/assertion-functions.md

@@ -2,6 +2,7 @@
 layout: default
 title: Assertion functions
 nav_order: 6
+permalink: /docs/assertions
 ---
 
 The list below captures the assertion functions available in the marklogic-unit-test `/test/test-helper.xqy` module.

docs/getting-started.md

@@ -2,6 +2,8 @@
 layout: default
 title: Getting started
 nav_order: 2
+[comment]: "/docs" is used to preserve links to previous set of docs.
+permalink: /docs
 ---
 
 This guide walks you through adding marklogic-unit-test to an existing project, followed by writing, loading, and 
@@ -39,7 +41,7 @@ in your `build.gradle` file), run the following task to install marklogic-unit-t
 
     ./gradlew -i mlLoadModules
 
-If you would like to [run your marklogic-unit-test tests](running-tests.md) via Gradle, you'll also need to include the 
+If you would like to [run your marklogic-unit-test tests](/docs/running) via Gradle, you'll also need to include the 
 following at the top of your `build.gradle` file:
 
 ```
@@ -89,7 +91,7 @@ therefore be stored in the `src/test/ml-modules/root/test/suites/(name of suite)
 
 A test suite can have any name; for this example, we will use "thesaurus" as the name. Test modules can have any name
 as well with a few exceptions for setup and teardown modules; those exceptions are covered in the 
-[guide for writing tests](writing-tests.md). We will use "simple-test.sjs" for this example, so we create a
+[guide for writing tests](/docs/writing). We will use "simple-test.sjs" for this example, so we create a
 file at `src/test/ml-modules/root/test/suites/thesaurus/simple-test.sjs` with the following initial content:
 
 ```
@@ -98,7 +100,7 @@ const lib = require("/example/lib.sjs");
 ```
 
 The first line above imports the marklogic-unit-test module containing dozens of useful 
-[assertion functions](assertion-functions.md); every test
+[assertion functions](/docs/assertions); every test
 module will need this imported. The second line imports the library module that we wish to verify. 
 
 Next, add the following text to the file:
@@ -115,7 +117,7 @@ const result = lib.lookupTerm("Car");
 The above code will invoke the `lookupTerm` function that we wish to test with a term that we know is in the 
 application's thesaurus. Each `assertEqual` function call - along with every other assertion function in 
 marklogic-unit-test - will return a success or failure. The test then returns an array of these successes and failures.
-The different approaches for [running tests](running-tests.md) know how to collect these results and display how many
+The different approaches for [running tests](/docs/running) know how to collect these results and display how many
 tests passed and how many failed.
 
 ## Configuring a connection to MarkLogic
@@ -162,7 +164,7 @@ Once you execute either `mlWatch` or `mlLoadModules`, your test will be ready to
 
 ## Running a test
 
-marklogic-unit-test provides [several ways to run tests](running-tests.md). We will look at the two primary ways to 
+marklogic-unit-test provides [several ways to run tests](/docs/running). We will look at the two primary ways to 
 run the test module we just wrote and loaded into our application's modules database.
 
 First, tests can be run via the ml-gradle `mlUnitTest` task, as long as you have included the 
@@ -216,6 +218,6 @@ This guide has covered the following topics:
 3. How to load a test.
 4. How to run a test.
 
-With the above information and the references on [writing tests](writing-tests.md) and 
-[running tests](running-tests.md), you can now start writing tests for the library modules in your application, 
+With the above information and the references on [writing tests](/docs/writing) and 
+[running tests](/docs/running), you can now start writing tests for the library modules in your application, 
 ensuring that you can quickly enhance your application without breaking any existing functionality. 

docs/index.md

@@ -19,7 +19,7 @@ marklogic-unit-test includes the following components:
    popular Java testing frameworks. 
 4. A REST endpoint for integrating with testing frameworks in any language.
 
-Please see the [Getting started guide](getting-started.md) to learn how to include marklogic-unit-test in your 
+Please see the [Getting started guide](/docs) to learn how to include marklogic-unit-test in your 
 project and to start writing and running tests.
 
 If you have any questions or run into issues while using marklogic-unit-test, try one of the following:

docs/loading-test-data.md

@@ -2,6 +2,7 @@
 layout: default
 title: Loading test data
 nav_order: 5
+permalink: /docs/loading
 ---
 
 marklogic-unit-test includes a simple mechanism for loading test data specific to a test suite. This capability is 
@@ -32,7 +33,7 @@ test:load-test-file("sample-doc.json", xdmp:database(), "/sample-doc.json")
 ```
 
 The above examples can also be implemented in either `suiteSetup.sjs` or `suite-setup.xqy` if desired - see the 
-[guide on writing tests](writing-tests.md) for more information on setup and teardown modules.
+[guide on writing tests](/docs/writing) for more information on setup and teardown modules.
 
 You can also use a teardown module to delete the data that was loaded. However, leaving data in place after a test 
 concludes is often helpful for both manually verifying what it's in the database and for debugging test failures. 

docs/running-tests.md

@@ -2,14 +2,15 @@
 layout: default
 title: Running tests
 nav_order: 4
+permalink: /docs/running
 ---
 
 Tests written using marklogic-unit-test can be run in several ways, each of which is described below. 
 
 ## Using Gradle 
 
 The [ml-gradle plugin for Gradle](https://github.com/marklogic/ml-gradle) provides an `mlUnitTest` task for running 
-all of your marklogic-unit-test tests. As noted in the [Getting started guide](getting-started.md), you will need to 
+all of your marklogic-unit-test tests. As noted in the [Getting started guide](/docs), you will need to 
 include the following block at the top of your `build.gradle` file to ensure this task can run successfully:
 
 ```
@@ -38,9 +39,9 @@ App Server.
 ## Using the web application
 
 Once you have deployed your application along with the marklogic-unit-test modules, as described in the
-[Getting started guide](getting-started.md), you will be able to access a custom endpoint via any MarkLogic HTTP
+[Getting started guide](/docs), you will be able to access a custom endpoint via any MarkLogic HTTP
 App Server associated with the modules database containing your application modules. The path of that endpoint is
-`/test/default.xqy`. For example, since the App Server in the [Getting started guide](getting-started.md) listens on
+`/test/default.xqy`. For example, since the App Server in the [Getting started guide](/docs) listens on
 port 8024, the endpoint would be accessible at <http://localhost:8024/test/default.xqy>.
 
 The web application at this custom endpoint provides a functional, albeit antiquated-looking, interface for running

docs/writing-tests.md

@@ -2,6 +2,7 @@
 layout: default
 title: Writing tests
 nav_order: 3
+permalink: /docs/writing
 ---
 
 This guide is a reference on the different kinds of test modules, setup modules, and teardown modules you can write 
@@ -11,7 +12,7 @@ in the `src/test/ml-modules/root/test/suites/thesaurus` directory in the
 
 ## Location of test files
 
-As described in the [Getting started guide](getting-started.md), marklogic-unit-test requires the URI of each module
+As described in the [Getting started guide](/docs), marklogic-unit-test requires the URI of each module
 to begin with `/test/suites/(name of suite)/`. Thus, all test files should be located in an 
 [ml-gradle modules directory](https://github.com/marklogic/ml-gradle/wiki/How-modules-are-loaded) under 
 `root/test/suites/(name of suite)/`. 
@@ -41,7 +42,7 @@ the test helper library to be followed by an import of the application module be
     const test = require("/test/test-helper.xqy");
     const lib = require("/example/lib.sjs");
 
-The test should then return the output of one or more [assertion functions](assertion-functions.md) 
+The test should then return the output of one or more [assertion functions](/docs/assertions) 
 found in the `test-helper` module. This can be done via a single array:
 
 ```
@@ -96,7 +97,7 @@ import module namespace ex="http://example.org" at "/example/lib.xqy";
 ```
 
 The test will then call the function to be tested and use the helper library to invoke one or more
-[assertion functions](assertion-functions.md), returning the results of those assertions:
+[assertion functions](/docs/assertions), returning the results of those assertions:
 
 ```
 let $result := ex:lookup-term("Car", "elements")

examples/test-examples/src/main/ml-modules/root/example/boom-lib.sjs

@@ -0,0 +1,25 @@
+"use strict";
+
+const BOOM_QNAME = xs.QName("MATCH-BOOM");
+const BOOM_ERROR = "The values matched";
+
+/**
+ * Throw an error if the parameters match.
+ * @param param1
+ * @param param2
+ * @returns
+ */
+function mightBoom(param1, param2) {
+  // When an SJS test uses test-helper.xqy and passes a function, the parameters are wrapped as objects which may
+  // impact how the application code has to be written or has to be tested. A future SJS version of test-helper.xqy
+  // will avoid this issue.
+  if (param1.toString() === param2.toString()) {
+    fn.error(BOOM_QNAME, BOOM_ERROR);
+  }
+  return param1;
+}
+
+module.exports = {
+  BOOM_ERROR,
+  mightBoom,
+};

examples/test-examples/src/main/ml-modules/root/example/boom-lib.xqy

@@ -0,0 +1,17 @@
+xquery version "1.0-ml";
+
+module namespace ex = "http://marklogic.com/example";
+
+declare option xdmp:mapping "false";
+
+declare variable $BOOM_QNAME := xs:QName("MATCH-BOOM");
+declare variable $BOOM_ERROR := "The values matched";
+
+declare function mightBoom($param1, $param2) {
+  if ($param1 eq $param2) then
+    fn:error($BOOM_QNAME, $BOOM_ERROR)
+  else (
+    xdmp:log("mightBoom; the parameters are different"),
+    $param1
+  )
+};

examples/test-examples/src/test/ml-modules/root/test/suites/might-boom/boom-test.sjs

@@ -0,0 +1,22 @@
+"use strict";
+
+const test = require("/test/test-helper.xqy");
+const lib = require("/example/boom-lib.sjs");
+
+const SAME_PARAM = "1";
+
+let assertions = [
+  test.assertEqual(
+    1,
+    lib.mightBoom(1, 2),
+    "Different values should not blow up"
+  ),
+  test.assertThrowsError(
+    xdmp.function(xs.QName("mightBoom"), "/example/boom-lib.sjs"),
+    SAME_PARAM,
+    SAME_PARAM,
+    lib.BOOM_ERROR
+  ),
+];
+
+assertions;

examples/test-examples/src/test/ml-modules/root/test/suites/might-boom/boom-test.xqy

@@ -0,0 +1,16 @@
+xquery version "1.0-ml";
+
+import module namespace test = "http://marklogic.com/test" at "/test/test-helper.xqy";
+import module namespace lib = "http://marklogic.com/example" at "/example/boom-lib.xqy";
+
+declare variable $SAME_PARAM := "1";
+
+
+(
+  test:assert-throws-error(
+    xdmp:function(fn:QName("http://marklogic.com/example", "mightBoom"), "/example/boom-lib.xqy"),
+    $SAME_PARAM,
+    $SAME_PARAM,
+    $lib:BOOM_ERROR
+  )
+)