This is part of a series on effect handling in Haskell using Polysemy

One of the benefits of writing pure code is that it’s so easy to test. You provide input, you get output, you assert on the output, that’s it. But “real world applications” have many functions with effects all over the place. And we also need to test those to ensure quality.

The problem is, how do you test effectful code? As the name indicates, naive tests would have various effects, rendering them “hard” to both write and run.

A solution particularly favored in languages with no clear effect boundary is to use ephemeral “containerized” environments, like Docker containers, to run their PostgreSQL databases, Kafka clusters, etc., during tests. These ephemeral containers lower the pain of testing effectful code, but with limited benefits: they remain slow and they are rather complex to write/maintain.

Another solution, when effectful code is well separated from business logic, is to mock the effects, i.e. to “replace” them with fake logic that suits each test exactly. These mocks usually have a greater LOC cost per test compared to containerized environments, but are extremely fast, and easier to maintain over time.

And guess what? Effect frameworks like Polysemy make it pretty simple to mock effects in tests.

Mocking effects

All we need to do to mock an effect is to change the interpreter layer! The effect declaration and the effect use in business code remain unchanged.

I will reuse the example from my previous post:

import Polysemy

data Log m a where
  LogInfo :: String -> Log m ()

makeSem ''Log

myBusinessFunction :: Member Log r => Integer -> Integer -> Sem r Integer
myBusinessFunction m n = do
  logInfo $ "myBusinessFunction was called with parameters " <> show m <> 
            " and " <> show n
  let result = m + n
  logInfo $ "myBusinessFunction result is " <> show result
  pure result

