# node-test-runner [![Version](https://img.shields.io/npm/v/elm-test.svg)](https://www.npmjs.com/package/elm-test)

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.

[elm-explorations/test]: https://package.elm-lang.org/packages/elm-explorations/test/latest

## Versions

You need to keep the versions of these three things in sync:

- This CLI tool.
- The Elm compiler.
- The [elm-explorations/test] package.

When it comes to the first two it’s easy: Use the same version for both. If you use Elm 0.19.2, use version 0.19.2 of this CLI tool as well. Note that the npm packages for both `elm` and `elm-test` might have suffixes such as `-0` and `-1` etc. It’s totally OK to use `elm@0.19.2-0` with `elm-test@0.19.2-1`! The suffixes don’t need to match. The suffixes are all about bug fixes or features in the respective npm packages, while the base version says which compiler version we’re working with.

When it comes to [elm-explorations/test]: Use at least version 2.0.0 with elm-test 0.19.2. If you’re on 0.19.1, see the following table:

| elm-explorations/test | elm-test CLI         |
| --------------------- | -------------------- |
| >= 2.0.0              | >= 0.19.1-revision10 |
| <= 1.2.2              | <= 0.19.1-revision9  |

(For 0.19.1, the suffix used was for example `-revision9` instead of just `-9`. This was changed in 0.19.2 to match the `elm` npm package.)

> **Unfortunate behavior of 0.19.1-revision9 and older**
>
> - `elm-test init` always installs the latest [elm-explorations/test]. This means that if you run `elm-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". (This is also why there is a version called "0.19.2-0" but no "0.19.2".)

## 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](https://github.com/isaacs/node-glob#glob-primer):

    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:

1.  In the `tests/` folder.

    This is the default and requires no extra setup.

2.  In any source directory (`"source-directories"` in `elm.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 have `src/LoginForm.elm` and `src/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 your `elm.json` are available in these files.

3.  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 your `elm.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"` in `elm.json`.

### Locating tests within files

For elm-test to find tests in your files you need to:

1. Create top-level values of the type [Test](https://package.elm-lang.org/packages/elm-explorations/test/latest/Test#Test). You can name the values anything – the only thing that matters is that their type is `Test`.
2. Expose them.

Example:

```elm
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](https://package.elm-lang.org/packages/elm-explorations/test/latest/Test#describe). Some prefer to expose several `Test` values.

**Also check out the [elm-explorations/test quick-start](https://github.com/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](https://github.com/chalk/chalk#chalksupportscolor) 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](#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`](https://docs.travis-ci.com/user/languages/elm/):

```yml
language: elm
elm:
  - 0.19.2
```

Here is an example [`travis.yml`](https://github.com/rtfeldman/elm-css/blob/master/.travis.yml) configuration file for running tests in CI.