test-karya: Testing framework.

[ bsd3, haskell, library, program, test ] [ Propose Tags ]

This is Karya's test framework, extracted to be usable standalone.


[Skip to Readme]
Versions 0.0.1, 0.0.2, 0.0.3
Dependencies async, base (>=4.9 && <5), bytestring, containers, data-ordlist, deepseq, Diff, directory, filepath, ghc-prim, haskell-src, pcre-heavy (>=0.2), pcre-light (>=0.4), pretty, process, QuickCheck, test-karya, text, unix [details]
License BSD-3-Clause
Author Evan Laforge
Maintainer Evan Laforge <qdunkan@gmail.com>
Category Haskell, Test
Home page https://github.com/elaforge/test-karya
Source repo head: git clone git://github.com/elaforge/test-karya.git
Uploaded by EvanLaforge at Mon Oct 1 00:54:53 UTC 2018
Distributions NixOS:0.0.3
Executables test-karya-generate
Downloads 163 total (14 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2018-10-01 [all 1 reports]
Hackage Matrix CI

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for test-karya-0.0.3

[back to package description]

Some time before 2008 I needed to write tests for Haskell, specifically for what became https://github.com/elaforge/karya. At the time, I think HUnit existed, but it did stuff I didn't think I needed, such as manually arranging tests into a hierarchy, and didn't have stuff I thought I did, such as automatic test discovery, diffs, filename:linenumber for failed tests, etc. So I wrote my own.

Over the years some features became obsolete (e.g. ghc now supports filename:linenumber natively via call stacks), but I got used to this style of tests, so I decided to try to extract it for use in cabal projects.

Here's what I like:

  • Automatic test discovery. Tests are any functions named test_* in a module named *_test.hs. In Karya, I use shake to collect the tests, but in this cabal version, I borrowed the -pgmF technique from hspec.

  • Automatic test hierarchy. Tests are named by their module name, so you can run subsets by pattern matching on the name. You don't have to collect them into suites, and when running them you don't have to dig through the files to see what they named their suites.

  • Low syntax overhead tests. A test is any standalone function that calls test functions (like equal):

    module M_test where
    import EL.Test.Global
    import qualified M
    
    test_something = do
        let f = M.something
        equal (f 10) 20
        equal (f 20) 30
    

    Tests don't abort on failure, so you can put a bunch together with local definitions. There's no need to name each test case, the error message will tell you module and line number. Since test_something is a normal IO () function you can run it in ghci, which is how I mainly work.

  • Doesn't mess with stdout. A check, like the equal function, is any function that prints to stdout. A line starting with __-> is a failure. This was originally the simplest stupidest thing that could work, but over the last 10 years there was never a reason to change it, and it turns out to be convenient. Since test output is integrated into the stdout stream, it's in the right context with any debugging or logging.

  • Colored formatted diffs. When values don't match, they are pretty printed and differing parts highlighted.

  • Various other ad-hoc conveniences: equalFmt attaches a formatter so you can get higher level diffs, stringsLike for matching strings with patterns, equalf and ApproxEq typeclass for floating point, and quickcheck for quickcheck properties with formatted diffs.

how to use

See example, but the short version is:

  • Install library and test-karya-generate binary with cabal install.

  • Make a test module like M_test above.

  • Make RunTests.hs with {-# OPTIONS_GHC -F -pgmF test-karya-generate #-}

  • Add a test-suite stanza to the cabal file, like in example.

  • cabal test. You can rerun the tests with dist/build/test/test, run only M_test with dist/build/test/test M_test or pass --help for more options, including running tests in parallel.