document how to measure code coverage of integration tests

doc/sphinx-guides/source/_static/util/instrument_war_jacoco.bash

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+
+JACOCO_HOME=${HOME}/local/jacoco-0.8.2/lib/
+PID=$$
+WAR_IN=$1
+WAR_OUT=$2
+
+if [ -z "${WAR_IN}" ]; then
+	echo "no input war specified; bailing out"
+	exit 1
+fi
+
+if [ -z "${WAR_OUT}" ]; then
+	echo "no output war specified; bailing out"
+	exit 1
+fi
+
+if [ ! -e "${JACOCO_HOME}/jacococli.jar" ]; then
+	echo "jacococli.jar not found in ${JACOCO_HOME}; bailing out"
+	exit 1
+fi
+
+TMPDIR=/tmp/war-wksp-${PID}
+CWD=`pwd`
+
+mkdir -p ${TMPDIR}/extract/
+cp ${WAR_IN} ${TMPDIR}/
+cd ${TMPDIR}/extract/
+wb=`basename ${WAR_IN}`
+jar xf ../${wb}
+mv WEB-INF/classes WEB-INF/orig-classes
+java -jar ${JACOCO_HOME}/jacococli.jar instrument WEB-INF/orig-classes/ --dest WEB-INF/classes
+rm -r WEB-INF/orig-classes/
+jar cf ${CWD}/${WAR_OUT} *
+cd ${CWD}
+
+# assuming that /tmp gets auto-cleaned, don't bother removing ${TMPDIR}
+

doc/sphinx-guides/source/developers/testing.rst

@@ -188,6 +188,18 @@ Once installed, you may run commands with ``mvn [options] [<goal(s)>] [<phase(s)
 
 To see the full list of tests used by the Docker option mentioned above, see :download:`run-test-suite.sh <../../../../conf/docker-aio/run-test-suite.sh>`.
 
+Measuring Coverage of Integration Tests
+---------------------------------------
+Measuring the code coverage of integration tests with jacoco requires several steps:
+
+- Instrument the WAR file. Using an approach similar to :download:`this script <../_static/util/instrument_war_jacoco.bash>` is probably preferable to instrumenting the WAR directly (at least until the ``nu.xom.UnicodeUtil.decompose`` method too large exceptions get sorted).
+- Deploy the WAR file to a glassfish server with ``jacocoagent.jar`` in ``glassfish4/glassfish/lib/``
+- Run integration tests as usual
+- Use ``glassfish4/glassfish/domains/domain1/config/jacoco.exec`` to generate a report: ``java -jar ${JACOCO_HOME}/jacococli.jar report --classfiles ${DV_REPO}/target/classes --sourcefiles ${DV_REPO}/src/main/java --html ${DV_REPO}/target/coverage-it/ jacoco.exec``
+
+The same approach could be used to measure code paths exercised in normal use (by substituting the "run integration tests" step).
+There is obvious potential to improve automation of this process.
+
 Load/Performance Testing
 ------------------------