# HG changeset patch
# User redestad
# Date 1539268873 -7200
# Node ID 2ea07b19b446ee29cd9564dee5466cc86fc82f6b
# Parent  96ecae6d8049a94c34561006a75ec85d09918919
Document micro run-test target

diff -r 96ecae6d8049 -r 2ea07b19b446 doc/testing.md
--- a/doc/testing.md	Tue Oct 09 14:37:59 2018 +0200
+++ b/doc/testing.md	Thu Oct 11 16:41:13 2018 +0200
@@ -20,6 +20,7 @@
     $ make run-test-only TEST="gtest:LogTagSet gtest:LogTagSetDescriptions" GTEST="REPEAT=-1"
     $ make run-test TEST="hotspot:hotspot_gc" JTREG="JOBS=1;TIMEOUT=8;VM_OPTIONS=-XshowSettings -Xlog:gc+ref=debug"
     $ make run-test TEST="jtreg:test/hotspot:hotspot_gc test/hotspot/jtreg/native_sanity/JniVersion.java"
+    $ make run-test TEST="micro:java.lang.reflect" MICRO="FORK=1;WARMUP_ITER=2"
     $ make exploded-run-test TEST=tier2
 
 ### Configuration
@@ -31,6 +32,12 @@
 containing `lib/jtreg.jar` etc. (An alternative is to set the `JT_HOME`
 environment variable to point to the JTReg home before running `configure`.)
 
+To be able to run microbenchmarks, `configure` needs to know where to find
+the JMH dependency. Use `--with-jmh=<path to JMH jars>` to point to a directory
+containing the core JMH and transitive dependencies. The recommended dependencies 
+can be retrieved by running `sh make/devkit/createJMHBundle.sh`, after which 
+`--with-jmh=build/jmh/jars` should work.
+
 ## Test selection
 
 All functionality is available using the run-test make target. In this use
@@ -98,6 +105,16 @@
 variant present (e.g. server, client). So if you only have the server JVM
 present, then `gtest:all` will be equivalent to `gtest:all/server`.
 
+### Microbenchmarks
+
+Which microbenchmarks to run is selected using a regular expression
+following the `micro:` test descriptor, e.g., `micro:java.lang.reflect`. This
+delegates the test selection to JMH, meaning package name, class name and even
+benchmark method names can be used to select tests.
+
+Using special characters like `|` in the regular expression is possible, but
+needs to be escaped multiple times: `micro:ArrayCopy\\\\\|reflect`.
+
 ## Test results and summary
 
 At the end of the test run, a summary of all tests run will be presented. This
@@ -230,6 +247,35 @@
 
 Use `GTEST="OPTIONS=--help"` to see all available Gtest options.
 
+### Microbenchmark keywords
+
+#### FORK
+Override the number of benchmark forks to spawn. Same as specifying `-f <num>`.
+
+#### ITER
+Number of measurement iterations per fork. Same as specifying `-i <num>`.
+
+#### TIME
+Amount of time to spend in each measurement iteration, in seconds. Same as
+specifying `-r <num>`
+
+#### WARMUP_ITER
+Number of warmup iterations to run before the measurement phase in each fork.
+Same as specifying `-wi <num>`.
+
+#### WARMUP_TIME
+Amount of time to spend in each warmup iteration. Same as specifying `-w <num>`.
+
+#### RESULTS_FORMAT
+Specify to have the test run save a log of the values. Accepts the same values
+as `-rff`, i.e., `text`, `csv`, `scsv`, `json`, or `latex`.
+
+#### VM_OPTIONS
+Additional VM arguments to provide to forked off VMs. Same as `-jvmArgs <args>`
+
+#### OPTIONS
+Additional arguments to send to JMH.
+
 ---
 # Override some definitions in the global css file that are not optimal for
 # this document.