src/test.lisp

   1 ;;;; -*- Mode: Lisp; indent-tabs-mode: nil -*-
   2
   3 (in-package :it.bese.fiveam)
   4
   5 ;;;; * Tests
   6
   7 ;;;; While executing checks and collecting the results is the core job
   8 ;;;; of a testing framework it is also important to be able to
   9 ;;;; organize checks into groups, fiveam provides two mechanisms for
  10 ;;;; organizing checks: tests and test suites. A test is a named
  11 ;;;; collection of checks which can be run and a test suite is a named
  12 ;;;; collection of tests and test suites.
  13
  14 (defvar *test*
  15   (make-hash-table :test 'eql)
  16   "Lookup table mapping test (and test suite) names to objects.")
  17
  18 (defun get-test (key &key default error)
  19   "Finds the test named KEY. If KEY is a testable-object (a test case
  20 or a test suite) then we just return KEY, otherwise we look for a test
  21 named KEY in the *TEST* hash table."
  22   (if (testable-object-p key)
  23       key
  24       (multiple-value-bind (value foundp)
  25           (gethash key *test*)
  26         (if foundp
  27             value
  28             (if error
  29                 (error "Unable to find test named ~S." key)
  30                 default)))))
  31
  32 (defun (setf get-test) (value key)
  33   (setf (gethash key *test*) value))
  34
  35 (defun rem-test (key)
  36   (remhash key *test*))
  37
  38 (defun test-names ()
  39   (loop for test being the hash-keys of *test*
  40         collect test))
  41
  42 (defmacro test (name &body body)
  43   "Deprecated. See DEF-TEST."
  44   (simple-style-warning "~A is OBSOLETE! Use ~A instead." 'test 'def-test)
  45   (destructuring-bind (name &rest args)
  46       (ensure-list name)
  47     `(def-test ,name (,@args) ,@body)))
  48
  49 (declaim (special *suite*))
  50
  51 (defmacro def-test (name (&key (suite nil suite-p)
  52                                fixture
  53                                (compile-at :run-time)
  54                                depends-on
  55                                profile)
  56                     &body body)
  57   "Create a test named NAME.
  58
  59 NAME (a symbol)::
  60   The name of the test.
  61
  62 SUITE (a test name)::
  63   The suite to put the test under. It defaults to *SUITE* (which
  64   itself defaults to the default global suite).
  65
  66 FIXTURE::
  67   The name of the fixture to use for this test. See `WITH-FIXTURE` for
  68   details on fixtures.
  69
  70 COMPILE-AT (a keyword)::
  71   When the body of this test should be compiled. By default, or when
  72   `:compile-at` is `:run-time`, test bodies are only compiled before
  73   they are run. Set this to to `:definition-time` to force
  74   compilation, and errors/warnings, to be done at compile time.
  75
  76 DEPENDS-ON::
  77   A list, or a symbol, which specifies the relationship between this
  78   test and other tests. These conditions, `AND`, `OR` and `NOT` can be
  79   combined to produce complex dependencies (whethere this is something
  80   you should actually be doing is a question for another day).
  81
  82   `(and &rest TEST-NAMES)`:::
  83     This test is run only if all of the tests in TEST-NAMES have
  84     passed, otherwise a single test-skipped result is generated.
  85
  86   `(or &rest TEST-NAMES)`:::
  87     If any of TEST-NAMES has passed this test is run, otherwise a
  88     test-skipped result is generated.
  89
  90   `(NOT TEST-NAME`:::
  91     This is test is run only if TEST-NAME failed.
  92
  93   __a-symbol__:::
  94     Shorthand for `(AND a-symbol)`
  95
  96 PROFILE::
  97   When non-`NIL` profiling information will be collected as well."
  98   (check-type compile-at (member :run-time :definition-time))
  99   (multiple-value-bind (forms decls docstring)
 100       (parse-body body :documentation t :whole name)
 101     (let* ((description (or docstring ""))
 102            (body-forms (append decls forms))
 103            (suite-form (if suite-p
 104                            (if suite
 105                                `(get-test ',suite)
 106                                nil)
 107                            '*suite*))
 108            (effective-body (let* ((test-fixture fixture)
 109                                   (suite-fixture (if suite-p
 110                                                      (if suite
 111                                                          (fixture (get-test suite :error t))
 112                                                          nil)
 113                                                      (if *suite*
 114                                                          (fixture *suite*)
 115                                                          nil)))
 116                                   (effective-fixture (or test-fixture suite-fixture)))
 117                              (if effective-fixture
 118                                  (destructuring-bind (name &rest args)
 119                                      (ensure-list effective-fixture)
 120                                    `((with-fixture ,name ,args ,@body-forms)))
 121                                  body-forms))))
 122       `(progn
 123          (register-test :name ',name
 124                         :description ,description
 125                         :body ',effective-body
 126                         :suite ,suite-form
 127                         :depends-on ',depends-on
 128                         :compile-at ,compile-at
 129                         :profile ,profile)
 130          (when *run-test-when-defined*
 131            (run! ',name))
 132          ',name))))
 133
 134 (defun register-test (&key name description body suite depends-on compile-at profile)
 135   (remove-from-suites name)
 136   (let ((lambda-name
 137           (format-symbol t "%~A-~A" '#:test name))
 138         (inner-lambda-name
 139           (format-symbol t "%~A-~A" '#:inner-test name)))
 140     (setf (get-test name)
 141           (make-instance 'test-case
 142                          :name name
 143                          :runtime-package (find-package (package-name *package*))
 144                          :test-lambda
 145                          (eval
 146                           `(named-lambda ,lambda-name ()
 147                              ,@(ecase compile-at
 148                                  (:run-time `((funcall
 149                                                (let ((*package* (find-package ',(package-name *package*))))
 150                                                  (compile ',inner-lambda-name
 151                                                           '(lambda () ,@body))))))
 152                                  (:definition-time body))))
 153                          :description description
 154                          :depends-on depends-on
 155                          :collect-profiling-info profile))
 156     (when suite
 157       (setf (gethash name (tests (get-test suite :error t))) name))))
 158
 159 (defvar *run-test-when-defined* nil
 160   "When non-NIL tests are run as soon as they are defined.")
 161
 162 ;; Copyright (c) 2002-2003, Edward Marco Baringer
 163 ;; All rights reserved.
 164 ;;
 165 ;; Redistribution and use in source and binary forms, with or without
 166 ;; modification, are permitted provided that the following conditions are
 167 ;; met:
 168 ;;
 169 ;;  - Redistributions of source code must retain the above copyright
 170 ;;    notice, this list of conditions and the following disclaimer.
 171 ;;
 172 ;;  - Redistributions in binary form must reproduce the above copyright
 173 ;;    notice, this list of conditions and the following disclaimer in the
 174 ;;    documentation and/or other materials provided with the distribution.
 175 ;;
 176 ;;  - Neither the name of Edward Marco Baringer, nor BESE, nor the names
 177 ;;    of its contributors may be used to endorse or promote products
 178 ;;    derived from this software without specific prior written permission.
 179 ;;
 180 ;; THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 181 ;; "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 182 ;; LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 183 ;; A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
 184 ;; OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 185 ;; SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 186 ;; LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 187 ;; DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 188 ;; THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 189 ;; (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 190 ;; OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.