A library, an executable and a test suite
One package, three components
A package that is more than a script has a library with the code, an executable that is a thin wrapper around it, and a test suite that exercises the library without the program. Cabal calls the three components of the package, and each has its own stanza in the .cabal file and its own build folder under dist-newstyle/.
shop/
├── shop.cabal
├── src/Shop/Price.hs
├── app/Main.hs
└── test/Spec.hs
The split is what makes the test suite cheap: it depends on the library and not on the executable, so it does not run the program to check a function. The next lesson runs this suite and breaks it on purpose; this one builds it.
The .cabal file
cabal-version: 3.0
name: shop
version: 0.1.0.0
build-type: Simple
library
exposed-modules: Shop.Price
hs-source-dirs: src
build-depends: base
default-language: Haskell2010
executable shop
main-is: Main.hs
hs-source-dirs: app
build-depends: base, shop
default-language: Haskell2010
test-suite shop-test
type: exitcode-stdio-1.0
main-is: Spec.hs
hs-source-dirs: test
build-depends: base, shop
default-language: Haskell2010
Three details carry the structure:
- exposed-modules is the public interface of the library. A module that is not listed is still compiled but only the listed ones are importable from another package.
- build-depends: base, shop in the executable and the test suite is the dependency on the library of the same package.
- type: exitcode-stdio-1.0 means the suite is a program that exits with 0 for success and anything else for failure, which is the test interface this course uses.
The library module
The module does the work: a price with tax and a string for pence. It imports nothing beyond base and exports two functions:
module Shop.Price (withTax, formatPence) where
withTax :: Int -> Int
withTax pence = pence + pence `div` 5
formatPence :: Int -> String
formatPence pence = show (pence `div` 100) ++ "." ++ pad (show (pence `mod` 100))
where
pad [d] = ['0', d]
pad ds = ds
The path is src/Shop/Price.hs because the module is Shop.Price, and hs-source-dirs: src is what makes the compiler look under src/.
The executable
module Main (main) where
import Shop.Price (formatPence, withTax)
main :: IO ()
main = mapM_ (putStrLn . formatPence . withTax) [100, 250, 999]
The program is a composition and a loop: three prices go through the tax and the formatter and come out as three lines. All the arithmetic is in the library, which is what the test suite checks.
The test suite
An exitcode-stdio-1.0 suite is a program with a main whose exit status is the verdict. This one prints a line per check and exits with 1 if any of them failed:
module Main (main) where
import Shop.Price (formatPence, withTax)
import System.Exit (exitFailure, exitSuccess)
check :: String -> Bool -> IO Bool
check label ok = do
putStrLn ((if ok then "ok " else "FAIL ") ++ label)
pure ok
main :: IO ()
main = do
results <-
sequence
[ check "100 with tax" (withTax 100 == 120)
, check "format 120" (formatPence 120 == "1.20")
, check "format 5" (formatPence 5 == "0.05")
]
if and results then exitSuccess else exitFailure
sequence runs the three checks in order and collects the booleans, and and decides the exit. The ok column is padded to five characters so the failures line up with the successes, the same trick the formatting lesson used with printf.
build, run and test
cabal build --offline
Warning: The package list for 'hackage.haskell.org' does not exist. Run 'cabal
update' to download it.
Resolving dependencies...
Build profile: -w ghc-9.10.3 -O1
In order, the following will be built (use -v for more details):
- shop-0.1.0.0 (lib) (first run)
- shop-0.1.0.0 (exe:shop) (first run)
Configuring library for shop-0.1.0.0...
Preprocessing library for shop-0.1.0.0...
Building library for shop-0.1.0.0...
[1 of 1] Compiling Shop.Price ( src/Shop/Price.hs, dist-newstyle/build/x86_64-linux/ghc-9.10.3/shop-0.1.0.0/build/Shop/Price.o, dist-newstyle/build/x86_64-linux/ghc-9.10.3/shop-0.1.0.0/build/Shop/Price.dyn_o )
Configuring executable 'shop' for shop-0.1.0.0...
Preprocessing executable 'shop' for shop-0.1.0.0...
Building executable 'shop' for shop-0.1.0.0...
[1 of 1] Compiling Main ( app/Main.hs, dist-newstyle/build/x86_64-linux/ghc-9.10.3/shop-0.1.0.0/x/shop/build/shop/shop-tmp/Main.o )
[2 of 2] Linking dist-newstyle/build/x86_64-linux/ghc-9.10.3/shop-0.1.0.0/x/shop/build/shop/shop
The library is built once and both other components compile against it, so the shared code is not compiled three times. The test suite is not part of build: Cabal builds it when test asks for it.
cabal run --offline shop
1.20
3.00
11.98
100 pence with tax is 120 and prints as 1.20, and 999 pence is 1198, which is 11.98. The numbers are the library's answer, not the program's, which is why the suite below can check them without starting the executable.
cabal test --offline
Build profile: -w ghc-9.10.3 -O1
In order, the following will be built (use -v for more details):
- shop-0.1.0.0 (test:shop-test) (first run)
Configuring test suite 'shop-test' for shop-0.1.0.0...
Preprocessing test suite 'shop-test' for shop-0.1.0.0...
Building test suite 'shop-test' for shop-0.1.0.0...
[1 of 1] Compiling Main ( test/Spec.hs, dist-newstyle/build/x86_64-linux/ghc-9.10.3/shop-0.1.0.0/t/shop-test/build/shop-test/shop-test-tmp/Main.o )
[2 of 2] Linking dist-newstyle/build/x86_64-linux/ghc-9.10.3/shop-0.1.0.0/t/shop-test/build/shop-test/shop-test
Running 1 test suites...
Test suite shop-test: RUNNING...
ok 100 with tax
ok format 120
ok format 5
Test suite shop-test: PASS
1 of 1 test suites (1 of 1 test cases) passed.
Between the PASS line and the last line Cabal prints the absolute path of the log file under dist-newstyle/; it is left out here because it depends on where the project sits. The suite prints its three lines because Cabal runs it with the terminal attached, and the PASS is Cabal's reading of the exit status, not the suite's own words. The next lesson makes a check fail and shows what Cabal does then.
Exercises
- Add a formatPence case for a negative amount and a check for it in the suite.
- Add a second module to the library and list it in exposed-modules.
- Move the test driver into a module of its own under test/ and list it in other-modules.
- Change build-depends: base to base, containers and use a Map in the library.
- Run cabal test --offline twice and explain the second run.
- Explain why the test suite depends on the library and not on the executable.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What are the three components of the package in this lesson?
Answer
A library, an executable and a test suite
The .cabal file has a library, executable and test-suite stanza.
-
What does
exposed-moduleslist?Answer
The modules another package may import
Only the exposed modules are part of the public interface of the library.
-
What does
type: exitcode-stdio-1.0mean for a test suite?Answer
The suite is a program whose exit status is the verdict
This interface runs the suite as a program and reads its exit status.
-
What does this program print?
module Main (main) where main :: IO () main = print (sum [1, 2, 3 :: Int])Answer
6
The sum of the three numbers is printed by print as 6.
-
Why does the test suite depend on
shopas well asbase?Answer
It imports the library module of the package
The suite imports Shop.Price, which is the library component named shop.
-
What does this program print?
module Main (main) where import System.Exit (exitSuccess) main :: IO () main = do putStrLn "done" exitSuccessAnswer
done
The line is printed and exitSuccess then ends the program with status 0.
-
When does Cabal build the test suite?
Answer
When a command such as
cabal testasks for itbuild builds the library and executables; test builds and runs the suite.
-
What does this program print?
module Main (main) where check :: Bool -> Bool check ok = ok main :: IO () main = putStrLn (if and (map check [True, True]) then "all ok" else "failures")Answer
all ok
Both checks are True, so and gives True and the first branch is printed.
-
Where do the library and the executable find their sources?
Answer
In the folders given by hs-source-dirs, here src and app
Each component declares its own hs-source-dirs, which is how src and app stay separate.
-
What does the
PASSline ofcabal testreport?Answer
The exit status of the suite program
Cabal reads the exit status of the exitcode-stdio suite and reports it as PASS or FAIL.
The code on this page was built with GHC 9.10.3 and cabal-install 3.16.0.0, and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev