Safe Haskell	None
Language	Haskell2010

Genesis.Test.Persist

Description

This module provides withGlobalPostgresqlConn, a function that parameterizes a global reference to a PostgreSQL database, dbConn. This is intended for use in test code that does not need a connection pool and simply needs to execute functions against a database. It also provides postgresOptions, an envparse Parser for PostgresOptions, which makes it easy to configure the PostgreSQL connection via the environment.

If you use hspec, you should wrap your top-level test execution with withGlobalPostgresqlConn to properly set the global connection during the dynamic scope of your tests and ensure the database is rolled back after each test, then use runDB in your tests to utilize the global connection.

Example:

 main :: IO ()
 main = do
   opts <- parse (header "test suite") postgresOptions
   withGlobalPostgresqlConn opts $
     hspec spec

 spec :: Spec
 spec = describe "GET /foo" $ do
   it "should produce a Foo" $ dbExample $ do
     let foo = Foo { fooBar = "baz" }
     fooId <- insert foo
     result <- getFoo (FooId 1)
     result `shouldBe` foo

Synopsis

Documentation

runDB :: MonadBaseControl IO m => SqlPersistT m a -> m a Source #

Runs a computation that may interact with a database using the global database context, then rolls back the transaction once the computation has completed. This is intended to be wrapped around a single test case to create a self-contained test that interacts with the database.

If you are using hspec, the dbExample helper may be more useful and concise, but this function is provided for uses that fall outside of simple hspec examples.

runDBCommit :: MonadBaseControl IO m => SqlPersistT m a -> m a Source #

Like runDB, except that the transaction is commited after running instead of rolled back (unless an exception is raised, in which case the transaction is rolled back, anyway). You should avoid this in test code to avoid creating tests that dependent on the database state, but it can be useful to run migrations, for example.

dbExample :: SqlPersistT IO () -> Expectation Source #

A helper function that combines example with runDB. This can be used with it to create a test case which has access to the database within its body:

 spec = describe "the database" $
   it "holds records" $ dbExample $ do
     ...

When using this function, you should most likely also use Genesis.Test.Hspec instead of Test.Hspec to avoid unnecessarily lifting of assertions.

dbConn :: (HasCallStack, MonadBaseControl IO m) => m SqlBackend Source #

Low-level access to the global database connection. If the global connection does not exist (that is, you are not in the dynamic extent of a call to withGlobalPostgresqlConn), this will raise an exception.

withGlobalPostgresqlConn :: MonadBaseControl IO m => PostgresOptions -> m a -> m a Source #

Parameterizes the global database connection, dbConn, within the dynamic extent of its execution. The connection is started within a transaction.