Repository files navigation

Formerly published as dispatch:mocha. Originally created byDispatch but now community maintained.

A Mocha test driver package for Meteor. This package reports server AND client test results in the server console and can be used for running tests on a CI server or locally.

In a Meteor 1.3+ app directory:

meteor add meteortesting:mocha

Not installing the package is possible but not advisable when creating a CI pipeline because the system will always download the latest version available, which might break your CI pipeline in a future major release of this package.

Since version 2.0.0 the packagelmieulet:meteor-coverageis no longer bundled with this package.

If you permanently want code coverage please run:

meteor add lmieulet:meteor-coverage

If you rather want the package to be included only for a single run, add the parameter--extra-packages lmieulet:meteor-coverage as shown to yourmeteor test command:

meteortest --driver-package meteortesting:mocha --extra-packages lmieulet:meteor-coverage

For the full documentation of meteor coverage, please consultthe docs in its repo.

To watch your tests in Meteor 1.8.1+:

meteortest --driver-package meteortesting:mochameteortest --driver-package meteortesting:mocha --full-app

NOTE: Watch mode does not properly rerun client tests if you run a headless browser and change only client code. To work around this, you can add or remove whitespace from a server file, and that will trigger both server and client tests to rerun.

If you want the process to exit after all tests are done, add the flag--once:

meteortest --driver-package meteortesting:mocha --oncemeteortest --driver-package meteortesting:mocha --once --full-app

In Meteor <1.8.1, you must addTEST_WATCH=1 if you do not add the--once flag. For example:

TEST_WATCH=1 meteortest --driver-package meteortesting:mochaTEST_WATCH=1 meteortest --driver-package meteortesting:mocha --full-app

If you have client tests, you can either open any browser to run them, or install a browser driver to run them headless.

Loadhttp://localhost:3000 in a browser to run your client tests and see the results. This only works well in watch mode because otherwise the server will likely shut down before you finish running the client tests.

The test results are reported in a div with IDmocha. If you run with the--full-app flag, this will likely be overlaid weirdly on top of your app, so you should add CSS to your app in order to be able to see both. For example, this will put the test results in a sidebar with resizeable width:

div#mocha {background: white;border-right:2px solid black;height:100%;left:0;margin:0;overflow: auto;padding:1rem;position: fixed;resize: horizontal;top:0;width:20px;z-index:1000;}

Support for running browser in headless mode is made possible by the package `` which this plugin depends on. Please refer to their documentation for further information:https://github.com/meteortesting/meteor-browser-tests#dependencies

By default both server and client tests run. To disable server tests:TEST_SERVER=0. Likewise for client:TEST_CLIENT=0

To run all tests with names that match a pattern, add the environment variableMOCHA_GREP=your_string. This will apply to both client and server tests.

To exclude any tests, you must use the grep option above plusMOCHA_INVERT=1. For example, to exclude tests named 'TODO:' (which you may want to exclude from your continuous integration workflow) you would pass at runtimeMOCHA_GREP=your_string MOCHA_INVERT=1

To override Mocha's default timeout of 2 seconds for all tests, add the environment variableMOCHA_TIMEOUT=your_timeout_in_ms.

You can configure the mocha runner with a.mocharc.js or a.mocharc.json file at the root of your Meteor app. This package uses mocha programmatically, so it supports a constrained list of options.

If both files are defined,.mocharc.js will overwrite the settings in.mocharc.json.

The settingtimeout will be overwritten if the environment variableMOCHA_TIMEOUT is set.

• Read more about using mocha and supported optionshere.
• You can find examples of config fileshere.

By default meteortesting:mocha will run in series. This is a safety mechanism since running a client test and server test which depend on DB state may have side effects.

If you design your client and server tests to not share state, then you can run tests faster. Run in parallel by exporting the environment variableTEST_PARALLEL=1 before running.

To write the tests to a file, setSERVER_MOCHA_OUTPUT andCLIENT_MOCHA_OUTPUT to the full path + filename, e.g.,$PWD/unit_server.txt and$PWD/unit_client.txt. This is specially important when using a format likexunit. The use ofXUNIT_FILE is deprecated because it has the same functionality asSERVER_MOCHA_OUTPUT, which is a better fit for what it actually does.

$ MOCHA_REPORTER=xunit SERVER_MOCHA_OUTPUT=$PWD/unit_server.xml CLIENT_MOCHA_OUTPUT=$PWD/unit_client.xml meteortest --once --driver-package meteortesting:mocha

The default Mocha reporter for server tests is the "spec" reporter. You can set theSERVER_TEST_REPORTER environment variable to change it.

$ SERVER_TEST_REPORTER="dot" meteortest --once --driver-package meteortesting:mocha

The default Mocha reporter for client tests is the "spec" reporter when running headless and "html" otherwise. You can set theCLIENT_TEST_REPORTER environment variable to change it.

$ CLIENT_TEST_REPORTER="tap" meteortest --once --driver-package meteortesting:mocha

Since version 2.0.0 the packagelmieulet:meteor-coverage is no longer bundled with this package. If you permanently want code coverage please run:

meteor add lmieulet:meteor-coverage

If you rather want the package to be included only for a single run, add the parameter--extra-packages lmieulet:meteor-coverage as shown to yourmeteor test command:

meteortest --driver-package meteortesting:mocha --extra-packages lmieulet:meteor-coverage

To enable code coverage you have to setCOVERAGE to1 andCOVERAGE_APP_FOLDER to the path of your project. On POSIX systems you can just useCOVERAGE_APP_FOLDER=$PWD/ wherebyCOVERAGE_APP_FOLDER=%cd%\ gives the expected result on Windows.

In addition there are quite some additional options you can set:

• COVERAGE_VERBOSE to see the files included in the coverage and other data that might help if something doesn't work as expected
• COVERAGE_IN_COVERAGE imports a coverage dump (previously create withCOVERAGE_OUT_COVERAGE)
• COVERAGE_OUT_COVERAGE creates a dump of the coverage - used when you want to merge several coverage
• COVERAGE_OUT_LCOVONLY creates a lcov report
• COVERAGE_OUT_HTML creates a html report
• COVERAGE_OUT_JSON creates a json report
• COVERAGE_OUT_JSON_SUMMARY creates a json_summary report
• COVERAGE_OUT_TEXT_SUMMARY creates a text_summary report
• COVERAGE_OUT_REMAP remaps the coverage to all the available report formats

Additional information can be found here:https://github.com/serut/meteor-coverage

A good best practice is to define these commands as run scripts in your app'spackage.json file. For example:

"scripts": {"pretest":"npm run lint --silent","test-chrome":"TEST_BROWSER_DRIVER=chrome meteor test --once --driver-package meteortesting:mocha","test-app-chrome":"TEST_BROWSER_DRIVER=chrome meteor test --full-app --once --driver-package meteortesting:mocha","test-phantom":"TEST_BROWSER_DRIVER=phantomjs meteor test --once --driver-package meteortesting:mocha","test-app-phantom":"TEST_BROWSER_DRIVER=phantomjs meteor test --full-app --once --driver-package meteortesting:mocha","test-watch":"TEST_BROWSER_DRIVER=chrome meteor test --driver-package meteortesting:mocha","test-app-watch":"TEST_BROWSER_DRIVER=chrome meteor test --full-app --driver-package meteortesting:mocha","test-watch-browser":"meteor test --driver-package meteortesting:mocha","test-app-watch-browser":"meteor test --full-app --driver-package meteortesting:mocha","lint":"eslint .","start":"meteor run"}

And then runnpm run test-chrome, etc.