git.iko.soy/streamly
on f2b2aa4 help sign in
streamly/test/README.md
158 lines 3.6 kB history raw
1# Streamly Tests
3## Running tests using bin/test.sh
5`bin/test.sh` (path relative to the top level repo dir) can run selected
6test groups, generate coverage report, pass GHC RTS options when
7running tests. `test.sh` runs the tests with restricted memory, see
8`bin/test.sh` source for details on the amount of memory used or to change it.
10To generate coverage report:
12```
13$ bin/test.sh --coverage
14```
16To view coverage report, open `./hpc_index.html` in browser.
18See `bin/test.sh --help` for more info.
20## Building and Running Tests using cabal
22### Build a single test
24```
25$ cabal build test:Prelude.Serial
26```
28or:
30```
31$ cd test; cabal build Prelude.Serial
32```
34Build with optimizations:
36```
37$ cabal build --flag opt ...
38```
40### Build all tests
42```
43$ cabal build --enable-tests all
44```
46or:
48```
49$ cd test; cabal build --enable-tests
50```
52Or this, note this command does not work as expected when in the "test" dir:
54```
55$ cabal build --enable-tests streamly-tests
56```
58### Build and run
60Running all test suites, use any of the following:
62```
63$ cabal test all
64```
66or:
68```
69$ cd test; cabal test
70```
72Or this, note this command does not work as expected when in the "test" dir:
74```
75$ cabal test streamly-tests
76```
78### Build and Run a single test suite
80To run `Prelude.Serial` test-suite:
82```
83$ cabal run test:Prelude.Serial
84```
86or:
88```
89$ cd test; cabal run Prelude.Serial
90```
92Note you could use `cabal test Prelude.Serial` but that unfortunately builds
93all the test suites before running `Prelude.Serial`.
95## Writing doctests
97* The test named `doctest` runs all the code snippets in a source module
98 that are written using the `>>>` markup in haddock. See `doctest.hs`.
99* Make sure you do not enclose your snippets in the `@ .. @` markup otherwise
100 they will show up verbatim in the docs and not as ghci styled snippets.
101* We use `--fast` mode of doctest, which means snippets are run as if you are
102 typing those examples from top to bottom in that order in GHCi. Previous
103 snippet's state is available to the next one.
104* A haddock section named `$setup` contains a snippet that is always run before
105 any other. When `--fast` mode is not used it is run before every snippet.
107An example setup section:
109```
110-- $setup
111-- >>> :m
112-- >>> import Control.Monad.IO.Class (MonadIO(..))
113-- >>> import Data.Function ((&))
114```
116Some tests that may take long can be written as follows. Just assigning
117the code to a function makes it compile but not run.
119```
120>>> :{
121main = do
122 Stream.drain $ Stream.fromAsync $ foldMap delay [1..10]
123 Stream.drain $ Stream.concatFoldableWith Stream.async (map delay [1..10])
124 Stream.drain $ Stream.concatMapFoldableWith Stream.async delay [1..10]
125 Stream.drain $ Stream.concatForFoldableWith Stream.async [1..10] delay
126:}
127```
129## Running doctests
131Run tests for all modules:
133```
134$ cabal run doctests --flag doctests
135```
137Use verbose mode to debug:
139```
140$ cabal run doctests --flag doctests -- --verbose
141```
143Run tests only for selected modules:
145```
146$ cabal run doctests --flag doctests -- --modules Streamly.Prelude
147```
149If it fails with a message that a particular modules is not loaded specify that
150module as well on the command line.
152## Naming of test modules
154Tests are organized by source modules. For example, for the source
155module `Streamly.Data.Array` and `Streamly.Internal.Data.Array` we have
156a test module `Data.Array`. For some modules tests for a source module
157are broken into multiple modules. For example, for `Streamly.Prelude` we have
158`Streamly.Prelude.Serial`, `Streamly.Prelude.Async` etc.