Verify examples in your docs.
Install
$ npm i elm-test -g$ npm i elm-doc-test -g$ elm-test init
Setup
$ touch tests/elm-doc-test.json
elm-doc-test.json
contains information on which files contain verified examples and where to find them.
It's recommended to add ./tests/Doc
to your .gitignore
.
Writing Verified Examples
Verified examples look like normal code examples in doc-comments.
Code needs to be indented by 4 spaces.
You can specify the expected result of an expression, by adding a comment -->
(the >
is important) and an expected expression.
{-| returns the sum of two int. -- You can write the expected result on the next line, add 41 1 --> 42 -- or on the same line. add 3 3 --> 6 -}add : Int -> Int -> Intadd = (+) You can write examples on multiple lines. {-| reverses the list rev [ 41 , 1 ] --> [ 1 --> , 41 --> ] rev [1, 2, 3] |> List.map toString |> String.join "" --> "321"-}rev : List a -> List arev = List.reverse
You can specify imports, if you want to use a module or a special test util.
{-| import Dict myWeirdFunc (Dict.fromList [(1, "a"), (2, "b")]) [2, 1] --> "ba"-}
Running DocTests
elm-doc-test
only converts your doc-tests into elm-tests.
You have to use elm-test in order to run them.
$ elm-doc-test && elm-test tests/Doc/Main.elm
By default the first command creates the tests at tests/Doc/
. If you want to have them at a custom location use the --output
argument (e.g. elm-doc-test --output my/custom/path/
will create the tests at my/custom/path/Doc/
).
Also by default the first command looks for the config file at tests/elm-doc-test.json
. If you want it to load a specific config file use the --config
argument (e.g. elm-doc-test --config my/custom/path/elm-doc-test.json
will read the config from my/custom/path/elm-doc-test.json
).
Examples
You can run the examples using:
npm start