Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tshm/elm-doctest

doctest runner against Elm-lang source files
https://github.com/tshm/elm-doctest

doctest elm test-runner unittest

Last synced: about 2 months ago
JSON representation

doctest runner against Elm-lang source files

Awesome Lists containing this project

README

        

[![Build Status](https://github.com/tshm/elm-doctest/actions/workflows/node.js.yml/badge.svg)](https://github.com/tshm/elm-doctest/actions/workflows/node.js.yml)
[![npm version](https://badge.fury.io/js/elm-doctest.svg)](https://badge.fury.io/js/elm-doctest)

# elm-doctest

[doctest](https://en.wikipedia.org/wiki/Docstring)
runner against Elm-lang source files

## installation

```shell
npm install elm-doctest
```

It depends on `elm` and assumes that `elm-make` and `elm-repl` are available
either via systemwide installation or npm module installation.
Make sure `elm-make` succeeds with your elm source files.

## how does it work?

It utilizes `elm-repl` for expression evaluation and compare the values
against the expected value.
(It does not comapre stringified values like haskell doctest does via
GHCi outputs.)

It only evaluates the expressions that follows `-- >>>`
(i.e. Elm comment symbol followed by space and three LT chars
until end of the line)
and the expression on the next line after `-- `.

For example, if the comment states:

```Elm
-- >>> x =
-- >>> 1 + 2
--
-- >>> x * 2
-- 6
```

Then, elm-doctest asks elm-repl to evaluate the
actual code section in the source file and
effectively following expression:

```Elm
((1 + 2) * 2) == (6)
```

If value reported by `elm-repl` is `True` then test passes, fail otherwise.

## usage

```
Usage: elm-doctest [--watch] [--help] [--elm-path PATH]
[--pretest CMD] FILES...
run doctest against given Elm files

Available options:
-h,--help Show this help text
--pretest CMD Command to run before doc-test
--elm-path PATH Path to elm executable
-w,--watch Watch and run tests when target files get updated
```

## example

ModuleTobeTested.elm:

```Elm
module ModuleTobeTested exposing(..)

-- |
-- >>> add 3 5
-- 8
--
-- >>> removeZeros [0, 1, 2, 3, 0]
-- [1, 2, 3]
--
-- >>> greetingTo "World"
-- "Konnichiwa World"
--
add : Int -> Int -> Int
add x y = x + y

greetingTo : String -> String
greetingTo x = "Hello " ++ x

removeZeros : List Int -> List Int
removeZeros = List.filter (\x -> x /= 0)
```

evaluation `elm-doctest ModuleTobeTested.elm` outputs

```
Starting elm-doctest ...

processing: test/TestData/TestFail.elm
### Failure in test/TestData/TestFail.elm:10: expression
greetingTo "World"
expected: "Konnichiwa World"
but got: "Hello World"
Examples: 3 Failures: 1
```

## limitation

As it utilizes `elm-repl`, the script must be runnable
inside `elm-repl`.
For example, code which imports `elm-lang/[email protected]`
module cannot be tested.
Since the stdout is used to evaluate the test result,
avoid using `Debug.log`.

Also, make sure elm-make runs without error.
You can auto run elm-make by using `--pretest` command-line
option.

## license

MIT