diff --git a/HUnit.cabal b/HUnit.cabal --- a/HUnit.cabal +++ b/HUnit.cabal @@ -1,20 +1,25 @@ -name: HUnit -version: 1.2.0.0 -license: BSD3 -license-file: LICENSE -author: Dean Herington -homepage: http://hunit.sourceforge.net/ -category: Testing -build-depends: base -synopsis: A unit testing framework for Haskell +name: HUnit +version: 1.2.0.1 +license: BSD3 +license-file: LICENSE +author: Dean Herington +homepage: http://hunit.sourceforge.net/ +category: Testing +synopsis: A unit testing framework for Haskell +maintainer: libraries@haskell.org +cabal-version: >= 1.2 description: - HUnit is a unit testing framework for Haskell, inspired by the - JUnit tool for Java, see: . + HUnit is a unit testing framework for Haskell, inspired by the + JUnit tool for Java, see: . build-type: Simple -exposed-modules: - Test.HUnit.Base, - Test.HUnit.Lang, - Test.HUnit.Terminal, - Test.HUnit.Text, - Test.HUnit -extensions: CPP + +Library + build-depends: base + exposed-modules: + Test.HUnit.Base, + Test.HUnit.Lang, + Test.HUnit.Terminal, + Test.HUnit.Text, + Test.HUnit + extensions: CPP + diff --git a/README b/README new file mode 100644 --- /dev/null +++ b/README @@ -0,0 +1,12 @@ +HUnit is a unit testing framework for Haskell, inspired by the JUnit +tool for Java. HUnit is free software; see its "License" file for +details. HUnit is available at . + +HUnit 1.1.1 consists of a number of files. Besides Haskell source files +in Test/HUnit (whose names end in ".hs" or ".lhs"), these files include: + + * README -- this file + * doc/Guide.html -- user's guide, in HTML format + * LICENSE -- license for use of HUnit + +See the user's guide for more information. diff --git a/Test/HUnit/Lang.lhs b/Test/HUnit/Lang.lhs --- a/Test/HUnit/Lang.lhs +++ b/Test/HUnit/Lang.lhs @@ -20,7 +20,7 @@ > import Data.List (isPrefixOf) #if defined(__GLASGOW_HASKELL__) || defined(__HUGS__) > import Data.Dynamic -> import Control.Exception as E ( throwDyn, try, Exception(..) ) +> import Control.Exception as E #else > import System.IO.Error (ioeGetErrorString, try) #endif @@ -52,7 +52,10 @@ #if defined(__GLASGOW_HASKELL__) || defined(__HUGS__) > data HUnitFailure = HUnitFailure String +> deriving Show > +> instance Exception HUnitFailure +> > hunitFailureTc :: TyCon > hunitFailureTc = mkTyCon "HUnitFailure" > {-# NOINLINE hunitFailureTc #-} @@ -60,17 +63,14 @@ > instance Typeable HUnitFailure where > typeOf _ = mkTyConApp hunitFailureTc [] -> assertFailure msg = E.throwDyn (HUnitFailure msg) +> assertFailure msg = E.throw (HUnitFailure msg) > performTestCase action = -> do r <- E.try action -> case r of -> Right () -> return Nothing -> Left e@(E.DynException dyn) -> -> case fromDynamic dyn of -> Just (HUnitFailure msg) -> return $ Just (True, msg) -> Nothing -> return $ Just (False, show e) -> Left e -> return $ Just (False, show e) +> do action +> return Nothing +> `E.catches` +> [E.Handler (\(HUnitFailure msg) -> return $ Just (True, msg)), +> E.Handler (\e -> return $ Just (False, show (e :: E.SomeException)))] #else > hunitPrefix = "HUnit:" diff --git a/doc/Guide.html b/doc/Guide.html new file mode 100644 --- /dev/null +++ b/doc/Guide.html @@ -0,0 +1,711 @@ + + + + + + + + HUnit 1.0 User's Guide + + + +

HUnit 1.0 User's Guide

+ +HUnit is a unit testing framework for Haskell, inspired by the JUnit +tool for Java. This guide describes how to use HUnit, assuming +you are familiar with Haskell, though not necessarily with +JUnit. You can obtain HUnit, including this guide, at +http://hunit.sourceforge.net. + +

Introduction

