src/suite.lisp

   1 ;;;; -*- Mode: Lisp; indent-tabs-mode: nil -*-
   2
   3 (in-package :it.bese.fiveam)
   4
   5 ;;;; * Test Suites
   6
   7 ;;;; Test suites allow us to collect multiple tests into a single
   8 ;;;; object and run them all using asingle name. Test suites do not
   9 ;;;; affect the way test are run nor the way the results are handled,
  10 ;;;; they are simply a test organizing group.
  11
  12 ;;;; Test suites can contain both tests and other test suites. Running
  13 ;;;; a test suite causes all of its tests and test suites to be
  14 ;;;; run. Suites do not affect test dependencies, running a test suite
  15 ;;;; can cause tests which are not in the suite to be run.
  16
  17 ;;;; ** Creating Suits
  18
  19 (defvar *suites* (make-hash-table :test 'eql))
  20
  21 (defmacro def-suite (name &key description (in nil in-p) (fixture nil fixture-p))
  22   "Define a new test-suite named NAME.
  23
  24 NAME::
  25   The symbol naming the test.
  26
  27 DESCRIPTION::
  28   A string describing the contents/purpose of this suite.
  29
  30 IN (a symbol), if provided, causes this suite te be nested in the
  31 suite named by `IN`. If `IN` is `NIL`, as opposed to not being passed
  32 at all, the new suite will not be a part of any existing suite.
  33
  34 \[NOTE]
  35 This macro is built on top of `make-suite` as such it, like `make-suite`,
  36 will overrwrite any existing suite named `NAME`.
  37
  38 DESCRIPTION is just a string.
  39
  40 FIXTURE is the fixture argument (exactly like the `:fixture` argument to
  41 def-test) to pass to tests in this suite."
  42   `(eval-when (:compile-toplevel :load-toplevel :execute)
  43      (make-suite ',name
  44                  ,@(when description `(:description ,description))
  45                  ,@(when in-p      `(:in ',in))
  46                  ,@(when fixture-p `(:fixture ',fixture)))
  47      ',name))
  48
  49 (defmacro def-suite* (name &rest def-suite-args)
  50   `(progn
  51      (def-suite ,name ,@def-suite-args)
  52      (in-suite ,name)))
  53
  54 (declaim (special *suite*))
  55
  56 (defun make-suite (name &key description ((:in parent-suite) *suite*) fixture)
  57   "Create a new test suite object.
  58
  59 Overrides any existing suite named NAME."
  60   (let ((suite (make-instance 'test-suite :name name)))
  61     (%update-suite name suite description parent-suite fixture)
  62     (setf (gethash name *suites*) suite)
  63     (setf (get-test name) suite)
  64     suite))
  65
  66 (defun update-suite (name suite
  67                      &key description ((:in parent-suite) *suite*) fixture)
  68   (%update-suite name suite description parent-suite fixture))
  69
  70 (defun list-all-suites ()
  71   "Returns an unordered LIST of all suites."
  72   (hash-table-values *suites*))
  73
  74 (defun remove-from-suites (name &optional parents)
  75   (when (get-test name)
  76     ;; if this suite already exists, and its :IN some other suite, remove it.
  77     (dolist (s (list-all-suites))
  78       (let ((tests (tests s)))
  79         (when (and (not (member (name s) parents :test #'eq))
  80                    (gethash name tests))
  81           (remhash name tests))))))
  82
  83 (defun add-to-suites (name suite parents)
  84   (dolist (i parents)
  85     (let ((in-suite (get-test i)))
  86       (when (null in-suite)
  87         (cerror "Create a new suite named ~A." "Unknown suite ~A." i)
  88         (setf in-suite (make-suite i)
  89               (get-test in-suite) in-suite))
  90       (setf (gethash name (tests in-suite)) suite))))
  91
  92 (defun remove-from-add-to-suites (test-name suite parent-suite)
  93   ;; prevent cycles
  94   (unless (eq suite parent-suite)
  95     (let ((parents (ensure-list parent-suite)))
  96       (remove-from-suites test-name parents)
  97       (add-to-suites test-name suite parents))))
  98
  99 (defun %update-suite (name suite description parent-suite fixture)
 100   (setf (description suite) description)
 101   (setf (fixture suite) fixture)
 102   (remove-from-add-to-suites name suite parent-suite)
 103   suite)
 104
 105 ;;;; ** Managing the Current Suite
 106
 107 (defvar *suite* (setf (get-test 'T) (make-suite 'T :description "Default global suite" :in nil))
 108   "The current test suite object")
 109
 110 (defmacro in-suite (suite-name)
 111   "Set the `*suite*` special variable so that all tests defined
 112 after the execution of this form are, unless specified otherwise,
 113 in the test-suite named `SUITE-NAME`.
 114
 115 See also: `DEF-SUITE` and `*SUITE*`. "
 116   `(eval-when (:compile-toplevel :load-toplevel :execute)
 117      (%in-suite ,suite-name)))
 118
 119 (defmacro in-suite* (suite-name &rest def-suite-args)
 120   "Same effect as `IN-SUITE`, but if `SUITE-NAME` does not exist it
 121 will be created (as per DEF-SUITE), or updated with the new arguments."
 122   `(%in-suite ,suite-name
 123               :fail-on-error nil
 124               ,@def-suite-args))
 125
 126 (defmacro %in-suite (suite-name
 127                      &key description (in nil in-p) (fixture nil fixture-p)
 128                           (fail-on-error t))
 129   (let ((def-suite-args
 130           `(,@(when description `(:description ,description))
 131             ,@(when in-p `(:in ',in))
 132             ,@(when fixture-p `(:fixture ',fixture)))))
 133     (with-gensyms (suite)
 134       `(progn
 135          (if-let (,suite (get-test ',suite-name))
 136            (setf *suite* (update-suite ',suite-name ,suite ,@def-suite-args))
 137            (progn
 138              ,@(when fail-on-error
 139                  `((cerror "Create a new suite named ~A."
 140                            "Unknown suite ~A." ',suite-name)))
 141              (setf *suite* (make-suite ',suite-name ,@def-suite-args))))
 142          ',suite-name))))
 143
 144 ;; Copyright (c) 2002-2003, Edward Marco Baringer
 145 ;; All rights reserved.
 146 ;;
 147 ;; Redistribution and use in source and binary forms, with or without
 148 ;; modification, are permitted provided that the following conditions are
 149 ;; met:
 150 ;;
 151 ;;  - Redistributions of source code must retain the above copyright
 152 ;;    notice, this list of conditions and the following disclaimer.
 153 ;;
 154 ;;  - Redistributions in binary form must reproduce the above copyright
 155 ;;    notice, this list of conditions and the following disclaimer in the
 156 ;;    documentation and/or other materials provided with the distribution.
 157 ;;
 158 ;;  - Neither the name of Edward Marco Baringer, nor BESE, nor the names
 159 ;;    of its contributors may be used to endorse or promote products
 160 ;;    derived from this software without specific prior written permission.
 161 ;;
 162 ;; THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 163 ;; "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 164 ;; LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 165 ;; A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
 166 ;; OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 167 ;; SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 168 ;; LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 169 ;; DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 170 ;; THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 171 ;; (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 172 ;; OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE