|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Debugging tests |
| 4 | +nav_order: 5 |
| 5 | +--- |
| 6 | + |
| 7 | +Like all unit testing frameworks, marklogic-unit-test is intended to speed up the cycle of developing, testing, and |
| 8 | +fixing code. A critical aspect of that is understanding why a test failed and how to fix it. This page provides |
| 9 | +guidance on how you can write your tests to ensure they can be easily debugged by any member of your development |
| 10 | +team. |
| 11 | + |
| 12 | +## Development setup |
| 13 | + |
| 14 | +Before looking at how to write tests, you should ensure that you can change your application code and test the |
| 15 | +changes as quickly as possible. As mentioned in the [Getting started guide](getting-started.md), ml-gradle supports |
| 16 | +[watching for module changes](https://github.com/marklogic/ml-gradle/wiki/Watching-for-module-changes) so that when |
| 17 | +you modify either an application module file or test module file, the file will be immediately loaded into your |
| 18 | +application's modules database. This allows you to test your changes as quickly as possible. |
| 19 | + |
| 20 | +To enable this, simply run the following Gradle task in its own terminal window: |
| 21 | + |
| 22 | + ./gradlew -i mlWatch |
| 23 | + |
| 24 | +The Gradle "-i" flag - for info-level logging - results in each modified file being logged when it is loaded into |
| 25 | +MarkLogic. |
| 26 | + |
| 27 | +## Test assertion messages |
| 28 | + |
| 29 | +Each [assertion function](assertion-functions.md) in marklogic-unit-test supports an assertion message as its final argument. |
| 30 | +These are recommended for when the intent of an assertion is not readily apparent from the two values being compared. |
| 31 | + |
| 32 | +For example, consider the following assertion: |
| 33 | + |
| 34 | + const actual = someLib.something(); |
| 35 | + test.assertEqual(3, actual); |
| 36 | + |
| 37 | +If that assertion fails because "actual" has a value of 2, marklogic-unit-test will throw the following error: |
| 38 | + |
| 39 | + expected: 3 actual: 2 (ASSERT-EQUAL-FAILED) |
| 40 | + |
| 41 | +However, this doesn't explain why "3" is the expected value. The optional 3rd argument in `test.assertEqual` |
| 42 | +provides a test developer with a chance to explain why the value is expected - e.g.: |
| 43 | + |
| 44 | + const actual = someLib.something(); |
| 45 | + test.assertEqual(3, actual, "Due to such-and-such reason, 3 should be returned"); |
| 46 | + |
| 47 | +The "such-and-such reason" would of course be replaced with a meaningful explanation in your test. |
| 48 | +marklogic-unit-test will then include this message in the failure message: |
| 49 | + |
| 50 | + Due to such-and-such reason, 3 should be returned; expected: 3 actual: 2 (ASSERT-EQUAL-FAILED) |
| 51 | + |
| 52 | +## Using log statements |
| 53 | + |
| 54 | +While tools such as [mlxprs](https://github.com/marklogic/mlxprs) exist to leverage the debugging capabilities within |
| 55 | +MarkLogic, you may often find it helpful to include log statements both in your application module and in your test |
| 56 | +module. These can log the value of certain variables that are not returned by the function being tested but whose |
| 57 | +values provide insight into how the application code is behaving. |
| 58 | + |
| 59 | +For JavaScript code, use the following: |
| 60 | + |
| 61 | + const value = someLib.something(); |
| 62 | + console.log("The value", value); |
| 63 | + |
| 64 | +And for XQuery code, use the following: |
| 65 | + |
| 66 | + let $value := someLib:something() |
| 67 | + let $_ := xdmp:log(("The value", $value)) |
| 68 | + |
| 69 | +You can add these statements to your tests as well. |
| 70 | + |
| 71 | +Log messages will then appear in the MarkLogic log file named "PORT_ErrorLog.txt", where "PORT" is the port number |
| 72 | +of the MarkLogic app server that you are running the tests against. |
| 73 | + |
| 74 | +## Examining the Gradle test report |
| 75 | + |
| 76 | +When running tests via Gradle - either via `./gradlew test` or `./gradlew mlUnitTest` - one or more test failures will |
| 77 | +result in the task failing with the location of the test report being logged. The test report allows you to see details |
| 78 | +on each test, including the failed assertion message and stacktrace for each failed test. |
| 79 | + |
| 80 | +When running `./gradlew test`, the test report will be available at "build/reports/tests/tests/index.html". You can |
| 81 | +open this file in a web browser to see the results; it is recommended to keep that window open and simply refresh it |
| 82 | +after re-running the Gradle `test` task. |
| 83 | + |
| 84 | +When running `./gradlew mlUnitTest`, the test report is a set of JUnit-formatted XML files available at |
| 85 | +"build/test-results/marklogic-unit-test". This approach does not result in an HTML web page that can be viewed in a web |
| 86 | +browser, but each XML file will contain the results for the tests in a particular suite, including the failed assertion |
| 87 | +messages and stacktrace for each failed test. |
| 88 | + |
0 commit comments