inspection-testing: GHC plugin to do inspection esting

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

Some carefully crafted libraries make promises to their users beyond functionality and performance.

Examples are: Fusion libraries promise intermediate data structures to be eliminated. Generic programming libraries promise that the generic implementation is identical to the hand-written one. Some libraries may promise allocation-free or branch-free code.

Conventionally, the modus operandi in all these cases is that the library author manually inspects the (intermediate or final) code produced by the compiler. This is not only tedious, but makes it very likely that some change, either in the library itself or the surrounding eco-system, breaks the library’s promised without anyone noticing.

This package provides a disciplined way of specifying such properties, and have them checked by the compiler. This way, this checking can be part of the ususal development cycle and regressions caught early.

See the documentation in Test.Inspection or the project webpage for more examples and more information.


[Skip to Readme]

Properties

Versions 0.1, 0.1, 0.1.1, 0.1.1.1, 0.1.1.2, 0.1.2, 0.2, 0.2.0.1, 0.3, 0.4, 0.4.1, 0.4.1.1, 0.4.1.2, 0.4.2, 0.4.2.1, 0.4.2.2, 0.4.2.4, 0.4.3.0, 0.4.4.0, 0.4.5.0, 0.4.6.0, 0.4.6.1, 0.5, 0.5.0.1, 0.5.0.2, 0.5.0.3
Change log ChangeLog.md
Dependencies base (>=4.9 && <4.12), containers, ghc (>=8.0.2 && <8.4), template-haskell [details]
License MIT
Copyright 2017 Joachim Breitner
Author Joachim Breitner
Maintainer mail@joachim-breitner.de
Category Testing, Compiler Plugin
Home page https://github.com/nomeata/inspection-testing
Source repo head: git clone git://github.com/nomeata/inspection-testing.git
Uploaded by JoachimBreitner at 2017-11-09T23:56:43Z

Modules

[Index]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for inspection-testing-0.1

[back to package description]

Inspection Testing for Haskell

This GHC plugin allows you to embed assertions about the intermediate code into your Haskell code, and have them checked by GHC. This is called inspection testing (as it automates what you do when you manually inspect the intermediate code).

Synopsis

See the Test.Inspection module for the documentation, but there really isn't much more to it than:

{-# LANGAUGE TemplateHaskell #-}
{-# OPTIONS_GHC -O -fplugin Test.Inspection.Plugin #-}
module Simple where

import Test.Inspection
import Data.Maybe

lhs, rhs :: (a -> b) -> Maybe a -> Bool
lhs f x = isNothing (fmap f x)
rhs f Nothing = True
rhs f (Just _) = False

inspect $ 'lhs === 'rhs

If you compile this, you will reassurringly read:

$ ghc Simple.hs
[1 of 1] Compiling Simple           ( Simple.hs, Simple.o )
examples/Simple.hs:14:1: inspecting lhs === rhs
Test.Inspection tested 1 obligation

See the examples/ directory for more examples of working proofs.

If an assertion fails, for example

bad1, bad2 :: Int
bad1 = 2 + 2
bad2 = 5

inspect $ 'bad1 === 'bad2

then the compiler will tell you so, and abort the compilation:

$ ghc Simple.hs
[1 of 1] Compiling Simple           ( Simple.hs, Simple.o )
examples/Simple.hs:20:1: inspecting bad1 === bad2
Obligation fails
    LHS: ghc-prim-0.5.1.0:GHC.Types.I# 4#
    RHS: ghc-prim-0.5.1.0:GHC.Types.I# 5#
examples/Simple.hs: error: inspection testing unsuccessful

What can I check for

Currently, inspection-testing supports

Possible further applications includes

Let me know if you need any of these, or have further ideas.

Can I comment or help?

Sure! We can use the GitHub issue tracker for discussions, and obviously contributions are welcome.