karma-elm-test v0.0.4
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.