Buttercup is a behavior-driven development framework for testing Emacs Lisp code. It allows to group related tests so they can share common set-up and tear-down code, and allows the programmer to “spy” on functions to ensure they are called with the right arguments during testing.
The framework is heavily inspired by Jasmine.
Full article: Writing Tests
A simple test looks like this. Note that lexical-binding: t
is
required in files defining buttercup tests.
;;; lexical-binding is required -*- lexical-binding: t; -*-
(describe "A suite"
(it "contains a spec with an expectation"
(expect t :to-be t)))
Full article: Running Tests
You can install buttercup from
NonGNU ELPA or
MELPA Stable. Add the following to your
init.el
or .emacs
file:
(require 'package)
;; Available as a default in GNU Emacs from version 28.1
(add-to-list 'package-archives
("nongnu" . "https://elpa.nongnu.org/nongnu/") t)
(add-to-list 'package-archives
'("melpa-stable" . "http://stable.melpa.org/packages/") t)
This should allow you to M-x package-install RET buttercup RET
.
Alternatively, users of Debian 9 or later or Ubuntu 16.10 or later may
simply apt-get install elpa-buttercup
.
Now create a file called test-feature.el
with these contents:
;;; -*- lexical-binding: t; -*-
(describe "A suite"
(it "contains a spec with an expectation"
(expect t :to-be t)))
You can now use buttercup to run this test:
$ emacs -batch -f package-initialize -L . -f buttercup-run-discover
Running 1 specs.
A suite
contains a spec with an expectation
Ran 1 specs, 0 failed, in 0.0 seconds.
Congratulations, you ran your first test!
expect
macro to describe expected
behavior.Emacs comes with a testing framework, ERT. Buttercup was written to address some shortcomings of that framework.
Nonetheless, ERT is a great project. It introduced testing to Emacs, and Buttercup learned a lot from its code to record a stack trace for error display. Even though Buttercup tries to be a better testing framework than ERT, we do wish ERT and the ERT maintainers all the best and hope both frameworks can continue to benefit from each other.