undercover.el

A test coverage library for Emacs Lisp.

Notes

Few important notes about undercover.el:

• it assumes a certain development cycle of your package (using Cask, Travis CI, and Coveralls), Codecov, or compatible;
• it doesn't support test coverage for byte-compiled files;
• it based on edebug and can have some issues with macros coverage. It doesn't support Circular Objects.

Check out combined usage example and buttercup integration example for more information.

Installation

• Add undercover.el to your Cask file:

  (source gnu)
  (source melpa)
  
  (package-file "awesome-package.el")
  
  (development
    (depends-on "undercover"))

• Before load or require your package in test/test-helper.el or features/support/env.el (or analogue), call undercover with wildcards that will match package files:

  (when (require 'undercover nil t)
    (undercover "*.el" "awesome-extensions/*.el" (:exclude "awesome-examples.el")))
  
  (require 'awesome-package)

• Add your repository to Coveralls or Codecov.

• For coverage services other than Coveralls, add the relevant command to .travis.yml. For example:

after_success:
  # Upload coverage
  - bash <(curl -s https://codecov.io/bash)

Configuration

• If you don't use Travis CI you need to set COVERALLS_REPO_TOKEN environment variable before running tests, for example:

  $ COVERALLS_REPO_TOKEN=<your-coveralls-repo-token> cask exec ert-runner

• Set report-type if not using Coveralls:

  (undercover "*.el" (:report-type :codecov))

• Set report-file option if you want to change report location:

  (undercover "*.el" (:report-file "/tmp/local-report.json"))

  undercover.el will try to merge new report with existing one.

• Set send-report option to nil if you don't want to send coverage report:

  (undercover "*.el" (:report-file "/tmp/local-report.json") (:send-report nil))

• Set UNDERCOVER_FORCE environment variable if you want to do coverage calculation locally:

  $ UNDERCOVER_FORCE=true cask exec ert-runner

• Set UNDERCOVER_CONFIG if you want to configure undercover.el via environment variables:

  (when (require 'undercover nil t) (undercover))

  $ UNDERCOVER_CONFIG='("*.el" (:exclude "awesome-examples.el"))' cask exec ert-runner

• If you get "UNDERCOVER: No coverage information [...]", make sure of the following:

  1. remove byte-compiled files (*.elc) of your project
  2. load and configure undercover before your project files (see above)
  3. make sure ert-runner does not load your project files (your project's .ert-runner should use -L instead of -l for files you want to measure coverage of)

• If you want to measure code coverage locally, you can set TRAVIS=true in the shell environment or (setq undercover-force-coverage t) in emacs.