Repository files navigation

A library and Leiningen plugin to runcljs.test in many JS environments. ForBoot plugin, seeboot-cljs-test.

...and I would have gotten away with it, too, if it wasn't for you meddling kids.

The latest stable release:

{:plugins [[lein-doo"0.1.11"]]}

To use doo you need to use[org.clojure/clojurescript "0.0-3308"] or newer.

All arguments are optional provided there is a corresponding default under:dooinproject.clj:

lein doolein doo {js-env}lein doo {js-env} {build-id}lein doo {js-env} {build-id} {watch-mode}

• js-env can be anychrome,chrome-headless,firefox,firefox-headless,ie,safari,opera,slimer,phantom,node,rhino,nashorn,lumo, orplanck.In the future it is planned to supportv8,jscore, and others.
  • Note thatchrome-headless requireskarma-chrome-launcher >= 2.0.0 and Chrome >= 59
  • Note thatfirefox-headless requireskarma-firefox-launcher >= 1.1.0 and Firefox >= 56
• watch-mode (optional): eitherauto (default) oronce whichexits with 0 if the tests were successful and 1 if they failed.
• build-id is one of yourcljsbuild profiles. For exampletest from:

:cljsbuild  {:builds [{:id"test":source-paths ["src""test"]:compiler {:output-to"resources/public/js/testable.js":main your-project.runner:optimizations:none}}]}

Notice that:main is set to the namespaceyour-project.runnerwhere you define which test namespaces you want to run, using:

(nsyour-project.runner    (:require [doo.runner:refer-macros [doo-tests]]              [your-project.core-test]              [your-project.util-test]))(doo-tests 'your-project.core-test           'your-project.util-test)

doo.runner/doo-tests works just likecljs.test/run-tests but it places hooksaround the tests to know when to start them and finish them. Since itis a macro that will be calling said namespaces, you need to requirethem inyour-project.runner even if you don't call any of theirfunctions. You can also call(doo.runner/doo-all-tests) which wrapscljs.test/run-all-tests to run tests in all loaded namespaces.Notice thatdoo-tests needs to be called in the top level and can'tbe called inside a function (unless you explicitly call that functionin the top level).

Then you can run:

lein doo slimer test

which starts an ClojureScript autobuilder for thetest profile andrunsslimerjs on it when it's done.

You can also calldoo without abuild-id (as inlein doo phantom) aslong as you specify aDefault Build in yourproject.clj.

doo is packaged as a Boot task inboot-cljs-test.

To run a JavaScript file in your preferred runner you can directly calldoo.core/run-script from Clojure:

