README.md 2.94 KB
Newer Older
Jorgen Schaefer's avatar
Jorgen Schaefer committed
1 2 3
# Buttercup — Behavior-Driven Emacs Lisp Testing

Buttercup is a behavior-driven development framework for testing Emacs
4 5 6 7
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.
Jorgen Schaefer's avatar
Jorgen Schaefer committed
8

9 10
The framework is heavily inspired by
[Jasmine](https://jasmine.github.io/edge/introduction.html).
Jorgen Schaefer's avatar
Jorgen Schaefer committed
11

12
## Example
13

Sean Whitton's avatar
Sean Whitton committed
14
*Full article: [Writing Tests](writing-tests.md)*
15

16
A simple test looks like this.
17 18 19 20 21 22 23

```Lisp
(describe "A suite"
  (it "contains a spec with an expectation"
    (expect t :to-be t)))
```

Sean Whitton's avatar
Sean Whitton committed
24
## Usage
Jorgen Schaefer's avatar
Jorgen Schaefer committed
25

Sean Whitton's avatar
Sean Whitton committed
26
*Full article: [Running Tests](running-tests.md)*
27

Sean Whitton's avatar
Sean Whitton committed
28
Create a file called `test-feature.el` with these contents:
Jorgen Schaefer's avatar
Jorgen Schaefer committed
29 30 31 32 33 34 35

```Lisp
(describe "A suite"
  (it "contains a spec with an expectation"
    (expect t :to-be t)))
```

36
You can now use buttercup to run this test:
37 38

```
39 40
$ emacs -batch -f package-initialize -f buttercup-run-discover
Running 1 specs.
41

42 43
A suite
  contains a spec with an expectation
Jorgen Schaefer's avatar
Jorgen Schaefer committed
44

45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
Ran 1 specs, 0 failed, in 0.0 seconds.
```

Congratulations, you ran your first test!

## Feature List

- Shared set-up and tear-down sections to reduce code repetition and
  share a common environment among tests.
- Easy to read and extensible `expect` macro to describe expected
  behavior.
- Powerful mocking framework, called “spies,” to both cause them to
  return expected values or throw errors as needed by the test, as
  well as to ensure functions are called with expected arguments
  during tests.
- Built to be run within a Continuous Integration environment,
  including test runners to discover and execute tests in a directory
  tree.

### Why not ERT?

Emacs comes with a testing framework,
[ERT](https://www.gnu.org/software/emacs/manual/html_mono/ert.html).
Buttercup was written to address some shortcomings of that framework.

- ERT
  [deliberately leaves it up to the programmer to define set-up and tear-down code](https://www.gnu.org/software/emacs/manual/html_mono/ert.html#Fixtures-and-Test-Suites),
  which requires a lot of boiler-plate code for every set-up function.
  Buttercup makes this easy and seamless.
- ERT has no good way of being run in a continuous integration
  environment. There are
  [external projects to make this less of a pain](https://github.com/rejeep/ert-runner.el)
  instead. Once all is said and done, you installed six external
  packages your project does not need just to run your own tests. And
  that does not include a mocking library.
- ERT has no way of grouping related tests, requiring every test name
  to share the same prefix, making names long and hard to read.

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.