• Stars
    star
    166
  • Rank 220,331 (Top 5 %)
  • Language
    Elm
  • License
    BSD 3-Clause "New...
  • Created over 7 years ago
  • Updated 27 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

elm-verify-examples Build Status

Verify examples in your docs.

ℹ️ This was formerly known as elm-doc-test.

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

Install

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

Setup

$ 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.

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 -> Int
add =
    (+)

Multiline Examples

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

Imports

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"

-}

Intermediate Definitions

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. ⚠️ 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) -> List a -> List a

Types in Examples

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

Examples in markdown files

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
```

Verify Examples

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

$ elm-verify-examples

This is useful if you want to run your tests using different runner than elm-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 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.

Examples

You can run the examples using:

npm start

More Repositories

1

awesome-fp-js

😎 A curated list of awesome functional programming stuff in js
5,918
star
2

awesome-frp-js

A curated list of awesome functional reactive programming stuff in js
286
star
3

material-iterm

πŸ’» Light & dark material theme for iterm2
238
star
4

react-motion-drawer

Drawer built with react-motion
JavaScript
221
star
5

react-cond

Lisp-Style conditional rendering in react.
JavaScript
178
star
6

redux-elm-middleware

Elm middleware for redux
JavaScript
149
star
7

awesome-ama-answers

A curated list of awesome AMA answers
127
star
8

redux-io

FSA-compliant io monad middleware for redux
JavaScript
66
star
9

compose-function

Function composition
JavaScript
57
star
10

redux-future

FSA-compliant future monad middleware for redux
JavaScript
53
star
11

.dotfiles

🏑
Vim Script
50
star
12

babel-plugin-array-includes

Replaces `arr.includes(val)' with `arr.indexOf(val) >= 0`.
JavaScript
44
star
13

react-mini

Create minimalistic react components
JavaScript
37
star
14

elm-verify

Elm
35
star
15

redux-saga-test

Helper for testing redux-saga
JavaScript
27
star
16

gulp-param

Add params to your tasks
JavaScript
26
star
17

elmi-to-json

Haskell
25
star
18

redux-either

FSA-compliant either monad middleware for redux
JavaScript
23
star
19

react-form-hoc

Higher order component for react forms
JavaScript
22
star
20

gh-contributors-table

πŸ™‡ Say "arigatō" to your contributors
JavaScript
21
star
21

recompose-examples

WIP Examples with recompose
JavaScript
20
star
22

mergesort

O(n log n)
JavaScript
20
star
23

underscore.string.fp

This is a wrapper for underscore.string to use it as a FP-library or with Ramda/lodash-fp
JavaScript
20
star
24

react-material-card

A material design card for react
JavaScript
18
star
25

elm-online

Subscribe to online/offline events πŸ“Ά
Elm
12
star
26

haskell-simple-dsl-examples

Simple examples on how to implement a DSL in Haskell.
Haskell
11
star
27

tasty-test-reporter

An ingredient for tasty that prints a summary and outputs junit xml that works with jenkins.
Haskell
11
star
28

elm-interface-to-json

Haskell
9
star
29

inquander

Inquirer for commander. If no arguments and options are passed to your commander app, it runs inquirer.
JavaScript
8
star
30

pm2-interactive-ui

πŸš₯ interactive cli for pm2
JavaScript
7
star
31

partition-all

Clojure's partition-all in js
JavaScript
7
star
32

extjs5-the-missing-components

This package adds missing components to extjs5.
JavaScript
7
star
33

nix-test-runner

Test runner for nix expressions
Rust
6
star
34

react-mini-this

React components as pure functions with function bind syntax
JavaScript
6
star
35

debug-view

Elm
6
star
36

arityN

Wraps a function with a function of a sertain arity.
JavaScript
5
star
37

grulp

:neckbeard: Never have to worry again if the project is using grunt or gulp. Just use grulp
JavaScript
5
star
38

elm-reflection

Haskell
5
star
39

editable

Elm
5
star
40

radioactive-react-example

Simple example with react and radioactive
JavaScript
5
star
41

create-constants

Create constants
JavaScript
5
star
42

bind-it

DEPRECATED: use stoeffel/bind-first and stoeffel/bind-last
JavaScript
4
star
43

ext.promise

promise for extjs
JavaScript
4
star
44

valid-sift

Check if it's a valid sift filter
JavaScript
3
star
45

compare.js

Comparator functions for you favorite sort-algo
JavaScript
3
star
46

reflux-hoc

Higher-order Component for reflux
JavaScript
3
star
47

if-change-then-notify

Notify me if a certain file changes
JavaScript
3
star
48

set-extra

Elm
3
star
49

pretty-diff

Pretty printing a diff of two values
Haskell
3
star
50

Tetris

A lill tetris developed using raphaeljs
JavaScript
3
star
51

elm-game-of-life

Game of Life in Elm
Elm
3
star
52

expand-object-keys

Expand dotty object keys to objects
JavaScript
3
star
53

underscore.string.cli

String manipulations on the commandline
JavaScript
2
star
54

reassemble-string

🏭 Reassemble your strings
JavaScript
2
star
55

.dots

🏑
Shell
2
star
56

css-longhand-cli

CLI for css-longhand
JavaScript
2
star
57

react-compose

Compose react components
2
star
58

burnhub

Burndown chart for github issues
JavaScript
2
star
59

guard-function

πŸ’‚β€β™‚οΈ You shall not pass!
JavaScript
2
star
60

retrieve-arguments

Retrieves the argumentnames of a function
JavaScript
2
star
61

gulp-macros

sweetjs macros for gulp
JavaScript
2
star
62

abclou

PureScript
2
star
63

advent-of-code-2016

my solutions http://adventofcode.com/
Haskell
2
star
64

tmux-tui

TUI to manage tmux sessions 🚧
Haskell
2
star
65

SEPS-GRP1

JavaScript
2
star
66

elm-check-updates

JavaScript
1
star
67

nur-packages

Nix
1
star
68

format-string

Format a string, using values from an object.
JavaScript
1
star
69

haskell-simple-quasi-quoter

code for small demo on how to use QuasiQuoter
Haskell
1
star
70

Aoc2021

Haskell
1
star
71

use-module

angularjs-style DI for nodemodules
JavaScript
1
star
72

resetable

Elm
1
star
73

reverse-arguments

Reverse the arguments passed to a function.
JavaScript
1
star
74

elm-playground

Elm
1
star
75

bn.js.logo

1
star
76

hosts_alias

my first ruby gem
Ruby
1
star
77

i18next-playground

JavaScript
1
star
78

stoeffel.github.io

🏑
CSS
1
star
79

sencha-leaflet

Leaflet component for sencha touch 2
JavaScript
1
star
80

underscore.hasInside

Recursivly searching for a property by name
JavaScript
1
star
81

lan-camp

CSS
1
star
82

rest-param

πŸ’¬ Returns a function with an appended rest param
JavaScript
1
star
83

array-comprehensions

Functional array comprehension
JavaScript
1
star
84

fparser-cli

a cli for bylexus's fparser
JavaScript
1
star