Verify examples in your docs.
ℹ️ This was formerly known as elm-doc-test
.
$ npm i elm-test -g
$ npm i elm-verify-examples -g
$ elm-test init
$ touch tests/elm-verify-examples.json
elm-verify-examples.json
contains information on which files contain verified examples and where to find them.
{
"root": "../src",
"tests": [
"Mock",
"Mock.Foo.Bar.Moo",
"./README.md"
]
}
It's recommended to add ./tests/VerifyExamples
to your .gitignore
.
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 -> Int
add =
(+)
You can write examples on multiple lines.
{-| reverses the list
rev
[ 41
, 1
]
--> [ 1
--> , 41
--> ]
rev [1, 2, 3]
|> List.map toString
|> String.concat
--> "321"
-}
rev : List a -> List a
rev =
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"
-}
You can use intermediate definitions in your example. :information: Unused functions don't get added to the test. This is useful if you wanna add incomplete examples to your docs. :warning: Intermediate definitions need a type signature!
{-|
isEven : Int -> Bool
isEven n =
n % 2 == 0
List.Extra.filterNot isEven [1,2,3,4] --> [1,3]
-}
filterNot : (a -> Bool) -> List a -> List a
You can define union types and type aliases in your examples.
{-| With a union type in the example.
type Animal
= Dog
| Cat
double Dog
--> (Dog, Dog)
-}
double : a -> (a, a)
double a =
(a, a)
{-| With a type alias in the example.
customTypeAlias defaultUser "?"
--> "?Luke"
type alias User =
{ id: Int -- ID
, name: String
}
defaultUser : User
defaultUser =
{ id = 1
, name = "Luke"
}
customTypeAlias defaultUser "_"
--> "_Luke"
-}
customTypeAlias : { a | name : String } -> String -> String
customTypeAlias { name } prefix =
prefix ++ name
You can also verify code example in markdown files (such as your README). To do so, add the file's path to your elm-verify-examples.json
file and write your example using the sames rules as above (no need for 4-space indentation here).
This is my README!
It explains how the `Documented` module works:
```elm
import Documented
Documented.two --> 2
```
elm-verify-examples
converts your verify-examples into elm-tests, and runs them using elm-test
.
$ elm-verify-examples
By default, this command looks for the config file at tests/elm-verify-examples.json
. If you want it to load a specific config file use the --config
argument (e.g. elm-verify-examples --config my/custom/path/elm-verify-examples.json
will read the config from my/custom/path/elm-verify-examples.json
).
You can run elm-verify-examples for one or more modules explicitly. They don't have to be specified in tests/elm-verify-examples.json
.
$ elm-verify-examples ./src/Foo.elm ./src/Foo/Bar.elm
You can pass a custom path to elm-test if necessary.
$ elm-verify-examples --elm-test=./node_modules/.bin/elm-test
$ # or add it to your elm-verify-examples.json `elmTest: "../node....`
$ # you can also pass arguments to elm-test with --elm-test-args
It will use the elm-test installed with this package.
You can run the examples using:
npm start