logToIO :: Member (Embed IO) r => Sem (Log ': r) a -> Sem r a
logToIO = interpret (\(LogInfo stringToLog) -> embed $ putStrLn stringToLog)

Step 1: No mocking

Let’s first write a test where the logging still happens in IO (logging to stdout):

import Polysemy

import Test.HUnit

test_1and2is3 = TestCase $ do
  result <- runM . logToIO $ myBusinessFunction 1 2
  result @?= 3

The test passes but stdout was polluted with the logs:

Cases: 1  Tried: 0  Errors: 0  Failures: 0myBusinessFunction was called with parameters 1 and 2
myBusinessFunction result is 3
Cases: 1  Tried: 1  Errors: 0  Failures: 0

Imagine when you have hundreds of tests running, your terminal (or your CI logs) will quickly get cluttered. Even worse: if our logging interpreter logged in a file, each test run would create and write into such a log file! This would also not scale well with other effects, like database calls.

We can do better.

Step 2: Disable logs

Our goal is to write tests for myBusinessFunction without actually logging to stdout.

Let’s write another interpreter logToSilence for the Log effect, except this interpreter will simply ignore the log and do nothing:

logToSilence :: Sem (Log ': r) a -> Sem r a
logToSilence = interpret (\(LogInfo _) -> pure ())

test_1and2is3 = TestCase $ do
  result <- runM . logToSilence $ myBusinessFunction 1 2
  result @?= 3

Now the logs are clean, the effect was nicely interpreted:

Cases: 1  Tried: 1  Errors: 0  Failures: 0

Note, we previously had to run in IO because logToIO required it. Our silencing interpreter is pure, though, so we can replace Polysemy’s runM with run and work with pure code:

test_1and2is3 = TestCase $
  let result = run . logToSilence $ myBusinessFunction 1 2
  in  result @?= 3

Step 3: Test effects too

Rather than silencing those logs, maybe logging is part of our requirements. In such case, we should actually check that the function logs correctly!

Let’s replace our silencing interpreter with another one, that records all logs, so that we can check exactly what was logged. We will rely on another pre-existing Polysemy effect, namely Polysemy.Writer, which is the Polysemy equivalent of Writer or WriterT.

Long story short, a Writer a effect allows you to write values of type a which will be glued together using mappend (thus the Monoid constraint). Note you can’t read those values as long as you are in code under this effect. Then when interpreting this effect, the result will be a pair of the resulting written a and the value returned by the effectful code. For our needs, a ~ [String], i.e. we record each log and we will get the list of all logged lines when interpreting this Writer [String] effect:

import Polysemy
import Polysemy.Writer

import Test.HUnit

logToRecord :: Member (Writer [String]) r => Sem (Log ': r) a -> Sem r a
logToRecord = interpret (\(LogInfo stringToLog) -> tell [stringToLog])

test_1and2is3 = TestCase $
  let (logs, result) = run . runWriter . logToRecord $ myBusinessFunction 1 2
  in do
      result @?= 3
      logs @?= [ "myBusinessFunction was called with parameters 1 and 2"
               , "myBusinessFunction result is 3" ]

So what’s going on here?

1. logToRecord interprets the Log effect in terms of Writer [String], i.e. we record all the logged lines as a list of strings (using tell from Polysemy.Writer to add logs)
2. We run this Writer effect using runWriter (this will aggregate all recorded logs thanks to the Monoid constraint, using list appending)
3. We can now assert both on the business result 3 and on the logged lines

That’s it! We have successfully removed the IO effect, our tests are pure, yet we can fully assert on both the business results and the effects!

Note: Technically we should use runWriterAssocR instead of runWriter since the monoid is a list, for performance reasons, but this is beyond the scope of this post.

It is exactly the same for property based tests (PBT). Say we want to (quick)check our business function is associative (on the result) and check that the last log will be the same (others will not because of order of application):

import Polysemy
import Polysemy.Writer

import Test.QuickCheck

logToRecord :: Member (Writer [String]) r => Sem (Log ': r) a -> Sem r a
logToRecord = interpret (\(LogInfo stringToLog) -> tell [stringToLog])

test_associative = \a b c ->
  let
    (logsAB_then_C, resultAB_then_C) = run . runWriter . logToRecord $ do
      resultAB <- myBusinessFunction a b
      myBusinessFunction resultAB c
    (logsA_then_BC, resultA_then_BC) = run . runWriter . logToRecord $ do
      resultBC <- myBusinessFunction b c
      myBusinessFunction a resultBC
   in
    last logsAB_then_C == last logsA_then_BC && resultAB_then_C == resultA_then_BC

You can find the full code example on my Github repo.

This first example showed how to change the interpreter to mock/record the effect behavior, but a major part of mocking effects is to return a dummy value instead of executing the effect to retrieve the value (e.g. database access or environment variable).

I think it’s interesting to showcase another example where the effect action has a return value other than ().

Intermediary example: environment variables

Let’s consider the use case of environment variable access.

Many applications need to read some global configuration, often passed by Kubernetes/Rancher through environment variables or secret files. A database URL, the logging level, a port number, an API key, you name it.

The effect declaration

import Polysemy

data Configuration m a where
  ReadConf :: String -> Configuration m (Maybe String)

makeSem ''Configuration

No surprise here. When you readConf, you have to pass the parameter name to read, and you get back a Maybe String (Nothing if the parameter is not configured).

The effect use in business code

import Data.Maybe
import Polysemy

myBusinessFunction :: Member Configuration r => Int -> Sem r (Either String Int)
myBusinessFunction amount = do
  maybeMinimumAmount <- fmap (fmap read) (readConf "MINIMUM_AMOUNT")
  let minimumAmount = fromMaybe 500 maybeMinimumAmount
  pure $ if amount >= minimumAmount
           then Right amount
           else Left $ show amount ++ " is lower than the minimum allowed amount " ++ show minimumAmount

This function reads the MINIMUM_AMOUNT configuration setting, or uses 500 as default value, then checks that the passed value is greater than or equal to the minimum amount.

Note: the double fmap may look weird, this is because we want to convert the resulting String to an Int but there are 2 layers to map over: IO and Maybe.

Again, the business code is not concerned with how the configuration is retrieved. Is it from an environment variable? A file? A cache? A hardcoded value? Or a combination of those? This decision is up to the interpreter!

The interpreters

This is an example of interpreter that reads from environment variables:

import System.Environment
import Polysemy

confToIO :: Member (Embed IO) r => Sem (Configuration ': r) a -> Sem r a
confToIO = interpret (\(ReadConf envVarName) -> embed $ lookupEnv envVarName)

Now let’s write a mock interpreter for our tests!

As stated in introduction, mocking means that each test gets to decide the behavior of effects. In this particular case, it means the decision of how to transform the configuration name (e.g. MINIMUM_AMOUNT) to a value (of type Maybe String) is up to each test, not to the interpreter.

Said differently, the interpreter should take as argument how to do this transformation.

In a functional language, it means: the interpreter should take as argument the function String -> Maybe String, and each test should pass such a function (the mock behavior).

confToMock :: (String -> Maybe String) -> Sem (Configuration ': r) a -> Sem r a
confToMock mockLookupEnv = interpret (\(ReadConf envVarName) -> pure $ mockLookupEnv envVarName)

And now a couple of unit tests showing how to use it:

import Test.HUnit

test_defaultMinimumAmount_lower = TestCase $
  let 
    mockLookupEnv _ = Nothing
    result = run . confToMock mockLookupEnv $ myBusinessFunction 400
  in 
    result @?= Left "400 is lower than the minimum allowed amount 500"

test_minimumAmount_greater = TestCase $
  let 
    mockLookupEnv "MINIMUM_AMOUNT" = Just "250"
    mockLookupEnv _                = Nothing
    result = run . confToMock mockLookupEnv $ myBusinessFunction 400
  in 
    result @?= Right 400

As you can see, each test provides the mocking function mockLookupEnv which is then injected in the interpreter.

You can find the full code example on my Github repo.

Conclusion

As shown in this post, testing (by mocking) is nice and inexpensive in Haskell with an effect framework like Polysemy.

The separation between effect declaration, effect use and effect interpretation is a big plus: tests only need to change the interpreter to mock effects, all other things remaining equal.

We have been using this technique for more than 6 months in my team, and we truly enjoy it. Most of us have experience with mocking techniques and frameworks in other languages (e.g. Java, JavaScript) but testing in Haskell with Polysemy is far more enjoyable, and by a long shot.

Remember: all the things shown here are loosely coupled to the testing libraries (HUnit and QuickCheck) and the effect library (Polysemy). You can achieve similar benefits with any testing or effect library that relies on the same separation of effect declaration, effect use and effect interpretation.

Enjoy testing!

This is part of a series on effect handling in Haskell using Polysemy

Setup

Let’s setup our project as documented in Polysemy readme beforehand (instructions are for Stack projects but I’m sure you will easily find the Cabal/Nix equivalent):

• Add polysemy and polysemy-plugin to our package.yaml dependencies
• Add the following to ghc-options:

- -fplugin=Polysemy.Plugin

• Add the following to default-extensions (we also add TemplateHaskell because we use it to reduce boilerplate):

- DataKinds
- FlexibleContexts
- GADTs
- LambdaCase
- PolyKinds
- RankNTypes
- ScopedTypeVariables
- TemplateHaskell
- TypeApplications
- TypeOperators
- TypeFamilies

Logging

A common need in any application is logging. Whether it’s technical logs to keep track of batch start/end (and result), audit logs about who did an admin action, or functional logs about a particular feature being used, it’s useful to find what happened in our beloved applications.

But logging is an effect! No matter if we send logs to standard output, a log file, or over the network, it has an effect on the world, other than mere processing.

Of course we could use a good ol’ IO and call it a day, but as explained in the previous post, IO is too coarse, we want more granularity. Instead, let’s create and use a Log effect!

Effect declaration

Let’s cut to the chase:

import Polysemy

data Log m a where
  LogInfo :: String -> Log m ()

makeSem ''Log

This is pretty dense already, let’s analyze bit by bit what’s going on!

data Log m a is our effect.

• Log is the effect name. This is the part that will appear in all our function signatures. Better pick a name that’s descriptive (and ideally not verbose) of the effect!
• m must always be there (you can guess the m stands for Monad but you don’t really need to know what it’s used for)
• () is the return type of the action. A logging action returns nothing, so we stick to Unit (())

LogInfo :: String -> Log m () is a possible action that has the Log effect. As you may have guessed, it is an action that takes a String to log, and will log it! Note we can have several actions under the same effect, but let’s start with one.

makeSem ''Log uses Template Haskell to create the logInfo function (same name as the action, but with the first letter changed to lowercase). We do not technically need this, but it saves us writing uninteresting boilerplate, so let’s stick with it.

In case you are curious, let’s check the type of this logInfo function:

> :type logInfo

logInfo :: 
   (IfStuck 
      (IndexOf r (Found r Log)) 
      (IfStuck r (TypeError ...) 
      (Pure (TypeError ...))) NoErrorFcf, 
   Find r Log, IndexOf r (Found r Log) ~ Log) 
 => String -> Sem r ()

You know what? Let’s pretend we never saw that. We don’t actually need to understand this (I don’t).

What if we display information about this function instead?

> :info logInfo

MemberWithError Log r => Text -> Sem r ()

which reads as “Give me a Text and I’ll give you a Sem monad with at least the Log effect”.

And that’s it! We have declared our logging effect. Remember, with effects, we split effect declaration and effect interpretation. This piece of code in no way explains how one should log. That is the whole point!

Effect use

Now that we have created our logging effect, let’s use it in our business code! Let’s say we currently have this piece of code:

myBusinessFunction :: Integer -> Integer -> IO Integer
myBusinessFunction m n = do
  putStrLn $ "myBusinessFunction was called with parameters " <> show m <> 
             " and " <> show n
  let result = m + n
  putStrLn $ "myBusinessFunction result is " <> show result
  pure result

IO is too coarse, we want to replace its use with our shiny new effect. Fear not, my friend, this is as simple as:

myBusinessFunction :: Member Log r => Integer -> Integer -> Sem r Integer
myBusinessFunction m n = do
  logInfo $ "myBusinessFunction was called with parameters " <> show m <> 
            " and " <> show n
  let result = m + n
  logInfo $ "myBusinessFunction result is " <> show result
  pure result

The main changes are:

• the constraint Member Log r which tells that r must have at least the Log effect (because we will use it in our implementation)
• the return type Sem r Integer which you can read as “A Polysemy monad with the list of effects r and which returns an Integer”. And the only thing we know (and we need to know) is that r has the Log effect. It may very well have a thousand other effects, or none, we don’t care in this business code. We declare the needed effects, not the exhaustive list of effects
• the use of logInfo (remember? It was generated thanks to makeSem ''Log in the effect declaration) to actually log stuff

This piece of code is much better. Now our business code better expresses its effects in the type signature (it logs, and cannot do anything else!), no longer has hardcoded the implementation (putStrLn), and we haven’t added any complexity to our code.

Now you might wonder “This is great, but at some point, somebody’s gotta do the actual logging with putStrLn!”.

Effect interpretation

This is where the real world catches on us. It’s time to explain how the Log effect must be interpreted in terms of putStrLn. Say the previous business code was consumed as such:

main :: IO ()
main = do
  m <- readLn :: IO Integer
  n <- readLn :: IO Integer
  result <- myBusinessFunction m n
  putStrLn $ "The business result is " <> show result

After the changes we did to myBusinessFunction this code no longer compiles, because myBusinessFunction works in the Sem monad while main works in the IO monad.

First, let’s write a function to interpret the Log effect in terms of IO:

logToIO :: Member (Embed IO) r => Sem (Log ': r) a -> Sem r a
logToIO = interpret (\(LogInfo stringToLog) -> embed $ putStrLn stringToLog)

There’s a lot going on! Don’t panic, as impressive as it may look the first time, you will soon get used to it.

• the Member (Embed IO) r constraint means r must have the ability to do IO. Ideally we would write Member IO r but since IO is not a Polysemy effect, we need to wrap it as an effect thanks to Embed. Note we require the IO effect because we want our main application to log using putStrLn. In our tests, we will write another interpreter with a pure function, thus we will not need to require the IO effect
• the Sem (Log ': r) a -> Sem r a type signature can be read as “I take a Sem monad which has any effect and the Log effect, and return the same Sem monad without that Log effect”, effectively meaning we are interpreting (destroying/consuming) the Log effect. Note, in more recent versions of Polysemy (unfortunately not yet available on Stackage), this type signature can be replaced with InterpreterFor Log r, which makes the function intention even clearer!
• note that the implementation does not explicitly mention the input argument (called pointfree style), this is how interpreters usually look
• interpret means what follows will be an interpreter
• since all we know about r is that it has the Log effect, we need to interpret only its actions (LogInfo)
• the (LogInfo stringToLog) pattern matching lets us capture the string to log when the action to interpret is LogInfo
• putStrLn stringToLog is the actual logging, however since its type is IO (), we need to wrap it back into our Sem monad, thanks to embed

Again, this usually is the toughest part to grasp. Don’t worry if it takes time to sink in. Wash, rinse, repeat.

Now we are able to convert a Sem monad with the Log effect to a Sem monad with the Embed IO effect. The last piece of the puzzle we need is to convert a Sem monad with IO to a good ol’ IO. Thankfully Polysemy already provides such a function, namely runM.

Let’s head back to our main function and explain to the compiler (and the reader) how one is supposed to interpret those hippie effects back into motherland IO:

main :: IO ()
main = do
  m <- readLn :: IO Integer
  n <- readLn :: IO Integer
  result <- runM . logToIO $ myBusinessFunction m n
  putStrLn $ "The business result is " <> show result

That’s it, our code was successfully migrated from monolithic effect IO to fine-grained Log effect! The additional noise is negligible and the benefit is already interesting, but the benefits increase tenfold in “real” applications with several effects, several actions per effect, several business functions calling each other, reinterpretations, and tests.

In my next blog post, I explain how to write tests for business functions with Polysemy effects.

You can find the full code example on my Github repo.

This is part of a series on effect handling in Haskell using Polysemy

Effect vs Side effect

Before I took on functional programming, I never made a difference between “effect” and “side effect”. Interestingly, there are many resources on side effects but few on effects. So let’s start with a few definitions:

• A function is a piece of software requiring 0, 1 or several parameters, and returning a value.
• A function has an effect when it has an observable interaction with the world outside of that function. Examples of effects are I/O (disk, network, keyboard, screen…), global variable or parameter mutation, program interruption, etc.
• A function has a side effect when it has an effect that was not described by the function - and thus, the caller of the function is unaware the program now has this effect!

Example of function having a side effect:

Integer foo(String input) {
    System.out.println("I am inside foo");
    return 42;
}

The caller is well aware this function takes a String as input and returns an Integer, but it has no idea the function will print something to the standard output without looking at its implementation. Requiring every developer to read through the implementation of each function, and each sub-function called by each function, and so on, obviously doesn’t scale to large programs. This leads to buggy, brittle programs that everybody fears maintaining.

Example of function having an effect which is not a side effect:

Integer foo(String input) throws CannotDoThatException {
    // ...
}

This function has an effect (program interruption through CannotDoThatException) which is definitely not hidden. The author knows very well this function can abruptly stop (and why) without looking at its implementation. This is much safer, and scales much better to programs.

Effects are awesome. A program is merely something that converts electricity into effects, be it a calculation result, a character displayed on your screen or your voice being recorded by a microphone.

I challenge you to write a useful program without effect.

Side effects, on the other hand, are evil. They creep throughout programs, the author or reader unaware of them, and may or may not have unintended consequences whenever they run.

And suddenly one can see why so many developers (myself included) confuse effects with side effects: most programming languages confuse them, too! Checked exceptions aside, Java treats all effects as side effects. Most of us have learnt and practiced unsafe programming for years because all of our effects (useful and intentional!) are side effects (hidden, untraceable, creeping).

And now the good news: some languages fully support and embrace effects, but make side effects impossible, resulting in safer programs for free! As an example, in Haskell, all functions having effects don’t return a value of type Foo, but of type IO Foo, meaning “This function ultimately returns a Foo but has effects along the way”. And all functions calling it also have to change their type from Bar to IO Bar to track the propagation of effects.

IO vs. Effect

Many Haskellers have a love-hate relationship with IO.

Love, because unlike most languages, Haskell programs “tag” functions with effects using IO, leading to programs that are easier to understand, and forcing developers to separate concerns between pure and impure functions.

Hate, because IO is binary: either a function has effects, or it has not, but you do not get much more information from IO. Whether an IO function writes to a file or launches a nuclear missile, you cannot tell by reading its type.

The thing is, Haskell developers love to carry as much information (and constraints) as possible in types. Everything the compiler checks, we don’t have to check them anymore (either through thinking or tests). So we want a finer granularity to identify and separate effects in the type system.

Various tactics have emerged through the years to carry more information about those effects: Monad transformers, MTL, freer-simple, fused-effects, etc.

And right now the new kid on the block is Polysemy.

As the readme states, Polysemy requires much less boilerplate than other solutions, and has a zero-cost performance (starting with GHC 8.10). An additional benefit I love - surprisingly it is not mentioned in the readme - is it becomes a lot easier to mock effects, and thus test functions with effects!

Let’s see how to get started with this new toy.

Polysemy basics

As I discussed in an issue I find the first Polysemy example quite complex and lacking explanations, which slowed me down in understanding how to make things work. I feel like code examples have more impact after a high level explanation of concepts. So here we go!

A Polysemy effect consists of 3 pieces of code:

1 - Effect declaration

This is where you describe the effect, its meaning, and what arguments need to be passed to “use” the effect in your business code.

Examples:

• Access the database
• Log
• Read configuration

2 - Effect uses

These are the various places in your business code where you need to use the effect.

Examples:

• Database
  • Select all users who play Squash
  • Update user “Julien Debon” to change his favorite sport from Volley-ball to Squash
• Log
  • Log as DEBUG whenever a price modification occurs
  • Log as ERROR when a payment fails
• Configuration
  • Read the environment property (dev / prod) to disable some features
  • Check if the bypassSecurity property is set (automation tests)

3 - Effect interpretation

This is where you explain how an effect should be “converted” into a real action. Typically this is where IO occurs.

Examples:

• Convert to a PostgreSQL query and send to the database pool
• Log to stdout or to a log file
• Read from the environment variables or a property file

Now that we better grasp the idea of Polysemy effects, let’s start writing code! Head to my next blog post for a first, simple example.