Fix readme, hide clojure-test helper vars

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+### Fixed
+
+- Added the `lazytest.core` aliases to the readme.
+- Added a note about the experimental to the readme.
+- Hide some of the helper functions from the docs.
+
 ## 1.1.0
 
 Released `2024-10-09`.

README.md

@@ -11,7 +11,7 @@ Add it to your deps.edn or project.clj:
 
 ```clojure
 {:aliases
- {:test {:extra-deps {io.github.noahtheduke/lazytest {:mvn/version "1.0.0"}}
+ {:test {:extra-deps {io.github.noahtheduke/lazytest {:mvn/version "1.1.0"}}
          :extra-paths ["test"]
          :main-opts ["-m" "lazytest.main"]}}}
 ```
@@ -131,6 +131,31 @@ The `expect` macro is like `assert` but carries more information about the failu
 
 If an `it` runs to completion without throwing an exception, the test case is considered to have passed.
 
+### Aliases
+
+To help write meaningful tests, a couple aliases have been defined for those who prefer different vocabulary:
+
+* `context` for `describe`
+* `specify` for `it`
+* `should` for `expect`
+
+These can be used interchangeably:
+
+```clojure
+(defdescribe +-test
+  (context "with integers"
+    (specify "that sums work"
+      (should (= 7 (+ 3 4)) "follows basic math")
+      (expect (not= 7 (1 + 1)))))
+```
+
+There are a number of experimental namespaces that define other aliases, with distinct behavior, if the base set of vars don't fit your needs:
+
+* [[lazytest.experimental.interfaces.clojure-test]] to mimic `clojure.test`.
+* [[lazytest.experimental.interfaces.midje]] to mimic [Midje](https://github.com/marick/midje).
+* [[lazytest.experimental.interfaces.qunit]] to mimic [QUnit](https://qunitjs.com/).
+* [[lazytest.experimental.interfaces.xunit]] to mimic a standard [xUnit](https://en.wikipedia.org/wiki/XUnit) framework.
+
 ### Var Metadata
 
 In addition to finding the tests defined with `defdescribe`, Lazytest also checks all vars for `:test` metadata. If the `:test` metadata is a function, a test case, or a test suite, it's treated as a top-level `defdescribe` for the associated var and executed just like other tests. `:test` functions are given the doc string ``"`:test` metadata"``.

src/clojure/lazytest/experimental/interfaces/clojure_test.clj

@@ -1,9 +1,9 @@
 (ns lazytest.experimental.interfaces.clojure-test 
   "EXPERIMENTAL. COULD BE CHANGED AT ANY TIME. Please share usage reports at https://github.com/noahtheduke/lazytest/issues
 
-  An adaption of the built-in `clojure.test` framework. [[testing]] works the same way as [[clojure.test/testing]], so it does not support metadata selection like [[lazytest.core/describe]].
+  An adaption of the built-in `clojure.test` framework. [[testing]] works the same way as `clojure.test/testing`, so it does not support metadata selection like [[lazytest.core/describe]].
 
-  Supported [[clojure.test]] vars:
+  Supported `clojure.test` vars:
   * [[deftest]]
   * [[testing]]
   * [[is]]
@@ -30,28 +30,28 @@
     [lazytest.core :refer [expect defdescribe it]]
     [clojure.template :as temp]))
 
-(def ^:dynamic *testing-strs*
-  "Adapted from [[clojure.test/*testing-contexts*]]."
+(def ^:dynamic ^:no-doc *testing-strs*
+  "Adapted from `clojure.test/*testing-contexts*`."
   (list))
 
 (defmacro testing
-  "Adapted from [[clojure.test/testing]]."
+  "Adapted from `clojure.test/testing`."
   [doc & body]
   `(binding [*testing-strs* (cons ~doc *testing-strs*)]
      ~@body))
 
-(defn testing-str []
+(defn ^:no-doc testing-str []
   (when (seq *testing-strs*)
     (str/join " " (reverse *testing-strs*))))
 
 (defmacro is
-  "Adapted from [[clojure.test/is]]."
+  "Adapted from `clojure.test/is`."
   ([form] `(expect ~form (testing-str)))
   ([form msg]
    `(expect ~form (str (testing-str) "\n" ~msg))))
 
 (defmacro are
-  "Adapted from [[clojure.test/are]]."
+  "Adapted from `clojure.test/are`."
   [argv expr & args]
   (if (or
        (and (empty? argv) (empty? args))
@@ -64,7 +64,7 @@
     (throw (IllegalArgumentException. "The number of args doesn't match are's argv."))))
 
 (defmacro deftest
-  "Adapted from [[clojure.test/deftest]]."
+  "Adapted from `clojure.test/deftest`."
   [test-name & body]
   (assert (symbol? test-name) "test-name must be a symbol")
   (with-meta