Awesome
node-test-runner
Runs elm-explorations/test suites in Node.js.
When people say “elm-test” they usually refer to either:
- This CLI tool for running tests.
- elm-explorations/test – an Elm package for defining tests that this CLI tool can run.
Versions
Not all versions of elm-explorations/test and this CLI tool work together!
elm-explorations/test | elm-test CLI |
---|---|
>= 2.0.0 | >= 0.19.1-revision10 |
<= 1.2.2 | <= 0.19.1-revision9 |
Unfortunate behavior of 0.19.1-revision9 and older
elm-test init
always installs the latest elm-explorations/test. This means that if you runelm-test init
on version 0.19.1-revision9 or older, you will get elm-explorations/test 2.0.0 or later, which don’t work 100 % together (see the next point).- elm-test 0.19.1-revision9 or older do not validate that elm-explorations/test in your elm.json has a compatible version. If you upgrade to elm-explorations/test 2.0.0 or later but forget to upgrade the elm-test CLI, most things will still work, but test distribution diagrams (new in elm-explorations/test 2.0.0) won’t show up. So if you use
Test.fuzzWith
and wonder why distribution diagrams never show up – check your elm-test CLI version!- There exists an elm-test CLI version called just "0.19.1". It should have been called "0.19.1-revision1", but unfortunately isn’t. Don’t make the mistake thinking it’s the latest version! You always want "0.19.1-revisionX".
Installation
npm install --save-dev elm-test
Quick start
Install elm-explorations/test and create tests/Example.elm
:
npx elm-test init
Run tests in the tests/
folder:
npx elm-test
Run tests in one particular file:
npx elm-test tests/Example.elm
Run tests in files matching a glob:
npx elm-test "src/**/*Tests.elm"
Note: The double quotes are important! Without quotes, your shell might expand the globs for you. With quotes, elm-test expands the globs. This way the watcher can pick up new tests matching the globs, and it will work cross-platform.
Run in watch mode:
npx elm-test --watch
Where to put tests
Locating files containing tests
There are 3 places you could put your tests:
-
In the
tests/
folder.This is the default and requires no extra setup.
-
In any source directory (
"source-directories"
inelm.json
for applications,src/
for packages) as separate files.A convention is to put test files next to the file it tests with a
Tests
suffix. For example, you could havesrc/LoginForm.elm
andsrc/LoginFormTests.elm
.This requires telling elm-test which folders/files to run. Examples:
npx elm-test "src/**/*Tests.elm" npx elm-test test/frontend/elm
You might also need to configure your editor to understand that the
"test-dependencies"
in yourelm.json
are available in these files. -
In already existing source files.
This allows testing internal functions without exposing them. (Be aware that testing implementation details can sometimes be counter-productive.)
This requires moving everything in
"test-dependencies"
in yourelm.json
into regular"dependencies"
, so your project still compiles. This also helps your editor. Note that this approach isn’t suitable for packages, since you don’t want your package to unnecessarily depend on elm-explorations/test.
You can mix all three variants if you want:
npx elm-test tests "src/**/*Tests.elm" app
In this example,
"src"
and"app"
need to be in"source-directories"
inelm.json
.
Locating tests within files
For elm-test to find tests in your files you need to:
- Create top-level values of the type Test. You can name the values anything – the only thing that matters is that their type is
Test
. - Expose them.
Example:
module LoginForm exposing (alreadyLoggedInTests, tests)
import Test exposing (Test)
tests : Test
tests =
-- ...
alreadyLoggedInTests : Test
alreadyLoggedInTests =
-- ...
Some prefer to expose a single Test
value and group everything using describe. Some prefer to expose several Test
values.
Also check out the elm-explorations/test quick-start guide!
Command Line Arguments
These are the most common commands and flags. Run elm-test --help
for an exhaustive list.
Note: Throughout this section, the npx
prefix is omitted for brevity.
install
Like elm install
, except elm-test will install to "test-dependencies"
in your elm.json
instead of to "dependencies"
.
elm-test install elm/regex
init
Runs elm-test install elm-explorations/test
and then creates a tests/Example.elm
example test to get you started.
elm-test init
requires an elm.json
file up the directory tree, so you will need to run elm init
first if you don’t already have one.
After initializing elm-test in your project, try out the example by running elm-test
with no arguments.
elm init
elm-test init
elm-test
--watch
Start the runner in watch mode. Your tests will automatically rerun whenever your project changes.
elm-test --watch
--seed
Run with a specific fuzzer seed, rather than a randomly generated seed. This allows reproducing a failing fuzz-test. The command needed to reproduce (including the --seed
flag) is printed after each test run. Copy, paste and run it!
elm-test --seed 336948560956134
--fuzz
Define how many times each fuzz-test should run. Defaults to 100
.
elm-test --fuzz 500
--report
Specify which format to use for reporting test results. Valid options are:
console
(default): pretty, human readable formatted output.json
: newline-delimited json with an object for each event.junit
: junit-compatible xml.
elm-test --report json
--no-color
Disable colored console output.
Colors are also disabled when you pipe the output of elm-test
to another program. You can use --color
to force the colors back.
Alternatively, you can set the environment variable FORCE_COLOR
to 0
to disable colors, or to any other value to force them.
See chalk.supportsColor for more information.
--compiler
If elm
is not in your $PATH
when elm-test runs, or the Elm executable is called something other than elm
, you can use this flag to point to your installation.
elm-test --compiler /path/to/elm
To run a tool installed locally using npm
you can use npx
:
npx elm-test
npx
adds the local node_modules/.bin/
folder to $PATH
when it executes the command passed to it. This means that if you have installed elm
locally, elm-test
will automatically find that local installation.
As mentioned in Installation we recommend installing elm-test locally in every project. This ensures all contributors and CI use the same version, to avoid nasty “works on my computer” issues.
Travis CI
If you want to run your tests on Travis CI, here's a good starter .travis.yml
:
language: elm
elm:
- 0.19.1
Here is an example travis.yml
configuration file for running tests in CI.