A simple library that turns examples in your README.md
file into tests and runs them!
This project follows the version scheme MAJOR.MINOR.COMMITS where MAJOR and MINOR provide some relative indication of the size of the change, but do not follow semantic versioning. In general, all changes endeavor to be non-breaking (by moving to new names rather than by breaking existing names). COMMITS is an ever-increasing counter of commits since the beginning of this repository.
Latest stable release: 1.0.3
Add an alias to your ~/.clojure/deps.edn
file:
:readme {seancorfield/readme {:mvn/version "1.0.3"}}
Then the most basic usage is:
clojure -A:readme -m seancorfield.readme
This turns README.md
's examples into tests in src/readme.clj
, loads and runs them, and then deletes that generated file (line numbers in failures should match line numbers in your original README.md
file).
You can optionally provide a different file path for the readme and for the generated file:
clojure -A:readme -m seancorfield.readme test/seancorfield/readme_example.md src/generated_test.clj
If your README.md
file contains code blocks of the form:
```clojure
some expression
=> result
```
This will generate tests of the form:
(deftest readme-N
(is (= result (do some expression))))
If there is no =>
then the Clojure code blocks will be added to the generated test namespace as-is with no direct test. This allows setup code to be shown in the README.md
file, followed by specific tests.
Each clojure
code block should be a standalone test. If there are multiple expressions in the code block before =>
they will be wrapped in a do
. There must be only one expression after =>
.
Build a deployable jar of this library:
$ clojure -A:jar
Install it locally:
$ clojure -A:install
Deploy it to Clojars -- needs CLOJARS_USERNAME
and CLOJARS_PASSWORD
environment variables:
$ clojure -A:deploy
Copyright © 2020 Sean Corfield, all rights reserved.
Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.
Can you improve this documentation?Edit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close