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: 10 months ago
JSON representation
doctest runner against Elm-lang source files
- Host: GitHub
- URL: https://github.com/tshm/elm-doctest
- Owner: tshm
- License: mit
- Created: 2016-05-05T17:59:52.000Z (almost 10 years ago)
- Default Branch: main
- Last Pushed: 2024-03-02T11:24:41.000Z (almost 2 years ago)
- Last Synced: 2025-04-09T16:50:08.843Z (10 months ago)
- Topics: doctest, elm, test-runner, unittest
- Language: Elm
- Size: 403 KB
- Stars: 16
- Watchers: 2
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/tshm/elm-doctest/actions/workflows/node.js.yml)
[](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/navigation@1.0.0`
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