1This file describes the flex test suite.
2
3* WHO SHOULD USE THE TEST SUITE?
4
5The test suite is intended to be used by flex developers, i.e., anyone hacking
6the flex distribution. If you are simply installing flex, then you can ignore
7this directory and its contents.
8
9* STRUCTURE OF THE TEST SUITE
10
11The testsuite consists of several tests. Each test is centered around
12a scanner known to work with the most recent version of flex. In
13general, after you modify your copy of the flex distribution, you
14should re-run the test suite. Some of the tests may require certain
15tools to be available (e.g., bison, diff). If any test returns an
16error or generates an error message, then your modifications *may*
17have broken a feature of flex. At a minimum, you'll want to
18investigate the failure and determine if it's truly significant.
19
20* HOW TO RUN THE TEST SUITE
21
22To build and execute all tests from the top level of the flex source tree:
23
24  $ make check
25
26To build and execute a single test:
27
28  $ cd tests/ # from the top level of the flex tree.
29  $ make testname.log
30
31  where "testname" is the name of the test. This is an automake-ism
32  that will create (or re-create, if need be), a log of the particular
33  test run that you're working on.
34
35* HOW TO ADD A NEW TEST TO THE TEST SUITE
36
37** List your test in the TESTS variable in Makefile.am in this
38   directory. Note that due to the large number of tests, we use
39   variables to group similar tests together. This also helps with
40   handling the automake test suite requirements. Hopefully your test
41   can be listed in SIMPLE_TESTS. You'll need to add the appropriate
42   automake _SOURCES variable as well. If you're unsure, then consult
43   the automake manual, paying attention to the parallel test harness
44   section.
45
46** On success, your test should return zero.
47
48** On error, your test should return 1 (one) and print a message to
49stderr, which will have been redirected to the log file created by the
50automake test suite harness.
51
52** If your test is skipped (e.g., because bison was not found), then
53   the test should return 77 (seventy-seven). This is the exit status that
54   would be recognized by automake's "test-driver" as _skipped_.
55
56** Once your work is done, submit a patch via the flex development
57   mailing list, the github pull request mechanism or some other
58   suitable means.
59