Temporary workaround for gh-231
[packages/text.git] / tests-and-benchmarks.markdown
1 Tests and benchmarks
2 ====================
3
4 Prerequisites
5 -------------
6
7 To run the tests and benchmarks, you will need the test data, which
8 you can clone from one of the following locations:
9
10 * Mercurial master repository:
11   [bitbucket.org/bos/text-test-data](https://bitbucket.org/bos/text-test-data)
12
13 * Git mirror repository:
14   [github.com/bos/text-test-data](https://github.com/bos/text-test-data)
15
16 You can clone either repository into the `tests` subdirectory using
17
18     cd tests/
19     make text-test-data         # to clone from mercurial, OR
20     make VCS=git text-test-data # to clone from git
21
22 Many tests and benchmarks will fail if the test files are missing.
23
24 Functional tests
25 ----------------
26
27 The functional tests are located in the `tests` subdirectory. An overview of
28 what's in that directory:
29
30     Makefile          Has targets for common tasks
31     Tests             Source files of the testing code
32     scripts           Various utility scripts
33     text-tests.cabal  Cabal file that compiles all benchmarks
34
35 The `text-tests.cabal` builds:
36
37 - A copy of the text library, sharing the source code, but exposing all internal
38   modules, for testing purposes
39 - The different test suites
40
41 To compile, run all tests, and generate a coverage report, simply use `make`.
42
43 Benchmarks
44 ----------
45
46 The benchmarks are located in the `benchmarks` subdirectory. An overview of
47 what's in that directory:
48
49     Makefile               Has targets for common tasks
50     haskell                Source files of the haskell benchmarks
51     python                 Python implementations of some benchmarks
52     ruby                   Ruby implementations of some benchmarks
53     text-benchmarks.cabal  Cabal file which compiles all benchmarks
54
55 To compile the benchmarks, navigate to the `benchmarks` subdirectory and run
56 `cabal configure && cabal build`. Then, you can run the benchmarks using:
57
58     ./dist/build/text-benchmarks/text-benchmarks
59
60 Or if you have a recent enough `cabal`, you can build and run the
61 benchmarks via
62
63     cabal new-run exe:text-benchmarks -- --help
64
65 However, since there's quite a lot of benchmarks, you usually don't want to
66 run them all. Instead, use the `-l` flag to get a list of benchmarks
67 and run the ones you want to inspect. If you want to configure the benchmarks
68 further, the exact parameters can be changed in `Benchmarks.hs`.