branch: elpa/cider
commit e8c4acd48eae9133c184f34cedcb7ba36637d6e9
Author: Bozhidar Batsov <[email protected]>
Commit: Bozhidar Batsov <[email protected]>
Document the tap viewer and ClojureScript test support
Two 2.0 features shipped without manual coverage. Add a Tap Viewer page
(wired into the nav) describing cider-tap, its buffer commands, the
ClojureScript caveat, and the tap-a-form helpers; and a "Running
ClojureScript Tests" section covering the cljs.test support and its
cider-nrepl requirement.
---
doc/modules/ROOT/nav.adoc | 1 +
doc/modules/ROOT/pages/debugging/tap.adoc | 61 +++++++++++++++++++++++
doc/modules/ROOT/pages/testing/running_tests.adoc | 15 +++++-
3 files changed, 76 insertions(+), 1 deletion(-)
diff --git a/doc/modules/ROOT/nav.adoc b/doc/modules/ROOT/nav.adoc
index b920d74e6d..c4bb34ec27 100644
--- a/doc/modules/ROOT/nav.adoc
+++ b/doc/modules/ROOT/nav.adoc
@@ -34,6 +34,7 @@
** xref:debugging/logging.adoc[Logging]
** xref:debugging/macroexpansion.adoc[Macroexpansion]
** xref:debugging/profiling.adoc[Profiling]
+** xref:debugging/tap.adoc[Tap Viewer]
** xref:debugging/tracing.adoc[Tracing]
* Configuration
** xref:config/basic_config.adoc[Basic Configuration]
diff --git a/doc/modules/ROOT/pages/debugging/tap.adoc
b/doc/modules/ROOT/pages/debugging/tap.adoc
new file mode 100644
index 0000000000..3830e87935
--- /dev/null
+++ b/doc/modules/ROOT/pages/debugging/tap.adoc
@@ -0,0 +1,61 @@
+= Tap Viewer
+:experimental:
+
+Clojure's `tap>` is a lightweight way to send a value somewhere without
+littering your code with prints or disturbing the value flow. CIDER can collect
+those values for you: kbd:[M-x] `cider-tap` opens a `+*cider-tap*+` buffer that
+streams every value sent to `tap>`.
+
+Any `+(tap> some-value)+` in your code shows up in that buffer as it happens,
as
+does anything you tap from the xref:inspector.adoc[inspector]. The buffer
follows
+the tail, so the newest value is always in view.
+
+NOTE: This requires a recent enough `cider-nrepl` (the one that ships the `tap`
+middleware). Without it the command won't have anything to subscribe to.
+
+== Using the buffer
+
+Inside the `+*cider-tap*+` buffer:
+
+|===
+| Keyboard shortcut | Command | Description
+
+| kbd:[RET]
+| `cider-tap-inspect-at-point`
+| Open the value on the current line in the inspector.
+
+| kbd:[n]
+| `cider-tap-next`
+| Move to the next tapped value.
+
+| kbd:[p]
+| `cider-tap-previous`
+| Move to the previous tapped value.
+
+| kbd:[c]
+| `cider-tap-clear`
+| Clear the buffer.
+
+| kbd:[q]
+| `quit-window`
+| Bury the buffer.
+|===
+
+Killing the buffer stops the streaming; reopening it with `cider-tap`
+re-subscribes (including after you reconnect to a different REPL).
+
+NOTE: ClojureScript taps stream into the buffer too, but they can't be
inspected
+with kbd:[RET] - the tapped value lives in the JavaScript runtime, so there's
no
+handle to send to the inspector.
+
+== Tapping a form
+
+You don't have to edit your source to tap a value. Two commands wrap the form
at
+point in a `tap>` for you, evaluating it and sending the result to any tap
+targets (including the viewer above):
+
+* `cider-tap-last-sexp` taps the result of the last sexp.
+* `cider-tap-sexp-at-point` taps the sexp around point.
+
+The original value is returned unchanged, so these are safe to drop into a
larger
+expression.
diff --git a/doc/modules/ROOT/pages/testing/running_tests.adoc
b/doc/modules/ROOT/pages/testing/running_tests.adoc
index 69f1d72bc6..429732b59d 100644
--- a/doc/modules/ROOT/pages/testing/running_tests.adoc
+++ b/doc/modules/ROOT/pages/testing/running_tests.adoc
@@ -86,7 +86,20 @@ the namespace inference logic as for kbd:[C-u C-c C-t C-n]
Finally, you can execute the specific test at the point using
kbd:[C-c C-t t] or kbd:[C-c C-t C-t]. It will also work for implementation
functions,
-by searching for a matching test namespace with a matching deftest name.
+by searching for a matching test namespace with a matching deftest name.
+
+== Running ClojureScript Tests
+
+The regular test commands work against a ClojureScript REPL too: when the
+active REPL is a ClojureScript one, `cider-test-run-ns-tests` and friends run
+your `cljs.test` tests instead of refusing them. In a `.cljc` file the commands
+dispatch to both the Clojure and the ClojureScript REPL, so you can exercise
the
+same tests on both platforms at once.
+
+Asynchronous ClojureScript tests (those using `cljs.test/async`) are supported.
+This requires a recent enough `cider-nrepl`; with an older middleware the
+ClojureScript test ops aren't available and the commands fall back to reporting
+that they're unsupported.
== Configuration
