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