Repository files navigation

Verify examples in your docs.

ℹ️ This was formerly known aselm-doc-test.

⚠️ This is not a replacement for tests, this tool should be used for improving your documentation.

$ npm i elm-test -g$ npm i elm-verify-examples -g$ elm-test init

There is no need for any configuration. elm-verify-examples will run on all elm files in the specifiedsource-directories (elm.json). It's possible to create a config file if you want to run it on only a subset of files or on additional markdown files.

$ touch tests/elm-verify-examples.json

elm-verify-examples.json contains information on which files contain verified examples and where to find them.

{"tests": ["Mock","Mock.Foo.Bar.Moo","./README.md"]}

Alternatively you can run elm-verify-examples on all elm files in your source directories:

{"tests":"all"}

or

{"tests": ["all","Some.md"]}

It's recommended to add./tests/VerifyExamples to your.gitignore.

If you are building apackage, you can pass the string"exposed" instead of an explicit list of modules,this will cause all the documented modules in your package to be verified. This makes it easier to keep these insync.

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.concat    --> "321"-}rev:Lista->Listarev=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 =        remainderBy 2 n == 0    List.Extra.filterNot isEven [1,2,3,4] --> [1,3]-}filterNot: (a->Bool)->Lista->Lista

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 )doublea=( 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->StringcustomTypeAlias{ 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 yourelm-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:```elmimport DocumentedDocumented.two --> 2```

elm-verify-examples converts your verify-examples into elm-tests, and optionally runs them usingelm-test. To only generate the test files intests/VerifyExamples/:

$ elm-verify-examples

This is useful if you want to run your tests using different runner thanelm-test, e.g.elm-coverage. If you also want to run the generated tests:

$ elm-verify-examples --run-tests

Note that this way the test files will be removed after they are ran.

By default, this command looks for the config file attests/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 frommy/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 intests/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.