(require '[doo.core:as doo])(let [doo-opts {:paths {:karma"karma"}}      compiler-opts {:output-to"out/testable.js":optimizations:none}]  (doo/run-script:phantom compiler-opts doo-opts))

You can rundoo.core/run-script with the following arguments:

(run-script js-env compiler-opts)(run-script js-env compiler-opts opts)

where:

• js-env - any of:phantom,:slimer, :node,:rhino,:nashorn,:lumo,:planck,:chrome,:chrome-headless,:firefox,:firefox-headless,:ie,:safari, or:opera
• compiler-opts - the options passed to the ClojureScript when itcompiled the script that doo should run
• opts - a map that can contain::verbose - bool (default true) that determines if the scriptsoutput should be printed and returned (verbose true) or onlyreturned (verbose false).:debug - bool (default false) to log to standard-out internal eventsto aid debugging:paths - a map from runners (keywords) to string commands for bash.:exec-dir - a directory path (file) from where runner should beexecuted. Defaults to nil which resolves to the current dir

This is the hardest part anddoo doesn't do it for you (yet?). Rightnow if you want to runslimer,phantom,nodeornashorn that ships with the JDK 8,you need to install them so that these commands work on the command line:

phantomjs -vslimerjs -vnode -vjjs -hrhino -helplumo -hplanck -h

If you want to use a different command to run a certain runner, seePaths.

Remember that Rhino and Node don't come with a DOM so you can't call thewindow or document objects. They are meant to test functions andlogic, not rendering.

If you want to run both, uselein doo headless {build-id} {watch-mode}.

Do not install Slimer with homebrew unless you know what youare doing. There arereportsof it not working with ClojureScript when installed that way becauseof dated versions.

Note: Slimer does notcurrently throwerror exit codes when encountering an error, which makes themunsuitable for CI testing.

Some requirements:

• Minimum node version required:0.12
• :output-dir is needed whenever you are using:none.
• :target :nodejs is always needed.

:node-test {:source-paths ["src""test"]:compiler {:output-to"target/testable.js":output-dir"target":main example.runner:target:nodejs}}

Karmais a comprehensive JavaScript test runner. It usesplugins toextend functionality. We are interested in several "launcher" pluginswhich start a browser on command. You mightwant any of:

- karma-chrome-launcher- karma-firefox-launcher- karma-safari-launcher- karma-opera-launcher- karma-ie-launcher

Alternatively, if you don't wantdoo to launch the browsers for you,you can always launch them yourself and navigate tohttp://localhost:9876

We also need to properly reportcljs.test results inside Karma.We'llneed a "framework" plugin:

- karma-cljs-test

Karma and its plugins are installed withnpm. It isrecommendedthat you install Karma and it's plugins locally in the projects directorywithnpm install karma --save-dev. It is possible to install Karma andits plugins globally withnpm install -g karma, but this is not recommended.It is not possible to run mix local and global Karma and Karma plugins.

Karma provides aCLI toolto make running Karma simpler and to ease cross platform compatibility.doo uses the CLI tool as the default runner, if you don't install it you willneed to configure doo.

For local installation run:

npm install karma karma-cljs-test --save-dev

and install the Karma CLI tool globally with

npm install -g karma-cli

then install any of the launchers you'll use:

npm install karma-chrome-launcher karma-firefox-launcher --save-devnpm install karma-safari-launcher karma-opera-launcher --save-devnpm install karma-ie-launcher --save-dev

The--save-dev option informsnpm that you only need the packagesduring development and not when packaging artifacts.

The installation will generate anode-modules folder with all theinstalled modules. It is recommended to addnode-modules to your.gitignore.

If you are usinglein-npm, follow theirinstructions.

It's possible to generate Istanbul coverage reports for JS files produced from CLJS.

To make it work two things are required.

Install your karma coverage plugin.

npm install karma-coverage --save-dev

Add coverage seetings to yourproject.clj

:doo {:coverage {:packages [my-app.module]                 :reporter {:check {:global {:statements 100}}}}}

Packages section is essential, it enables coverage cofiguration and defines whichfiles would have coverage instrumentation.

By default HTML reporter is enabled which createscoverage folder with the reportand there are no coverage reqirements.

Anything under:reporter is passed ascoverageReporter config to Karma config.

SeeKarma coverage for more details.SeeReagent covered for a sample project configuration.

If you are using a local installation and/ornode_modules is not locatedat the project root, you need to telldoo about it. Add this to yourproject.clj:

:doo {:paths {:karma"path/to/node_modules/karma/bin/karma"}}:cljsbuild { your-builds }

and make sure that the filekarma/bin/karma exists insidenode_modules. If yourpackage.json andnode_modules folder are in thesame directory than yourproject.clj, then you should use:

:doo {:paths {:karma"./node_modules/karma/bin/karma"}}:cljsbuild { your-builds }

For more info on:paths see Paths.

Global installation will allow you touse karma in all of your projects. The problem is that it won't beexplicitly configured in your project that karma is used for testing,which makes it harder for new contributors to setup.

In some systems (e.g. Ubuntu) you might need to run all npm commandsas root:sudo npm install karma --save-dev

To avoid starting a new Slimer/Phantom on every run while usingauto, we can useSlimer/Phantom through Karma.

Install any of the launchers you'll use:

npm install karma-phantomjs-launcher --save-devnpm install karma-slimerjs-launcher --save-dev

and call

lein doo karma-phantom test autolein doo karma-slimer test auto

If you are usingonce, the regularphantom/slimer runners are recommended.

Note: karma-slimer sometimes fails to close the running Slimer instance,which you need to close manually.

After installingElectron install the launcher with

npm install karma-electron-launcher --save-dev

and call

lein doo electron test

Planck2.14.0 or later is required.

You might want to use a different version of node, or the globalversion of Karma, or any other binary to run your tests for a givenenvironment. You can configure that paths like so:

:doo {:paths {:node"user/local/bin/node12":karma"./frontend/node_modules/karma/bin/karma"}:cljsbuild { your-builds }

Paths can also be used to pass command line arguments to the runners:

:doo {:paths {:phantom"phantomjs --web-security=false":slimer"slimerjs --ignore-ssl-errors=true":karma"karma --port=9881 --no-colors":rhino"rhino -strict":node"node --trace-gc --trace-gc-verbose"}}

You might want to group runners and callthem from the command line. For example, while developing you mightonly be interested inchrome andfirefox, but you also want totest withsafari before doing a deploy:

:doo {:alias {:browsers [:chrome:firefox]:all [:browsers:safari]}}:cljsbuild { my-builds }

Then you can use:

lein doo browsers my-build# runs chrome and firefoxlein doo all my-build# runs chrome, firefox, and safari

As you can see, aliases can be recursively defined: watch for circulardependencies ordoo will bark.

The only built-in alias is:headless [:phantom :slimer].

To save you one command line argument,lein-doo lets you specify adefault build in yourproject.clj:

:doo {:build"some-build-id":paths { ... }:alias { ... }}:cljsbuild  {:builds [{:id"some-build-id":source-paths ["src""test"]:compiler {:output-to"out/testable.js":optimizations:none:main example.runner}}]}

You can supply arbitraryconfiguration options to Karma under the:karma {:config {}} key. For example, if you want to usekarma-junit-reporter, do this:

{:doo {:karma       {:config {"plugins" ["karma-junit-reporter"]"reporters" ["progress""junit"]"junitReporter" {"outputDir""test-results"}}}}}

The options are merged to Doo's Karma configuration. By default, array valuesare merged by appending. For example, in the example above, the value of"plugins" is appended to the list of plugins needed by Doo. Merging isimplemented withmeta-merge, so if you need more control, you canuse^:replace and^:prepend metadata.

To add custom Karma launchers (eg. as described in theChrome Karma Plugin) you can add the following config entries to yourproject.clj as shown in the example below:

The plugin in the:launchers map should match an installed Karma plugin andthe name should match a Karma launcher (possibly a custom one as shown in thefollowing example). If needed, add"customLaunchers" configurationunder the:config key.

You will then be able to runlein doo chrome-no-security from the comand line.

:doo {:karma      {:launchers {:chrome-no-security {:plugin"karma-chrome-launcher":name"Chrome_no_security"}}:config {"customLaunchers"                {"Chrome_no_security" {"base""Chrome""flags" ["--disable-web-security"]}}}}

To run ontravis there is a sample.travis.yml file in the example project:example/.travis.yml

(Currently only tested with PhantomJS.)

To run the tests for doo, you need to have installed rhino, phantomjs, slimer, chrome, node, and firefox. You will also need to runnpm install in thelibrary directory.

This project started as a repackaging ofcemerick/clojurescript.test,therefore much of the credit goes to Chas Emerick and contributors tothat project.

Copyright © 2016-2018 Sebastian Bensusan and Contributors.

Distributed under the Eclipse Public License either version 1.0 or (atyour option) any later version.