Though we find plenty of information about Karma on their website, I found it not all obvious what the different configuration settings in its config file do. We try to explain this using an example project.
The project has the following directory structure (get if from github):
// Contains all source files src/js/ src/vendor/ // Contains the tests tests/unit/ // Contains nodejs modules node_modules/
INSTALL TESTING LIBS
First, install Karma and some plugins:
// Install karma, mocha adapter and chai npm install karma karma-mocha chai --save-dev
Everything is installed in the
node_modules directory. Karma is the test runner. As a test runner it:
- Loads all files in the correct order
- Spins up browsers to run our tests in
Mocha is a test framework. It is responsible to run our tests and report back which failed.
Chai is an assertion library. It provides a nice api to check whether our code does the things we expect it to do.
CREATE KARMA CONFIG FILE
Next we create the Karma config file in our directory root running this command:
// Create Karma config file ./node_modules/karma/bin/karma init
This will prompt us for some questions and generates a config file. Items of interests to us are:
The base path tells Karma where to load our files from. Setting it to
'' means all files will be looked up from the root of our project.
files: [ "node_modules/chai/chai.js", "src/**/*.js", "tests/**/*.js" ],
Files tells Karma which files it should load relative to the base path. These are:
- All test related libraries
- Our source code to test
- The tests themselves
Note we instruct Karma to load
chai.js. Forgetting this means chai will not be loaded.
This will generate karma.conf.js file including karma configuration.
What about Mocha? Doesn’t it need to be loaded too?
Yes it should. However, Karma will autoload all sibling node modules starting with
karma-. This means if Karma is installed in the
node_modules directory, all other modules starting with
karma- will be autoloaded for us. And mocha is fetched as the
karma-mocha node module. No need to manually load it ourselves.
Frameworks instructs Karma to use the mocha testing framework.
Browsers tells Karma to run the tests in Chrome. Note, Chrome needs to be installed on our computer. Running the tests from the command line will spin up a new Chrome window.
karma-chrome-launcher node module needs to be installed too.
karma init command will auto install it for us. If you add a browser later on, don’t forget to install its runner too.
Auto watch instructs Karma to rerun the tests whenever a file changes.
Single run tells Karma to shut down the browser when all tests have ran. This is useful for Continuous Integration systems where only one run is needed. For development, set it to false as this will keep the browser window opened. This means no time is wasted spinning up a new browser every time tests need to be executed.
RUN THE TESTS
Now we can run the tests like:
Notice we can also run the tests with
./node_modules/karma/bin/karma run. This will not spin up the server to load our test files. Use it in combination with
karma start. Start will spin up the browser and load the files, run will instruct karma to rerun the tests.
It’s tiresome to always do
./node_modules/karma/bin/karma start instead of just
karma start. Therefore install
npm install -g karma-cli
This tool executes the Karma commands for the project in the current directory. By exposing the commands in a separate module then the Karma implementation, we can use different versions of Karma for different projects on our computer.
Note: we might have installed Karma globally before. If so, we need to delete it first as it will mess up which plugins it will autoload. For example: we might have installed
karma-mocha in our project dir but not globally. Executing Karma (as global installed module) will fail to load
karma-mocha (since “global” Karma will only look into the globally installed modules). Just uninstall
karma as a global module and install
karma-cli globally instead.