Test.Database.Hasql

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.

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

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

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 ()

Teardown database and associated resources

allocateConnection :: DB -> IO Connection

Allocates connection to the temporary database

freeConnection :: Connection -> IO ()

Frees connection to the temporary database

data InitException

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

Show InitException

Defined in Test.Database.Hasql

Methods

showsPrec :: Int -> InitException -> ShowS

show :: InitException -> String

showList :: [InitException] -> ShowS

Exception InitException

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:

1. that the query is well formed and that encoders works.

However it does not check:

1. If encoder works
2. Complexity of the query
3. Locks that the query holds

explain

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)