Running Tests

Running tests is fairly easy. They can be run in the browser or via Node.js. To ensure ical.js works in both environments the tests should be run in both environments, but you can be fairly certain it works if it passes in at least one environment.

Test Suites

The performance tests make sure the important parts of the library remain fast. This is mostly the recurrence parser, which needs to be as fast as possible for smooth operation with many events.

Running these tests usually takes a while.

Three versions are compared:

• latest: The version in the current working directory (i.e. your current work).
• previous: An old version of the parser, before some massive performance improvements.
• upstream: The version of ical.js on the master branch (uses git show master:build/ical.js)

The acceptance tests check to see if the gathered real life examples of ics are accepted by the parser. If you come across .ics data that is not understood by ICAL.js you should create an issue to include it as an acceptance test.

The unit tests are most important, and ensure there are no regressions in the ICAL.js code. These tests should ideally cover every line of code we have. When developing a patch, you will usually be running these tests only.

Unless you are testing performance regressions, I'd suggest skipping the performance tests; they take very long to run.

If you are working on a part of the code that is performance-sensitive (like the parser, or recurrence expansion code) you should run these tests before sending a pull request. Be sure to compare the upstream numbers to the latest numbers to see if there have been any major changes in ops per second.

Installing the prerequisites

If you haven't already done this, you should execute npm install to make sure the prerequisites are installed. On Windows, I recently got an error like this:

Error: ENOENT, stat 'C:\Users\kewisch\AppData\Roaming\npm'

This seems to be an error with the node windows package. Simply creating that directory solved the issue for me.

Running tests in the browser

$ grunt test-browser

Running tests in the command line via node

If you prefer running all tests within your terminal, you can also run the tests via command line using node. To do so, run grunt test-node. You will get the following output:

$ grunt test-node
Running "test-node" task

Running "performance-update-upstream" task
>> There are git changes, also comparing against master branch

Running "mochacli:performance" (mochacli) task
    (...)
Running "mochacli:acceptance" (mochacli) task
    (...)
Running "mochacli:unit" (mochacli) task
    (...)

You can run each of the test suites separately:

grunt test-node:unit                                 # Run all unit tests
grunt test-node:acceptance                           # Run all acceptance tests
grunt test-node:performance                          # Run all performance tests
grunt test-node:single --test=test/period_test.js    # Run a single test (of any type)

Debugging Tests

All tests can be debugged using node-inspector.

To do so, you need to have either Chrome or Opera installed. Everything else is taken care of by grunt. Just add --debug as a parameter at the end of a call to grunt test-node.

For example, run the following command:

grunt test-node:single --test=test/period_test.js --debug

If all goes well, Chrome will open and present the debugger UI stopped at an initial breakpoint. You can then set more breakpoints and continue execution.

Sometimes when Chrome is already open, it will just open a blank window.

If all else fails, you can visit http://127.0.0.1:8080/debug?port=5858 manually.

Output should look like this:

Running "test-node:single" (test-node) task
[D] Task source: /Users/kewisch/mozilla/github/ical.js/Gruntfile.js

Running "concurrent:single" (concurrent) task
[D] Task source: /Users/kewisch/mozilla/github/ical.js/node_modules/grunt-concurrent/tasks/concurrent.js
    
    Running "node-inspector:test" (node-inspector) task
    [D] Task source: /Users/kewisch/mozilla/github/ical.js/node_modules/grunt-node-inspector/tasks/inspector.js
    Node Inspector v0.9.2
    
    Done, without errors.

Code Coverage

You can check the level of code coverage locally to help figure out if your newly written code is sufficiently tested. Only the unit tests contribute to code coverage. Running grunt coverage will result in the following output:

$ grunt coverage
Running "mocha_istanbul:coverage" (mocha_istanbul) task

  ․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․
  ․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․
  ․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․
  ․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․․

  506 tests complete (5 seconds)

=============================================================================
Writing coverage object [/Users/kewisch/mozilla/github/ical.js/coverage/coverage.json]
Writing coverage reports at [/Users/kewisch/mozilla/github/ical.js/coverage]
=============================================================================

=============================== Coverage summary ===============================
Statements   : 94.69% ( 2512/2653 ), 14 ignored
Branches     : 90.69% ( 1276/1407 ), 23 ignored
Functions    : 98.6% ( 351/356 ), 5 ignored
Lines        : 94.62% ( 2478/2619 )
================================================================================
>> Done. Check coverage folder.

Done, without errors.

You can then open coverage/lcov-report/index.html in your browser to view the coverage report.

Writing new tests

When writing new tests, just follow the style of the other tests.

If you need help on the assertions commands, check the Chai documentation.