git.iko.soy/streamly
on 63407dc help sign in
streamly/docs/Developer/Tests.md
139 lines 3.0 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* We use `cabal-docspec` to run all the code snippets in a source module
98 that are written using the `>>>` markup in haddock.
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* A haddock section named `$setup` contains a snippet that is always run before
102 any other.
104An example setup section:
106```
107-- $setup
108-- >>> :m
109-- >>> import Control.Monad.IO.Class (MonadIO(..))
110-- >>> import Data.Function ((&))
111```
113Some tests that may take long can be written as follows. Just defining
114the snippet as a function makes it compile but not run.
116```
117>>> :{
118main = do
119 Stream.drain $ Stream.fromAsync $ foldMap delay [1..10]
120 Stream.drain $ Stream.concatFoldableWith Stream.async (map delay [1..10])
121 Stream.drain $ Stream.concatMapFoldableWith Stream.async delay [1..10]
122 Stream.drain $ Stream.concatForFoldableWith Stream.async [1..10] delay
123:}
124```
126## Running doctests
128```
129$ cabal build all
130$ cabal-docspec --timeout 60 --check-properties --property-variables xs
131```
133## Naming of test modules
135Tests are organized by source modules. For example, for the source
136module `Streamly.Data.Array.Generic` and `Streamly.Internal.Data.Array.Generic` we have
137a test module `Data.Array.Generic`. For some modules tests for a source module
138are broken into multiple modules. For example, for `Streamly.Prelude` we have
139`Streamly.Prelude.Serial`, `Streamly.Prelude.Async` etc.