README

ELMER IS DEPRECATED

There will be no more updates to Elmer. It was fun while it lasted, but I'm pretty sure Elmer won't work with Elm 0.19.1 or later versions.

Instead, you should use elm-spec.

Elm-spec is a test framework for Elm that lets you describe the behavior of Elm programs, much like Elmer did. Unlike Elmer, elm-spec doesn't use kernel/native code so it has been published to the Elm package repository and should be more resilient to future changes in Elm.

Elmer

Elmer makes it easy to describe the behavior of Elm HTML applications. If you love TDD and you love Elm, then you'll probably appreciate Elmer.

For more on Elmer, see the documentation and the github repo.

This package allows you to install Elmer locally so you can use it to write tests for Elm 0.19 programs.

Getting Started

Because Elmer uses some native Javascript code to accomplish its magic, you cannot install Elmer through the elm package repository. Instead, follow these steps to TDD bliss ...

Install

First, you'll need to install

Elm (0.19.x)
the node test runner for elm-test (elm-test@elm0.19.0)
this package

I recommend installing these dependencies locally in your project directory so you can track versions carefully. Here's the command to install all these at once:

$ npm install --save-dev elm elm-test@elm0.19.0 elmer-test

Now install the elm test library:

$ npx elm install elm-explorations/test

Update the elm.json file

In your elm.json file, you'll need to manually add elmer to the test-dependencies section like so:

"test-dependencies": {
  "direct": {
    "elm-explorations/test": "1.1.0",
    "elm-explorations/elmer": "6.0.0"
  },
  "indirect": {}
}

Notice the indirect section under test-dependencies. Elmer itself has the following dependencies:

"dependencies": {
  "elm/browser": "1.0.0 <= v < 2.0.0",
  "elm/core": "1.0.0 <= v < 2.0.0",
  "elm/html": "1.0.0 <= v < 2.0.0",
  "elm/json": "1.0.0 <= v < 2.0.0",
  "elm/random": "1.0.0 <= v < 2.0.0",
  "elm/url": "1.0.0 <= v < 2.0.0",
  "elm-explorations/test": "1.0.0 <= v < 2.0.0"
},

If any of these dependencies are not already listed as direct or indirect dependencies of your app, you'll need to list these in the indirect section of your test-dependencies.

If you just try to run elm-test (see below) and you're missing any dependencies, the compiler will give you an error message. Take the missing dependencies it mentions and list them as indirect test dependencies.

Run

Now that everything's in place, you're ready to write tests with Elmer. In order to run those tests, you'll need to set the ELM_HOME environment variable to the home directory under the elmer-test install. If you've installed elmer-test locally, the directory should look like this:

<Project Home>/node_modules/elmer-test/home

I recommend adding a test script to your package.json that sets the environment variable for you. The following will work on a Mac running bash:

"scripts": {
  "test": "ELM_HOME=$(pwd)/node_modules/elmer-test/home elm-test"
}

Note that ELM_HOME must be an absolute path (thus the $(pwd) in the test command).

Caveats

The elm command searches for test dependencies any time you invoke it (so, even if you aren't running tests). This means that you will need to set the ELM_HOME environment variable as described above, any time you invoke the elm command. For example, to build your app, you'll need to do something like:

$ ELM_HOME=$(pwd)/node_modules/elmer-test/home elm make src/Mail.elm

Releases

6.0.0

Removed Elmer.Http and the dependency on elm/http. Elmer.Http now lives in its own package so it can be updated independently.
Provided new APIs useful for creating extensions and custom matchers. See Elmer.Value, Elmer.Message, Elmer.Message.Failure,Elmer.Effects, and Elmer.Task

5.0.1

Support for calling a spy across multiple test states

5.0.0

Revised Elmer.Spy api to make it simpler and to allow the compiler to do type checking when injecting a spy or providing a fake implementation. This should provide better feedback when working with spies

4.0.0

Updated Elmer to work with Elm 0.19
Revised api for targeting Html elements to allow the compiler to provide better feedback

Development

To create a new elmer release:

$ npm run release <path to elmer>

Usage no npm install needed!