How to write test fixtures for FiveAM.

When you write a comprehensive test suite you will most likely need to repeat the same set up and tear down process multiple times because a lot of the tests will test the same basic scenario in a slightly different way.

Testing frameworks address this code repetition problem with “fixtures”. FiveAM also has this concept, although slightly limited¹.

FiveAM implements fixtures as a wrapper around defmacro. The documentation states:

NB: A FiveAM fixture is nothing more than a macro. Since the term ‘fixture’ is so common in testing frameworks we’ve provided a wrapper around defmacro for this purpose.

There are no examples in the documentation on what such a fixture-macro should look like. Do you need the usual macro symbology like backticks and splicing or not? If so how? This can be difficult to decipher if you are not fluent in reading macros. The single example in the source code is making things worse because it does include backticks and splicing.

FiveAM defines a macro def-fixture which allows you write your fixtures just like normal functions with the one exception that there is an implicit variable &body to represent your test code. No fiddling with complex macros!

This is a simple example:

(def-fixture in-test-environment ()
  "Set up and tear down the test environment."
  (setup-code)
  (&body)
  (teardown-code))

(def-test a-test ()
  "Test in clean environment."
  (with-fixture in-test-environment ()
    (is-true (some-function))))

The fixture implementation provides an easy-to-use definition syntax without any additional processing. If you need more complex macros than what def-fixture can handle you can write normal Lisp macros as usual without interfering with FiveAM’s operation.