+ +A test-centered methodology for software development is most effective +when tests are easy to create, change, and execute. The JUnit tool pioneered support for +test-first development in Java. +HUnit is an adaptation of JUnit to Haskell, a general-purpose, purely +functional programming language. (To learn more about Haskell, +see http://www.haskell.org.) +

+With HUnit, as with JUnit, you can easily create tests, name them, +group them into suites, and execute them, with the framework checking +the results automatically. Test specification in HUnit is even +more concise and flexible than in JUnit, thanks to the nature of the +Haskell language. HUnit currently includes only a text-based +test controller, but the framework is designed for easy +extension. (Would anyone care to write a graphical test +controller for HUnit?) +

+The next section helps you get started using HUnit in simple +ways. Subsequent sections give details on writing tests and running tests. The document concludes +with a section describing HUnit's constituent files and a section giving +references to further information. + +

Getting Started

+ +In the Haskell module where your tests will reside, import module +Test.HUnit: +
+    import Test.HUnit
+
+Define test cases as appropriate: +
+    test1 = TestCase (assertEqual "for (foo 3)," (1,2) (foo 3))
+    test2 = TestCase (do (x,y) <- partA 3
+                         assertEqual "for the first result of partA," 5 x
+                         b <- partB y
+                         assertBool ("(partB " ++ show y ++ ") failed") b)
+
+Name the test cases and group them together: +
+    tests = TestList [TestLabel "test1" test1, TestLabel "test2" test2]
+
+Run the tests as a group. At a Haskell interpreter prompt, apply +the function runTestTT to the collected tests. (The +"TT" suggests text orientation with output to +the terminal.) +
+    > runTestTT tests
+    Cases: 2  Tried: 2  Errors: 0  Failures: 0
+    >
+
+If the tests are proving their worth, you might see: +
+    > runTestTT tests
+    ### Failure in: 0:test1
+    for (foo 3),
+    expected: (1,2)
+     but got: (1,3)
+    Cases: 2  Tried: 2  Errors: 0  Failures: 1
+    >
+
+Isn't that easy? +

+You can specify tests even more succinctly using operators and +overloaded functions that HUnit provides: +

+    tests = test [ "test1" ~: "(foo 3)" ~: (1,2) ~=? (foo 3),
+                   "test2" ~: do (x, y) <- partA 3
+                                 assertEqual "for the first result of partA," 5 x
+                                 partB y @? "(partB " ++ show y ++ ") failed" ]
+
+Assuming the same test failures as before, you would see: +
+    > runTestTT tests
+    ### Failure in: 0:test1:(foo 3)
+    expected: (1,2)
+     but got: (1,3)
+    Cases: 2  Tried: 2  Errors: 0  Failures: 1
+    >
+
+ +

Writing Tests

+ +Tests are specified compositionally. Assertions are combined to make a test case, and test cases are combined into tests. HUnit also provides advanced features for more convenient +test specification. + +

Assertions

+ +The basic building block of a test is an assertion. +
+    type Assertion = IO ()
+
+An assertion is an IO computation that always produces a void +result. Why is an assertion an IO computation? So that +programs with real-world side effects can be tested. How does an +assertion assert anything if it produces no useful result? The answer +is that an assertion can signal failure by calling +assertFailure. +
+    assertFailure :: String -> Assertion
+    assertFailure msg = ioError (userError ("HUnit:" ++ msg))
+
+(assertFailure msg) raises an exception. The string +argument identifies the failure. The failure message is prefixed +by "HUnit:" to mark it as an HUnit assertion failure +message. The HUnit test framework interprets such an exception +as indicating failure of the test whose execution raised the +exception. (Note: The details concerning the implementation of +assertFailure are subject to change and should not be relied +upon.) +

+assertFailure can be used directly, but it is much more +common to use it indirectly through other assertion functions that +conditionally assert failure. +

+    assertBool :: String -> Bool -> Assertion
+    assertBool msg b = unless b (assertFailure msg)
+
+    assertString :: String -> Assertion
+    assertString s = unless (null s) (assertFailure s)
+
+    assertEqual :: (Eq a, Show a) => String -> a -> a -> Assertion
+    assertEqual preface expected actual =
+      unless (actual == expected) (assertFailure msg)
+     where msg = (if null preface then "" else preface ++ "\n") ++
+                 "expected: " ++ show expected ++ "\n but got: " ++ show actual
+
+With assertBool you give the assertion condition and failure +message separately. With assertString the two are +combined. With assertEqual you provide a "preface", an +expected value, and an actual value; the failure message shows the two +unequal values and is prefixed by the preface. Additional ways +to create assertions are described later under Advanced Features. +

+Since assertions are IO computations, they may be +combined--along with other IO computations--using +(>>=), (>>), and the do notation. As +long as its result is of type (IO ()), such a combination +constitutes a single, collective assertion, incorporating any number +of constituent assertions. The important features of such a +collective assertion are that it fails if any of its constituent +assertions is executed and fails, and that the first constituent +assertion to fail terminates execution of the collective +assertion. Such behavior is essential to specifying a test case. + +

Test Case

+ +A test case is the unit of test execution. That is, +distinct test cases are executed independently. The failure of +one is independent of the failure of any other. +

+A test case consists of a single, possibly collective, +assertion. The possibly multiple constituent assertions in a +test case's collective assertion are not independent. +Their interdependence may be crucial to specifying correct operation +for a test. A test case may involve a series of steps, each +concluding in an assertion, where each step must succeed in order for +the test case to continue. As another example, a test may +require some "set up" to be performed that must be undone ("torn down" +in JUnit parlance) once the test is complete. In this case, you +could use Haskell's IO.bracket function to achieve the +desired effect. +

+You can make a test case from an assertion by applying the +TestCase constructor. For example, +(TestCase (return ())) is a test case that never +fails, and +(TestCase (assertEqual "for x," 3 x)) +is a test case that checks that the value of x is 3.  +Additional ways to create test cases are described later under +Advanced Features. + +

Tests

+ +As soon as you have more than one test, you'll want to name them to +tell them apart. As soon as you have more than several tests, +you'll want to group them to process them more easily. So, +naming and grouping are the two keys to managing collections of tests. +

+In tune with the "composite" design pattern [1], a test is defined as a package +of test cases. Concretely, a test is either a single test case, +a group of tests, or either of the first two identified by a label. +

+    data Test = TestCase Assertion
+              | TestList [Test]
+              | TestLabel String Test
+
+There are three important features of this definition to note: +
    +
  • +A TestList consists of a list of tests rather than a list of +test cases. This means that the structure of a Test is +actually a tree. Using a hierarchy helps organize tests just as +it helps organize files in a file system. +
    • +
  • +A TestLabel is attached to a test rather than to a test +case. This means that all nodes in the test tree, not just test +case (leaf) nodes, can be labeled. Hierarchical naming helps +organize tests just as it helps organize files in a file system. +
    • +
  • +A TestLabel is separate from both TestCase and +TestList. This means that labeling is optional +everywhere in the tree. Why is this a good thing? Because of +the hierarchical structure of a test, each constituent test case is +uniquely identified by its path in the tree, ignoring all +labels. Sometimes a test case's path (or perhaps its subpath +below a certain node) is a perfectly adequate "name" for the test case +(perhaps relative to a certain node). In this case, creating a +label for the test case is both unnecessary and inconvenient. +
    • +
+

+The number of test cases that a test comprises can be computed with +testCaseCount. +

+    testCaseCount :: Test -> Int
+
+

+As mentioned above, a test is identified by its path in the +test hierarchy. +

+    data Node  = ListItem Int | Label String
+      deriving (Eq, Show, Read)
+
+    type Path = [Node]    -- Node order is from test case to root.
+
+Each occurrence of TestList gives rise to a ListItem +and each occurrence of TestLabel gives rise to a +Label. The ListItems by themselves ensure +uniqueness among test case paths, while the Labels allow you +to add mnemonic names for individual test cases and collections of +them. +

+Note that the order of nodes in a path is reversed from what you might +expect: The first node in the list is the one deepest in the +tree. This order is a concession to efficiency: It allows common +path prefixes to be shared. +

+The paths of the test cases that a test comprises can be computed with +testCasePaths. The paths are listed in the order in +which the corresponding test cases would be executed. +

+    testCasePaths :: Test -> [Path]
+
+

+The three variants of Test can be constructed simply by +applying TestCase, TestList, and TestLabel +to appropriate arguments. Additional ways to create tests are +described later under Advanced +Features. +

+The design of the type Test provides great conciseness, +flexibility, and convenience in specifying tests. Moreover, the +nature of Haskell significantly augments these qualities: +

    +
  • +Combining assertions and other code to construct test cases is easy +with the IO monad. +
    • +
  • +Using overloaded functions and special operators (see below), +specification of assertions and tests is extremely compact. +
    • +
  • +Structuring a test tree by value, rather than by name as in JUnit, +provides for more convenient, flexible, and robust test suite +specification. In particular, a test suite can more easily be +computed "on the fly" than in other test frameworks. +
    • +
  • +Haskell's powerful abstraction facilities provide unmatched support +for test refactoring. +
    • +
+ +

Advanced Features

+ +HUnit provides additional features for specifying assertions and tests +more conveniently and concisely. These facilities make use of +Haskell type classes. +

+The following operators can be used to construct assertions. +

+    infix 1 @?, @=?, @?=
+
+    (@?) :: (AssertionPredicable t) => t -> String -> Assertion
+    pred @? msg = assertionPredicate pred >>= assertBool msg
+
+    (@=?) :: (Eq a, Show a) => a -> a -> Assertion
+    expected @=? actual = assertEqual "" expected actual
+
+    (@?=) :: (Eq a, Show a) => a -> a -> Assertion
+    actual @?= expected = assertEqual "" expected actual
+
+You provide a boolean condition and failure message separately to +(@?), as for assertBool, but in a different +order. The (@=?) and (@?=) operators provide +shorthands for assertEqual when no preface is required. +They differ only in the order in which the expected and actual values +are provided. (The actual value--the uncertain one--goes on the +"?" side of the operator.) +

+The (@?) operator's first argument is something from which an +assertion predicate can be made, that is, its type must be +AssertionPredicable. +

+    type AssertionPredicate = IO Bool
+
+    class AssertionPredicable t
+     where assertionPredicate :: t -> AssertionPredicate
+
+    instance AssertionPredicable Bool
+     where assertionPredicate = return
+
+    instance (AssertionPredicable t) => AssertionPredicable (IO t)
+     where assertionPredicate = (>>= assertionPredicate)
+
+The overloaded assert function in the Assertable +type class constructs an assertion. +
+    class Assertable t
+     where assert :: t -> Assertion
+
+    instance Assertable ()
+     where assert = return
+
+    instance Assertable Bool
+     where assert = assertBool ""
+
+    instance (ListAssertable t) => Assertable [t]
+     where assert = listAssert
+
+    instance (Assertable t) => Assertable (IO t)
+     where assert = (>>= assert)
+
+The ListAssertable class allows assert to be applied +to [Char] (that is, String). +
+    class ListAssertable t
+     where listAssert :: [t] -> Assertion
+
+    instance ListAssertable Char
+     where listAssert = assertString
+
+With the above declarations, (assert ()), +(assert True), and (assert "") (as well as +IO forms of these values, such as (return ())) +are all assertions that never fail, while (assert False) +and (assert "some failure message") (and their +IO forms) are assertions that always fail. You may +define additional instances for the type classes Assertable, +ListAssertable, and AssertionPredicable if that +should be useful in your application. +

+The overloaded test function in the Testable type +class constructs a test. +

+    class Testable t
+     where test :: t -> Test
+
+    instance Testable Test
+     where test = id
+
+    instance (Assertable t) => Testable (IO t)
+     where test = TestCase . assert
+
+    instance (Testable t) => Testable [t]
+     where test = TestList . map test
+
+The test function makes a test from either an +Assertion (using TestCase), a list of +Testable items (using TestList), or a Test +(making no change). +

+The following operators can be used to construct tests. +

+    infix  1 ~?, ~=?, ~?=
+    infixr 0 ~:
+
+    (~?) :: (AssertionPredicable t) => t -> String -> Test
+    pred ~? msg = TestCase (pred @? msg)
+
+    (~=?) :: (Eq a, Show a) => a -> a -> Test
+    expected ~=? actual = TestCase (expected @=? actual)
+
+    (~?=) :: (Eq a, Show a) => a -> a -> Test
+    actual ~?= expected = TestCase (actual @?= expected)
+
+    (~:) :: (Testable t) => String -> t -> Test
+    label ~: t = TestLabel label (test t)
+
+(~?), (~=?), and (~?=) each make an +assertion, as for (@?), (@=?), and (@?=), +respectively, and then a test case from that assertion. +(~:) attaches a label to something that is +Testable. You may define additional instances for the +type class Testable should that be useful. + +

Running Tests

+ +HUnit is structured to support multiple test controllers. The +first subsection below describes the test +execution characteristics common to all test controllers. +The second subsection describes the +text-based controller that is +included with HUnit. + +

Test Execution

+ +All test controllers share a common test execution model. They +differ only in how the results of test execution are shown. +

+The execution of a test (a value of type Test) involves the +serial execution (in the IO monad) of its constituent test +cases. The test cases are executed in a depth-first, +left-to-right order. During test execution, four counts of test +cases are maintained: +

+    data Counts = Counts { cases, tried, errors, failures :: Int }
+      deriving (Eq, Show, Read)
+
+
    +
  • +cases is the number of test cases included in the test. +This number is a static property of a test and remains unchanged +during test execution. +
    • +
  • +tried is the number of test cases that have been executed so +far during the test execution. +
    • +
  • +errors is the number of test cases whose execution ended with +an unexpected exception being raised. Errors indicate problems +with test cases, as opposed to the code under test. +
    • +
  • +failures is the number of test cases whose execution asserted +failure. Failures indicate problems with the code under test. +
    • +
+Why is there no count for test case successes? The technical reason +is that the counts are maintained such that the number of test case +successes is always equal to +(tried - (errors + failures)). The +psychosocial reason is that, with test-centered development and the +expectation that test failures will be few and short-lived, attention +should be focused on the failures rather than the successes. +

+As test execution proceeds, three kinds of reporting event are +communicated to the test controller. (What the controller does +in response to the reporting events depends on the controller.) +

    +
  • +start -- +Just prior to initiation of a test case, the path of the test case and +the current counts (excluding the current test case) are reported. +
    • +
  • +error -- +When a test case terminates with an error, the error message is +reported, along with the test case path and current counts (including +the current test case). +
    • +
  • +failure -- +When a test case terminates with a failure, the failure message is +reported, along with the test case path and current counts (including +the current test case). +
    • +
+Typically, a test controller shows error and failure +reports immediately but uses the start report merely to update +an indication of overall test execution progress. + +

Text-Based Controller

+ +A text-based test controller is included with HUnit. +
+    runTestText :: PutText st -> Test -> IO (Counts, st)
+
+runTestText is generalized on a reporting scheme given +as its first argument. During execution of the test given as its +second argument, the controller creates a string for each reporting +event and processes it according to the reporting scheme. When +test execution is complete, the controller returns the final counts +along with the final state for the reporting scheme. +

+The strings for the three kinds of reporting event are as follows. +

    +
  • +A start report is the result of the function +showCounts applied to the counts current immediately prior to +initiation of the test case being started. +
    • +
  • +An error report is of the form +"Error in:   path\nmessage", +where path is the path of the test case in error, as shown by +showPath, and message is a message describing the +error. If the path is empty, the report has the form +"Error:\nmessage". +
    • +
  • +A failure report is of the form +"Failure in: path\nmessage", where +path is the path of the test case in error, as shown by +showPath, and message is the failure message. If +the path is empty, the report has the form +"Failure:\nmessage". +
    • +
+

+The function showCounts shows a set of counts. +

+    showCounts :: Counts -> String
+
+The form of its result is +"Cases: cases  Tried: tried  Errors: errors  Failures: failures" +where cases, tried, errors, and failures +are the count values. +

+The function showPath shows a test case path. +

+    showPath :: Path -> String
+
+The nodes in the path are reversed (so that the path reads from the +root down to the test case), and the representations for the nodes are +joined by ':' separators. The representation for +(ListItem n) is (show n). The +representation for (Label label) is normally +label. However, if label contains a colon or if +(show label) is different from label surrounded +by quotation marks--that is, if any ambiguity could exist--then +(Label label) is represented as (show +label). +

+HUnit includes two reporting schemes for the text-based test +controller. You may define others if you wish. +

+    putTextToHandle :: Handle -> Bool -> PutText Int
+
+putTextToHandle writes error and failure reports, plus a +report of the final counts, to the given handle. Each of these +reports is terminated by a newline. In addition, if the given +flag is True, it writes start reports to the handle as +well. A start report, however, is not terminated by a +newline. Before the next report is written, the start report is +"erased" with an appropriate sequence of carriage return and space +characters. Such overwriting realizes its intended effect on +terminal devices. +
+    putTextToShowS :: PutText ShowS
+
+putTextToShowS ignores start reports and simply accumulates +error and failure reports, terminating them with newlines. The +accumulated reports are returned (as the second element of the pair +returned by runTestText) as a ShowS function (that +is, one with type (String -> String)) whose first +argument is a string to be appended to the accumulated report lines. +

+HUnit provides a shorthand for the most common use of the text-based +test controller. +

+    runTestTT :: Test -> IO Counts
+
+runTestTT invokes runTestText, specifying +(putTextToHandle stderr True) for the reporting scheme, and +returns the final counts from the test execution. + +

Constituent Files

+ +HUnit 1.0 consists of the following files. +
+ +
doc/Guide.html +
+This document. +
examples/Example.hs +
+Haskell module that includes the examples given in the Getting Started section. Run this +program to make sure you understand how to use HUnit. +
Test/HUnit.lhs +
+Haskell module that you import to use HUnit. +
Test/HUnit/Base.lhs +
+Haskell module that defines HUnit's basic facilities. +
Test/HUnit/Lang.lhs +
+Haskell module that defines how assertion failure is signaled and +caught. By default, it is a copy of +Test/HUnit/Lang98.lhs. Replace it by a copy of +Test/HUnit/LangExtended.lhs for more robust exception behavior. +
Test/HUnit/Lang98.lhs +
+Haskell module that defines generic assertion failure handling.  +It is compliant to Haskell 98 but catches only IO errors. +
Test/HUnit/LangExtended.lhs +
+Haskell module that defines more robust assertion failure +handling. It catches more (though unfortunately not all) kinds +of exceptions. However, it works only with Hugs (Dec. 2001 or +later) and GHC (5.00 and later). +
examples/test/HUnitTest98.lhs +
+Haskell module that tests HUnit, assuming the generic assertion +failure handling of HUnitLang98.lhs. +
examples/test/HUnitTestBase.lhs +
+Haskell module that defines testing support and basic (Haskell 98 +compliant) tests of HUnit (using HUnit, of course!). Contains +more extensive and advanced examples of testing with HUnit. +
examples/test/HUnitTestExtended.lhs +
+Haskell module that tests HUnit, assuming the extended assertion +failure handling of HUnitLangExc.lhs. +
Test/HUnit/Text.lhs +
+Haskell module that defines HUnit's text-based test controller. +
LICENSE +
+The license for use of HUnit. +
Test/HUnit/Terminal.lhs +
+Haskell module that assists in checking the output of HUnit tests +performed by the text-based test controller. +
examples/test/TerminalTest.lhs +
+Haskell module that tests Test/HUnit/Terminal.lhs (using HUnit, of +course!). +
+ +

References

+ +
+ +
+[1] Gamma, E., et al. Design Patterns: +Elements of Reusable Object-Oriented Software, Addison-Wesley, +Reading, MA, 1995. +
+The classic book describing design patterns in an object-oriented +context. + +
+http://www.junit.org +
+Web page for JUnit, the tool after which HUnit is modeled. + +
+ +http://junit.sourceforge.net/doc/testinfected/testing.htm +
+A good introduction to test-first development and the use of JUnit. + +
+ +http://junit.sourceforge.net/doc/cookstour/cookstour.htm +
+A description of the internal structure of JUnit. Makes for an +interesting comparison between JUnit and HUnit. + +
+ +

+

+ +The HUnit software and this guide were written by Dean Herington +(heringto@cs.unc.edu). + +

+HUnit development is supported by + +SourceForge.net Logo + + + diff --git a/examples/Example.hs b/examples/Example.hs new file mode 100644 --- /dev/null +++ b/examples/Example.hs @@ -0,0 +1,37 @@ +-- Example.hs -- Examples from HUnit user's guide + +module Main where + +import Test.HUnit + + +foo :: Int -> (Int, Int) +foo x = (1, x) + +partA :: Int -> IO (Int, Int) +partA v = return (v+2, v+3) + +partB :: Int -> IO Bool +partB v = return (v > 5) + +test1 :: Test +test1 = TestCase (assertEqual "for (foo 3)," (1,2) (foo 3)) + +test2 :: Test +test2 = TestCase (do (x,y) <- partA 3 + assertEqual "for the first result of partA," 5 x + b <- partB y + assertBool ("(partB " ++ show y ++ ") failed") b) + +tests :: Test +tests = TestList [TestLabel "test1" test1, TestLabel "test2" test2] + +tests' :: Test +tests' = test [ "test1" ~: "(foo 3)" ~: (1,2) ~=? (foo 3), + "test2" ~: do (x, y) <- partA 3 + assertEqual "for the first result of partA," 5 x + partB y @? "(partB " ++ show y ++ ") failed" ] + +main :: IO Counts +main = do runTestTT tests + runTestTT tests' diff --git a/examples/Makefile b/examples/Makefile new file mode 100644 --- /dev/null +++ b/examples/Makefile @@ -0,0 +1,27 @@ +# ----------------------------------------------------------------------------- + +TOP = ../.. +include $(TOP)/mk/boilerplate.mk + +# ----------------------------------------------------------------------------- + +ifeq "$(way)" "" +SUBDIRS = test + +EXAMPLES := $(wildcard *.hs) +BINS := $(addsuffix $(exeext),$(EXAMPLES:.hs=)) +CLEAN_FILES += $(BINS) + +HC = $(GHC_INPLACE) +MKDEPENDHS = $(GHC_INPLACE) +SRC_HC_OPTS += -Wall -package HUnit + +all:: $(BINS) + +$(BINS): %$(exeext): %.o + $(HC) -o $@ $(HC_OPTS) $(LD_OPTS) $< +endif + +# ----------------------------------------------------------------------------- + +include $(TOP)/mk/target.mk diff --git a/examples/test/HUnitTest98.lhs b/examples/test/HUnitTest98.lhs new file mode 100644 --- /dev/null +++ b/examples/test/HUnitTest98.lhs @@ -0,0 +1,9 @@ +HUnitTest98.lhs -- test for HUnit, using Haskell language system "98" + +> module Main (main) where + +> import Test.HUnit +> import HUnitTestBase + +> main :: IO Counts +> main = runTestTT (test [baseTests]) diff --git a/examples/test/HUnitTestBase.lhs b/examples/test/HUnitTestBase.lhs new file mode 100644 --- /dev/null +++ b/examples/test/HUnitTestBase.lhs @@ -0,0 +1,373 @@ +HUnitTestBase.lhs -- test support and basic tests (Haskell 98 compliant) + +> module HUnitTestBase where + +> import Test.HUnit +> import Test.HUnit.Terminal (terminalAppearance) +> import System.IO (IOMode(..), openFile, hClose) + + +> data Report = Start State +> | Error String State +> | UnspecifiedError State +> | Failure String State +> deriving (Show, Read) + +> instance Eq Report where +> Start s1 == Start s2 = s1 == s2 +> Error m1 s1 == Error m2 s2 = m1 == m2 && s1 == s2 +> Error m1 s1 == UnspecifiedError s2 = s1 == s2 +> UnspecifiedError s1 == Error m2 s2 = s1 == s2 +> UnspecifiedError s1 == UnspecifiedError s2 = s1 == s2 +> Failure m1 s1 == Failure m2 s2 = m1 == m2 && s1 == s2 +> _ == _ = False + + +> expectReports :: [Report] -> Counts -> Test -> Test +> expectReports reports counts test = TestCase $ do +> (counts', reports') <- performTest (\ ss us -> return (Start ss : us)) +> (\m ss us -> return (Error m ss : us)) +> (\m ss us -> return (Failure m ss : us)) +> [] test +> assertEqual "for the reports from a test," reports (reverse reports') +> assertEqual "for the counts from a test," counts counts' + + +> simpleStart = Start (State [] (Counts 1 0 0 0)) + +> expectSuccess :: Test -> Test +> expectSuccess = expectReports [simpleStart] (Counts 1 1 0 0) + +> expectProblem :: (String -> State -> Report) -> Int -> String -> Test -> Test +> expectProblem kind err msg = +> expectReports [simpleStart, kind msg (State [] counts)] counts +> where counts = Counts 1 1 err (1-err) + +> expectError, expectFailure :: String -> Test -> Test +> expectError = expectProblem Error 1 +> expectFailure = expectProblem Failure 0 + +> expectUnspecifiedError :: Test -> Test +> expectUnspecifiedError = expectProblem (\ msg st -> UnspecifiedError st) 1 undefined + + +> data Expect = Succ | Err String | UErr | Fail String + +> expect :: Expect -> Test -> Test +> expect Succ test = expectSuccess test +> expect (Err m) test = expectError m test +> expect UErr test = expectUnspecifiedError test +> expect (Fail m) test = expectFailure m test + + + +> baseTests = test [ assertTests, +> testCaseCountTests, +> testCasePathsTests, +> reportTests, +> textTests, +> showPathTests, +> showCountsTests, +> assertableTests, +> predicableTests, +> compareTests, +> extendedTestTests ] + + +> ok = test (assert ()) +> bad m = test (assertFailure m) + + +> assertTests = test [ + +> "null" ~: expectSuccess ok, + +> "userError" ~: +> expectError "error" (TestCase (ioError (userError "error"))), + +> "IO error (file missing)" ~: +> expectUnspecifiedError +> (test (do openFile "3g9djs" ReadMode; return ())), + + "error" ~: + expectError "error" (TestCase (error "error")), + + "tail []" ~: + expectUnspecifiedError (TestCase (tail [] `seq` return ())), + + -- GHC doesn't currently catch arithmetic exceptions. + "div by 0" ~: + expectUnspecifiedError (TestCase ((3 `div` 0) `seq` return ())), + +> "assertFailure" ~: +> let msg = "simple assertFailure" +> in expectFailure msg (test (assertFailure msg)), + +> "assertString null" ~: expectSuccess (TestCase (assertString "")), + +> "assertString nonnull" ~: +> let msg = "assertString nonnull" +> in expectFailure msg (TestCase (assertString msg)), + +> let exp v non = +> show v ++ " with " ++ non ++ "null message" ~: +> expect (if v then Succ else Fail non) $ test $ assertBool non v +> in "assertBool" ~: [ exp v non | v <- [True, False], non <- ["non", ""] ], + +> let msg = "assertBool True" +> in msg ~: expectSuccess (test (assertBool msg True)), + +> let msg = "assertBool False" +> in msg ~: expectFailure msg (test (assertBool msg False)), + +> "assertEqual equal" ~: +> expectSuccess (test (assertEqual "" 3 3)), + +> "assertEqual unequal no msg" ~: +> expectFailure "expected: 3\n but got: 4" +> (test (assertEqual "" 3 4)), + +> "assertEqual unequal with msg" ~: +> expectFailure "for x,\nexpected: 3\n but got: 4" +> (test (assertEqual "for x," 3 4)) + +> ] + + +> emptyTest0 = TestList [] +> emptyTest1 = TestLabel "empty" emptyTest0 +> emptyTest2 = TestList [ emptyTest0, emptyTest1, emptyTest0 ] +> emptyTests = [emptyTest0, emptyTest1, emptyTest2] + +> testCountEmpty test = TestCase (assertEqual "" 0 (testCaseCount test)) + +> suite0 = (0, ok) +> suite1 = (1, TestList []) +> suite2 = (2, TestLabel "3" ok) +> suite3 = (3, suite) + +> suite = +> TestLabel "0" +> (TestList [ TestLabel "1" (bad "1"), +> TestLabel "2" (TestList [ TestLabel "2.1" ok, +> ok, +> TestLabel "2.3" (bad "2") ]), +> TestLabel "3" (TestLabel "4" (TestLabel "5" (bad "3"))), +> TestList [ TestList [ TestLabel "6" (bad "4") ] ] ]) + +> suiteCount = (6 :: Int) + +> suitePaths = [ +> [Label "0", ListItem 0, Label "1"], +> [Label "0", ListItem 1, Label "2", ListItem 0, Label "2.1"], +> [Label "0", ListItem 1, Label "2", ListItem 1], +> [Label "0", ListItem 1, Label "2", ListItem 2, Label "2.3"], +> [Label "0", ListItem 2, Label "3", Label "4", Label "5"], +> [Label "0", ListItem 3, ListItem 0, ListItem 0, Label "6"]] + +> suiteReports = [ Start (State (p 0) (Counts 6 0 0 0)), +> Failure "1" (State (p 0) (Counts 6 1 0 1)), +> Start (State (p 1) (Counts 6 1 0 1)), +> Start (State (p 2) (Counts 6 2 0 1)), +> Start (State (p 3) (Counts 6 3 0 1)), +> Failure "2" (State (p 3) (Counts 6 4 0 2)), +> Start (State (p 4) (Counts 6 4 0 2)), +> Failure "3" (State (p 4) (Counts 6 5 0 3)), +> Start (State (p 5) (Counts 6 5 0 3)), +> Failure "4" (State (p 5) (Counts 6 6 0 4))] +> where p n = reverse (suitePaths !! n) + +> suiteCounts = Counts 6 6 0 4 + +> suiteOutput = "### Failure in: 0:0:1\n\ +> \1\n\ +> \### Failure in: 0:1:2:2:2.3\n\ +> \2\n\ +> \### Failure in: 0:2:3:4:5\n\ +> \3\n\ +> \### Failure in: 0:3:0:0:6\n\ +> \4\n\ +> \Cases: 6 Tried: 6 Errors: 0 Failures: 4\n" + + +> suites = [suite0, suite1, suite2, suite3] + + +> testCount (num, test) count = +> "testCaseCount suite" ++ show num ~: +> TestCase $ assertEqual "for test count," count (testCaseCount test) + +> testCaseCountTests = TestList [ + +> "testCaseCount empty" ~: test (map testCountEmpty emptyTests), + +> testCount suite0 1, +> testCount suite1 0, +> testCount suite2 1, +> testCount suite3 suiteCount + +> ] + + +> testPaths (num, test) paths = +> "testCasePaths suite" ++ show num ~: +> TestCase $ assertEqual "for test paths," +> (map reverse paths) (testCasePaths test) + +> testPathsEmpty test = TestCase $ assertEqual "" [] (testCasePaths test) + +> testCasePathsTests = TestList [ + +> "testCasePaths empty" ~: test (map testPathsEmpty emptyTests), + +> testPaths suite0 [[]], +> testPaths suite1 [], +> testPaths suite2 [[Label "3"]], +> testPaths suite3 suitePaths + +> ] + + +> reportTests = "reports" ~: expectReports suiteReports suiteCounts suite + + +> expectText counts text test = TestCase $ do +> (counts', text') <- runTestText putTextToShowS test +> assertEqual "for the final counts," counts counts' +> assertEqual "for the failure text output," text (text' "") + + +> textTests = test [ + +> "lone error" ~: +> expectText (Counts 1 1 1 0) +> "### Error:\nxyz\nCases: 1 Tried: 1 Errors: 1 Failures: 0\n" +> (test (do ioError (userError "xyz"); return ())), + +> "lone failure" ~: +> expectText (Counts 1 1 0 1) +> "### Failure:\nxyz\nCases: 1 Tried: 1 Errors: 0 Failures: 1\n" +> (test (assert "xyz")), + +> "putTextToShowS" ~: +> expectText suiteCounts suiteOutput suite, + +> "putTextToHandle (file)" ~: +> let filename = "HUnitTest.tmp" +> trim = unlines . map (reverse . dropWhile (== ' ') . reverse) . lines +> in map test +> [ "show progress = " ++ show flag ~: do +> handle <- openFile filename WriteMode +> (counts, _) <- runTestText (putTextToHandle handle flag) suite +> hClose handle +> assertEqual "for the final counts," suiteCounts counts +> text <- readFile filename +> let text' = if flag then trim (terminalAppearance text) else text +> assertEqual "for the failure text output," suiteOutput text' +> | flag <- [False, True] ] + +> ] + + +> showPathTests = "showPath" ~: [ + +> "empty" ~: showPath [] ~?= "", +> ":" ~: showPath [Label ":", Label "::"] ~?= "\"::\":\":\"", +> "\"\\\n" ~: showPath [Label "\"\\n\n\""] ~?= "\"\\\"\\\\n\\n\\\"\"", +> "misc" ~: showPath [Label "b", ListItem 2, ListItem 3, Label "foo"] ~?= +> "foo:3:2:b" + +> ] + + +> showCountsTests = "showCounts" ~: showCounts (Counts 4 3 2 1) ~?= +> "Cases: 4 Tried: 3 Errors: 2 Failures: 1" + + + +> lift :: a -> IO a +> lift a = return a + + +> assertableTests = +> let assertables x = [ +> ( "", assert x , test (lift x)) , +> ( "IO ", assert (lift x) , test (lift (lift x))) , +> ( "IO IO ", assert (lift (lift x)), test (lift (lift (lift x))))] +> assertabled l e x = +> test [ test [ "assert" ~: pre ++ l ~: expect e $ test $ a, +> "test" ~: pre ++ "IO " ++ l ~: expect e $ t ] +> | (pre, a, t) <- assertables x ] +> in "assertable" ~: [ +> assertabled "()" Succ (), +> assertabled "True" Succ True, +> assertabled "False" (Fail "") False, +> assertabled "\"\"" Succ "", +> assertabled "\"x\"" (Fail "x") "x" +> ] + + +> predicableTests = +> let predicables x m = [ +> ( "", assertionPredicate x , x @? m, x ~? m ), +> ( "IO ", assertionPredicate (l x) , l x @? m, l x ~? m ), +> ( "IO IO ", assertionPredicate (l(l x)), l(l x) @? m, l(l x) ~? m )] +> l x = lift x +> predicabled l e m x = +> test [ test [ "pred" ~: pre ++ l ~: m ~: expect e $ test $ tst p, +> "(@?)" ~: pre ++ l ~: m ~: expect e $ test $ a, +> "(~?)" ~: pre ++ l ~: m ~: expect e $ t ] +> | (pre, p, a, t) <- predicables x m ] +> where tst p = p >>= assertBool m +> in "predicable" ~: [ +> predicabled "True" Succ "error" True, +> predicabled "False" (Fail "error") "error" False, +> predicabled "True" Succ "" True, +> predicabled "False" (Fail "" ) "" False +> ] + + +> compareTests = test [ + +> let succ = const Succ +> compare f exp act = test [ "(@=?)" ~: expect e $ test (exp @=? act), +> "(@?=)" ~: expect e $ test (act @?= exp), +> "(~=?)" ~: expect e $ exp ~=? act, +> "(~?=)" ~: expect e $ act ~?= exp ] +> where e = f $ "expected: " ++ show exp ++ "\n but got: " ++ show act +> in test [ +> compare succ 1 1, +> compare Fail 1 2, +> compare succ (1,'b',3.0) (1,'b',3.0), +> compare Fail (1,'b',3.0) (1,'b',3.1) +> ] + +> ] + + +> expectList1 :: Int -> Test -> Test +> expectList1 c = +> expectReports +> [ Start (State [ListItem n] (Counts c n 0 0)) | n <- [0..c-1] ] +> (Counts c c 0 0) + +> expectList2 :: [Int] -> Test -> Test +> expectList2 cs test = +> expectReports +> [ Start (State [ListItem j, ListItem i] (Counts c n 0 0)) +> | ((i,j),n) <- zip coords [0..] ] +> (Counts c c 0 0) +> test +> where coords = [ (i,j) | i <- [0 .. length cs - 1], j <- [0 .. cs!!i - 1] ] +> c = testCaseCount test + + +> extendedTestTests = test [ + +> "test idempotent" ~: expect Succ $ test $ test $ test $ ok, + +> "test list 1" ~: expectList1 3 $ test [assert (), assert "", assert True], + +> "test list 2" ~: expectList2 [0, 1, 2] $ test [[], [ok], [ok, ok]] + +> ] diff --git a/examples/test/HUnitTestExtended.lhs b/examples/test/HUnitTestExtended.lhs new file mode 100644 --- /dev/null +++ b/examples/test/HUnitTestExtended.lhs @@ -0,0 +1,38 @@ +HUnitTestExc.lhs -- test for HUnit, using Haskell language system "Exc" + +> module Main (main) where + +> import Test.HUnit +> import HUnitTestBase + + import qualified Control.Exception (assert) + + assertionMessage = "HUnitTestExc.lhs:13: Assertion failed\n" + assertion = Control.Exception.assert False (return ()) + + +> main :: IO Counts +> main = runTestTT (test [baseTests, excTests]) + +> excTests :: Test +> excTests = test [ + + -- Hugs and GHC don't currently catch arithmetic exceptions. + "div by 0" ~: + expectUnspecifiedError (TestCase ((3 `div` 0) `seq` return ())), + + -- GHC doesn't currently catch array-related exceptions. + "array ref out of bounds" ~: + expectUnspecifiedError (TestCase (... `seq` return ())), + +> "error" ~: +> expectError "error" (TestCase (error "error")), + +> "tail []" ~: +> expectUnspecifiedError (TestCase (tail [] `seq` return ())) + + -- Hugs doesn't provide `assert`. + "assert" ~: + expectError assertionMessage (TestCase assertion) + +> ] diff --git a/examples/test/Makefile b/examples/test/Makefile new file mode 100644 --- /dev/null +++ b/examples/test/Makefile @@ -0,0 +1,29 @@ +# ----------------------------------------------------------------------------- + +TOP = ../../.. +include $(TOP)/mk/boilerplate.mk + +# ----------------------------------------------------------------------------- + +EXAMPLES := $(filter-out HUnitTestBase.lhs,$(wildcard *.lhs)) +BINS := $(addsuffix $(exeext),$(EXAMPLES:.lhs=)) +CLEAN_FILES += $(BINS) + +HC = $(GHC_INPLACE) +MKDEPENDHS = $(GHC_INPLACE) +SRC_HC_OPTS += -Wall -package HUnit + +all:: $(BINS) + +USES_HUNITTESTBASE := $(EXAMPLES:.lhs=) + +.PRECIOUS: HUnitTestBase.o +$(addsuffix .o,$(USES_HUNITTESTBASE)): HUnitTestBase.hi +$(addsuffix $(exeext),$(USES_HUNITTESTBASE)): HUnitTestBase.o + +$(BINS): %$(exeext): %.o + $(HC) -o $@ $(HC_OPTS) $(LD_OPTS) $< $(patsubst %,HUnitTestBase.o,$(filter $(<:.o=),$(USES_HUNITTESTBASE))) + +# ----------------------------------------------------------------------------- + +include $(TOP)/mk/target.mk diff --git a/examples/test/TerminalTest.lhs b/examples/test/TerminalTest.lhs new file mode 100644 --- /dev/null +++ b/examples/test/TerminalTest.lhs @@ -0,0 +1,24 @@ +TerminalTest.lhs + +> import Test.HUnit.Terminal +> import Test.HUnit + +> main :: IO Counts +> main = runTestTT tests + +> try :: String -> String -> String -> Test +> try lab inp exp' = lab ~: terminalAppearance inp ~?= exp' + +> tests :: Test +> tests = test [ +> try "empty" "" "", +> try "end in \\n" "abc\ndef\n" "abc\ndef\n", +> try "not end in \\n" "abc\ndef" "abc\ndef", +> try "return 1" "abc\ndefgh\rxyz" "abc\nxyzgh", +> try "return 2" "\nabcdefgh\rijklm\rxy\n" "\nxyklmfgh\n", +> try "return 3" "\r\rabc\r\rdef\r\r\r\nghi\r\r\n" "def\nghi\n", +> try "back 1" "abc\bdef\b\bgh\b" "abdgh", +> try "back 2" "abc\b\b\bdef\b\bxy\b\b\n" "dxy\n" +> -- \b at beginning of line +> -- nonprinting char +> ] diff --git a/prologue.txt b/prologue.txt new file mode 100644 --- /dev/null +++ b/prologue.txt @@ -0,0 +1,2 @@ +HUnit is a unit testing framework for Haskell, inspired by the JUnit +tool for Java, see: .