karma-elm-test
A Karma plugin for elm to run tests written using elm-test to provided CI friendly, multi-browser unit testing for Elm.
The elm functionality for hosting the test code in a browser is adapted from elm html-test-runner.
Prerequisites
This plugin currently requires elm to have been installed on the system and the elm-make & elm-packages to be on the host system's path. If you do not have these then they can be installed via npm:
npm install -g elm
These instructions also assume Karma CLI is installed (if not all the karma commands have to reference the local version under 'node_modules' in your project). It can be installed using:
npm install -g karma-cli
NOTE: ensure you install karma-cli globally, NOT karma itself, doing this will cause problems!
Karma needs to be installed in your project as a dev dependency via npm:
npm install --save-dev karma
Installation
This can be installed into your projects dev dependencies via npm with
npm install --save-dev karma-elm-test
Configuration
The current version requires pretty verbose config, something I hope to improve in upcoming versions.
I created a fork of elm-css converted to run its tests in karma using this plugin here: https://github.com/stephenhand/elm-css the karma.conf.js included here is a good reference example of how to configure the plugin.
Firstly, the plugin needs 'elm-test' to be registered as a framework AND 'elm' to be registered as a preprocessor, so something like:
preprocessors: {
"./src/**/*.elm": ['elm'],
"./tests/**/*.elm": ['elm']
},
frameworks: ["elm-test"],
Second, all your elm files, production and test need to be specified under 'files':
files: ["./src/**/*.elm", "./tests/**/*.elm"],
Finally, a root 'client' item needs adding with an 'elm-test' item under that, which needs to contain the following:
A 'test-source-directories' array containing the paths to your elm test source. These are relative to the project root and are specified in the same way as source directory paths in your elm-pacages.json.
"test-source-directories" : [
"./tests"
]
A 'suites' array containing a list of all the modules containing your tests and the fully qualified function calls required to execute them. For example:
suites:[
{
module:"Compile",
tests:["Compile.colorWarnings","Compile.unstyledDiv","Compile.dreamwriter","Compile.compileTest"]
},
{
module:"Properties",
tests:["Properties.all"]
},
{
module:"Selectors",
tests:["Selectors.nonElements","Selectors.elements"]
}
]
The above would specify 3 different modules with tests to run. The first module, 'Compile' has 4 functions exposed that run tests, 'colorWarnings', 'unstyledDiv', 'dreamwriter', 'compileTest'.
Specifying all the modules & entry functions in config is obviously less than ideal and I hope to incorporate an auto discovery mechanism in the near future to eliminate the need for this.
Known issues & limitations
-
Doesn't correctly report skipped tests
-
Only supports projects where a single elm-packages.json for the code under test is in the root directory, more flexibility is required.
Roadmap
The following things are on my list for doing ASAP (in approximate priority order:
-
Fix above outstanding issues
-
Refactor project to depend on a fork of html-test-runner for its Elm browser code so it's easier to merge in changes going forward
-
Add unit tests (possibly 'dog fooding', running in karma via this plugin)
-
Add auto discovery of tests to cut down required config
-
Investigate ways of more elegantly / robustly compiling & running tests. Generating elm-packages.json and Bootstrap.elm files seems a bit kludgy (nasty unnecessary side effects!), being able do everything in memory would be ideal.
-
Try to make the project 'pure node' rather than shelling out to external programs (or have those programs contained within / auto deployed alongside the plugin) to make it easier to deploy in CI.