|
4 weeks ago | |
---|---|---|
bin | 4 weeks ago | |
resources | 1 month ago | |
src/clojure/itl | 4 weeks ago | |
tests | 1 month ago | |
.gitignore | 4 weeks ago | |
LICENSE | 1 year ago | |
README.md | 4 weeks ago | |
project.clj | 4 weeks ago | |
publish | 4 months ago |
Integration Test Library
An experiment in writing executable documentation in Clojure.
Inspired by the SLIM Test System, it uses a Markdown parser to transform documents into an AST which can be executed by regular Clojure functions. Since we are not using classes and methods, but instead just functions, we couldn’t port the SLIM protocol and write all our tests in FitNesse. This flexibility also allows us to deviate a bit from the norms enforced by thinking of test tables as instances of a class.
This project is self-testing. We run this README file as part of every build.
I have tested the entire build process using JDK 11
This project’s version of Clojure requires at least Java 8.
You’ll also need to install Leiningen
The easiest thing to do is run ./prepare-release
to run all the project tests,
document generation, and linting. This is the best way to make sure your changes
work fine.
Other things you can do:
lein test
runs the itl tests printing full outputitl.core/run
.
There is sample code at the bottom of itl.core
You can download the source code for itl from its Project Page
Coming soon.
This library tests itself! You can run: lein cli README.md
, which
should execute this document. If you use lein cli -- -h
you’ll see
some options you can use.
!!! abstract “global:itl test suite”
These are all the different tests for itl itself.
File | Result | Pass | Fail | Exception |
---|---|---|---|---|
tables.md | tables.html | 18 | 0 | 0 |
tags.md | tags.html | 0 | 0 | 0 |
[All ITL Tests (execute-pages: indir=tests, outdir=docs)]
Check out the itl.example
namespace as well as bin/test-all
for how
the documentation for this project was executed.
You’ll notice this file is pretty nice looking! That’s because we
used a nice simple CSS file. The default is in
resources/itl-md.css
You can specify your own CSS by passing the --css
flag to itl.cli
.
See source code and test results for more details on which tables you can put into your documents and what they do.
You can tag a section of a document. Then, if you run itl.cli
with one
or more -t
or --tag
switches, followed by the name of the tag you
want to run, only the sections with the given tags, plus the global
tag, will be executed. You can see an example of how this is done in
source code
and
test results for tags.
0.4.0
, Generative tables (gentable
and generative-table
)
are deprecated.0.3.3
, AsciiDoc support is deprecated. This means no new features
will be added to the AsciiDoc portion of the library, and at some future
release it will be purged altogether.0.4.* to 1.*
0.3.* to 0.4.*
run
function in itl.core
has been removed. Use
one of the other options.CSS_FILE
environment variable has been replaced with the
--css
switch in itl.cli
-- you can use itl.markdown/with-css
on the REPL instead of using the environment variable.0.2.* to 0.3.*
The syntax for '<x'
variable interpolation has been removed completely.
Use {{x}}
instead, and don’t worry about manually resolving it using
generated-var
. column-table
does the resolution for you.
0.1.* to 0.2.*
--quiet
or -q
switch to itl.cli
execute example files
table used to take an outdir
, which was where
it both looked for the example md
files to parse as well as where it
writes its file called example-output.log
. Now, you would use an
indir
parameter to specify here md
files are found, an
outdir
parameter to specify where the html
files are written, and a
logfile
parameter for where the output from running the files should go.
If no logfile
is given, output will go to standard out. You must specify an
indir
and outdir
If you have a contribution to make, you are welcome to! Send an email to stephen@calmabiding.me and we can have a conversation about how you like to contribute!
Copyright © 2019 Stephen Starkey
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.