Safe Haskell	None
Language	Haskell2010

Test.Database.Hasql

Contents

Running tests
Explain tests

Description

An interface for testing hasql queries. As hasql is pretty low level library and does not provide additional checks in compile time we are intered if the queries are well formed from the database point of view.

This library provides a number of tests that helps to check that the basic properties are held. In order to run the tests the library provides helpers for running the temporary database.

Synopsis

startupPostgres :: ByteString -> IO DB
startupPostgresInit :: (Connection -> IO ()) -> IO DB
teardownPostgres :: DB -> IO ()
allocateConnection :: DB -> IO Connection
freeConnection :: Connection -> IO ()
data InitException
explain :: Arbitrary input => Statement input output -> Connection -> Expectation

Running tests

The library if the test-framework agnostic so it provides only the basic commands that can be used in order to run the tests using diferrent frameworks.

For example using tasty + tasty-hunit one can do:

import Test.Tasty
import Test.Tasty.HUnit

main = defaultMain $
  withResource (startupPostgres) (teardownPostgres) $ mkDb ->
    withResource (mkDb >>= allocateConnection) (freeConnection) $ conn ->
      tests conn

tests :: IO HC.Connection -> TestGroup
tests mkConn = testGroup "explain-tests"
  [ testCase "select 1" $ mkConn >>= explain select1
  ]

startupPostgres :: ByteString -> IO DB Source #

Start and initialize temporary database using init script.

Accepts database initialization script that can contain multiple commands and is run in the separate transaction.

@throws: In case if the database initialization fails throws InitException.

startupPostgresInit :: (Connection -> IO ()) -> IO DB Source #

Start and initialize temporary database.

Accepts database initialization funciton from the user.

@throws: In case if the database initialization fails throws InitException in addition to any exception that could be thrown by the user function.

teardownPostgres :: DB -> IO () Source #

Teardown database and associated resources

allocateConnection :: DB -> IO Connection Source #

Allocates connection to the temporary database

freeConnection :: Connection -> IO () Source #

Frees connection to the temporary database

data InitException Source #

Possible exceptions that may happen during the initialization process

Constructors

InitException QueryError	Exception during running of the initialization script
ConnectException ConnectionError	Can't allocate connection to the local db
PostgresStartException StartError	We have failed to start temporary postgres.

Instances

Instances details

Show InitException Source #
Instance details Defined in Test.Database.Hasql Methods showsPrec :: Int -> InitException -> ShowS # show :: InitException -> String # showList :: [InitException] -> ShowS #
Exception InitException Source #
Instance details Defined in Test.Database.Hasql Methods toException :: InitException -> SomeException # fromException :: SomeException -> Maybe InitException # displayException :: InitException -> String #

Explain tests

Explain tests are the tests that are based on the idea to run explain on the query. It means that if we have some SQL query we run EXPLAIN $SQL and provide some variables. Then we check if this query succeeds.

If this test passes it guarantees:

that the query is well formed and that encoders works.

However it does not check:

If encoder works
Complexity of the query
Locks that the query holds

explain Source #

Arguments

:: Arbitrary input
=> Statement input output	Original statement
-> Connection	Connection to the database
-> Expectation

Runs explain test.

Note In order to run the query we need to substitute parameters, we chose to pass an arbitrary value (using quickcheck), however some values may miss the arbitrary instance, in such cases one can use lmap to map values from the ones that have this interface. I.e.

explain (lmap (() -> constValue) query)