f428cfeaafa01d3de9f71faace561ea58ec39c6a
[ghc.git] / testsuite / README
1 Running the test suite against a GHC build
2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3
4 NOTE: you need Python (any version >= 1.5 will probably do) in order
5 to use the testsuite.
6
7 To run the test suite against stage 1 of a GHC build in the same
8 source tree, first:
9
10         cd testsuite
11         make boot
12
13 This sets up the testsuite and builds the timeout tool which is used
14 when running tests.  Then:
15
16         cd tests/ghc-regress
17         make
18
19 (from now on, we'll assume that you're in the tests/ghc-regress
20 directory).
21
22 To run a fast version of the testsuite, which should complete in under
23 5 minutes on a fast machine with an optimised GHC build:
24
25         make fast
26
27 To run the testsuite with the stage2 compiler (this is often what you
28 want, because GHCi tests will fail with stage1):
29
30         make stage=2
31
32 To run the test suite against a different GHC, say ghc-5.04:
33
34         make TEST_HC=ghc-5.04
35
36 To run an individual test or tests (eg. tc054):
37
38         make TEST=tc054
39
40 (you can also go straight to the directory containing the test and say
41 'make TEST=tc054' from there, which will save some time).
42
43 To run the tests one particular way only (eg. GHCi):
44
45         make WAY=ghci
46         
47 For more details, see below.
48
49
50 Running the testsuite with a compiler other than GHC
51 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52
53 (to be written.  The plan is something like: 
54
55         cvs checkout fpconfig
56         cd fptools
57         cvs checkout testsuite
58         autoconf
59         ./configure
60         cd testsuite
61         make TEST_HC=nhc98 COMPILER=nhc98
62 )
63
64
65 Running individual tests or subdirectories of the testsuite
66 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
67
68 Most of the subdirectories in the testsuite have a Makefile.  In these
69 subdirectories you can use 'make' to run the test driver in two
70 ways:
71
72         make            -- run all the tests in the current directory
73         make accept     -- run the tests, accepting the current output
74
75 The following variables may be set on the make command line:
76
77         TESTS                   -- specific tests to run
78         TEST_HC                 -- compiler to use
79         EXTRA_HC_OPTS           -- extra flags to send to the Haskell compiler
80         EXTRA_RUNTEST_OPTS      -- extra flags to give the test driver
81         CONFIG                  -- use a different configuration file
82         COMPILER                -- stem of a different configuration file
83                                 -- from the config directory [default: ghc]
84         WAY                     -- just this way
85
86 The following ways are defined (for GHC, also see the file config/ghc):
87
88         normal                  -- no special options
89         opt                     -- -O
90         optasm                  -- -O -fasm
91         prof                    -- -O -prof -auto-all
92         profasm                 -- -O -prof -auto-all -fasm
93         unreg                   -- -unreg
94         ghci                    -- (run only, not compile) run test under GHCi
95         extcore                 -- -fext-core
96         optextcore              -- -O -fext-core
97         threaded                -- -threaded
98
99 certain ways are enabled automatically if the GHC build in the local
100 tree supports them.  Ways that are enabled this way are optasm, prof,
101 profasm, unreg, threaded, and ghci.
102
103
104 Updating tests when the output changes
105 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
106
107 If the output of a test has changed, but the new output is still
108 correct, you can automatically update the sample output to match the
109 new output like so:
110
111         make accept TESTS=<test-name>
112
113 where <test-name> is the name of the test.  In a directory which
114 contains a single test, or if you want to update *all* the tests in
115 the current directory, just omit the 'TESTS=<test-name>' part.
116
117
118 Adding a new test
119 ~~~~~~~~~~~~~~~~~
120
121 For a test which can be encapsulated in a single source file, follow
122 these steps:
123
124 1.  Find the appropriate place for the test.  The GHC regression suite
125     is generally organised in a "white-box" manner: a regression which
126     originally illustrated a bug in a particular part of the compiler
127     is placed in the directory for that part.  For example, typechecker
128     regression tests go in the typechecker/ directory, parser tests
129     go in parser/, and so on.  
130
131     It's not always possible to find a single best place for a test;
132     in those cases just pick one which seems reasonable.
133
134     Under each main directory may be up to three subdirectories:
135
136       - should_compile:  tests which need to compile only
137
138       - should_fail:     tests which should fail to compile
139                          and generate a particular error message
140
141       - should_run:      tests which should compile, run with
142                          some specific input, and generate a
143                          particular output.
144     
145     We don't always divide the tests up like this, and it's not
146     essential to do so (the directory names have no meaning as
147     far as the test driver is concerned).        
148
149
150 2.  Having found a suitable place for the test, give the test a name.
151     Follow the convention for the directory in which you place the
152     test: for example, in typecheck/should_compile, tests are named
153     tc001, tc002, and so on.  Suppose you name your test T, then
154     you'll have the following files:
155
156        T.hs      The source file containing the test
157
158        T.stdin   (for tests that run, and optional)
159                  A file to feed the test as standard input when it
160                  runs.
161
162        T.stdout  (for tests that run, and optional)
163                  For tests that run, this file is compared against
164                  the standard output generated by the program.  If 
165                  T.stdout does not exist, then the program must not
166                  generate anything on stdout.
167
168        T.stderr  (optional) For tests that run, this file is compared
169                  against the standard error generated by the program.
170
171                  For tests that compile only, this file is compared
172                  against the standard error output of the compiler,
173                  which is normalised to eliminate bogus differences
174                  (eg. absolute pathnames are removed, whitespace
175                  differences are ignored, etc.)
176
177
178 2.  Edit all.T in the relevant directory and add a line for the
179     test.  The line is always of the form
180
181       test(<name>, <opt-fn>, <test-fn>, <args>)
182
183     where
184
185       <name>    is the name of the test, in quotes (' or ").
186
187       <opt-fn> is a function (i.e. any callable object in Python)
188                 which allows the options for this test to be changed.
189                 There are several pre-defined functions which can be
190                 used in this field:
191
192                 normal                don't change any options from the defaults
193                 skip                  skip this test
194                 omit_ways(ways)       skip this test for certain ways
195                 only_ways(ways)       do this test certain ways only
196                 omit_compiler_types(compilers)
197                                       skip this test for certain compilers
198                 only_compiler_types(compilers)
199                                       do this test for certain compilers only
200                 expect_fail           this test is an expected failure
201                 expect_fail_for(ways) expect failure for certain ways 
202                 expect_fail_if_platform(plat)
203                                       expect failure on a certain platform
204                 expect_fail_if_compiler_type(compiler)
205                                       expect failure from a certain compiler
206                 set_stdin(file)       use a different file for stdin
207                 exit_code(n)          expect an exit code of 'n' from the prog
208                 extra_run_opts(opts)  pass some extra opts to the prog
209                 no_clean              don't clean up after this test
210
211                 you can compose two of these functions together by
212                 saying compose(f,g).  For example, to expect an exit
213                 code of 3 and omit way 'opt', we could use
214
215                      compose(omit_ways(['opt']), exit_code(3))
216
217                 as the <opt-fn> argument.  Calls to compose() can of
218                 course be nested.
219
220
221       <test-fn> is a function which describes how the test should be
222                 run, and determines the form of <args>.  The possible
223                 values are:
224
225                 compile         Just compile the program, the
226                                 compilation should succeed.
227
228                 compile_fail    Just compile the program, the
229                                 compilation should fail (error
230                                 messages will be in T.stderr).
231                                 
232                 compile_and_run 
233                                 Compile the program and run it,
234                                 comparing the output against the 
235                                 relevant files.
236
237                 multimod_compile
238                                 Compile a multi-module program
239                                 (more about multi-module programs
240                                 below).
241
242                 multimod_compile_fail
243                                 Compile a multi-module program,
244                                 and expect the compilation to fail
245                                 with error messages in T.stderr
246
247                 multimod_compile_and_run
248                                 Compile and run a multi-module
249                                 program.
250
251                 run_command
252                                 Just run an arbitrary command.  The
253                                 output is checked against T.stdout and
254                                 T.stderr, and the stdin and expected
255                                 exit code can be changed in the same
256                                 way as for compile_and_run.
257
258                 run_command_ignore_output
259                                 Same as run_command, except the output
260                                 (both stdout and stderr) from the
261                                 command is ignored.
262
263                 ghci_script
264                                 Runs the current compiler, passing
265                                 --interactive and using the specified
266                                 script as standard input.
267
268         <args>  is a list of arguments to be passed to <test-fn>.
269
270                 For compile, compile_fail and compile_and_run, <args>
271                 is a list with a single string which contains extra
272                 compiler options with which to run the test.  eg.
273                 
274                 test(tc001, normal, compile, ['-fglasgow-exts'])
275
276                 would pass the flag -fglasgow-exts to the compiler
277                 when compiling tc001.
278
279                 The multimod_ versions of compile and compile_and_run
280                 expect an extra argument on the front of the list: the
281                 name of the top module in the program to be compiled
282                 (usually this will be 'Main').
283
284
285 A multi-module test is straightforward.  It usually goes in a
286 directory of its own (although this isn't essential), and the source
287 files can be named anything you like.  The test must have a name, in
288 the same way as a single-module test; and the stdin/stdout/stderr
289 files follow the name of the test as before.  In the same directory,
290 place a file 'test.T' containing a line like
291
292    test(multimod001, normal, multimod_compile_and_run, \
293                  [ 'Main', '-fglasgow-exts', '', 0 ])
294
295 as described above.
296
297 For some examples, take a look in tests/ghc-regress/programs.
298
299
300 The details
301 ~~~~~~~~~~~
302
303 The test suite driver is just a set of Python scripts, as are all of
304 the .T files in the test suite.  The driver (driver/runtests.py) first
305 searches for all the .T files it can find, and then proceeds to
306 execute each one, keeping a track of the number of tests run, and
307 which ones succeeded and failed.
308
309 The script runtests.py takes several options:
310
311   --config <file>
312   
313        <file> is just a file containing Python code which is 
314        executed.   The purpose of this option is so that a file
315        containing settings for the configuration options can
316        be specified on the command line.  Multiple --config options
317        may be given.
318
319   --rootdir <dir>
320
321        <dir> is the directory below which to search for .T files
322        to run.
323
324   --output-summary <file>
325
326        In addition to dumping the test summary to stdout, also
327        put it in <file>.  (stdout also gets a lot of other output
328        when running a series of tests, so redirecting it isn't  
329        always the right thing).
330
331   --only <test>
332
333        Only run tests named <test> (multiple --only options can
334        be given).  Useful for running a single test from a .T file
335        containing multiple tests.
336
337   -e <stmt>
338
339        executes the Python statement <stmt> before running any tests.
340        The main purpose of this option is to allow certain
341        configuration options to be tweaked from the command line; for
342        example, the build system adds '-e config.accept=1' to the
343        command line when 'make accept' is invoked.
344
345 Most of the code for running tests is located in driver/testlib.py.
346 Take a look.
347
348 There is a single Python class (TestConfig) containing the global
349 configuration for the test suite.  It contains information such as the
350 kind of compiler being used, which flags to give it, which platform
351 we're running on, and so on.  The idea is that each platform and
352 compiler would have its own file containing assignments for elements
353 of the configuration, which are sourced by passing the appropriate
354 --config options to the test driver.  For example, the GHC
355 configuration is contained in the file config/ghc.
356
357 A .T file can obviously contain arbitrary Python code, but the general
358 idea is that it contains a sequence of calls to the function test(),
359 which resides in testlib.py.  As described above, test() takes four
360 arguments:
361
362       test(<name>, <opt-fn>, <test-fn>, <args>)
363
364 The function <opt-fn> is allowed to be any Python callable object,
365 which takes a single argument of type TestOptions.  TestOptions is a
366 class containing options which affect the way that the current test is
367 run: whether to skip it, whether to expect failure, extra options to
368 pass to the compiler, etc. (see testlib.py for the definition of the
369 TestOptions class).  The idea is that the <opt-fn> function modifies
370 the TestOptions object that it is passed.  For example, to expect
371 failure for a test, we might do this in the .T file:
372
373    def fn(opts):
374       opts.expect = 'fail'
375
376    test(test001, fn, compile, [''])
377
378 so when fn is called, it sets the instance variable "expect" in the
379 instance of TestOptions passed as an argument, to the value 'fail'.
380 This indicates to the test driver that the current test is expected to
381 fail.
382
383 Some of these functions, such as the one above, are common, so rather
384 than forcing every .T file to redefine them, we provide canned
385 versions.  For example, the provided function expect_fail does the
386 same as fn in the example above.  See testlib.py for all the canned
387 functions we provide for <opt-fn>.
388
389 The argument <test-fn> is a function which performs the test.  It
390 takes three or more arguments:
391
392       <test-fn>( <name>, <way>, ... )
393
394 where <name> is the name of the test, <way> is the way in which it is
395 to be run (eg. opt, optasm, prof, etc.), and the rest of the arguments
396 are constructed from the list <args> in the original call to test().
397 The following <test-fn>s are provided at the moment:
398
399            compile
400            compile_fail
401            compile_and_run
402            multimod_compile
403            multimod_compile_fail
404            multimod_compile_and_run
405            run_command
406            run_command_ignore_output
407            ghci_script
408
409 and obviously others can be defined.  The function should return
410 either 'pass' or 'fail' indicating that the test passed or failed
411 respectively.
412