| This file describes the flex test suite. |
| |
| * WHO SHOULD USE THE TEST SUITE? |
| |
| The test suite is intended to be used by flex developers, i.e., anyone hacking |
| the flex distribution. If you are simply installing flex, then you can ignore |
| this directory and its contents. |
| |
| * STRUCTURE OF THE TEST SUITE |
| |
| The testsuite consists of several tests. Each test is centered around |
| a scanner known to work with the most recent version of flex. In |
| general, after you modify your copy of the flex distribution, you |
| should re-run the test suite. Some of the tests may require certain |
| tools to be available (e.g., bison, diff). If any test returns an |
| error or generates an error message, then your modifications *may* |
| have broken a feature of flex. At a minimum, you'll want to |
| investigate the failure and determine if it's truly significant. |
| |
| * HOW TO RUN THE TEST SUITE |
| |
| To build and execute all tests from the top level of the flex source tree: |
| |
| $ make check |
| |
| To build and execute a single test: |
| |
| $ cd tests/ # from the top level of the flex tree. |
| $ make testname.log |
| |
| where "testname" is the name of the test. This is an automake-ism |
| that will create (or re-create, if need be), a log of the particular |
| test run that you're working on. |
| |
| * HOW TO ADD A NEW TEST TO THE TEST SUITE |
| |
| ** List your test in the TESTS variable in Makefile.am in this |
| directory. Note that due to the large number of tests, we use |
| variables to group similar tests together. This also helps with |
| handling the automake test suite requirements. Hopefully your test |
| can be listed in SIMPLE_TESTS. You'll need to add the appropriate |
| automake _SOURCES variable as well. If you're unsure, then consult |
| the automake manual, paying attention to the parallel test harness |
| section. |
| |
| ** On success, your test should return zero. |
| |
| ** On error, your test should return 1 (one) and print a message to |
| stderr, which will have been redirected to the log file created by the |
| automake test suite harness. |
| |
| ** If your test is skipped (e.g., because bison was not found), then |
| the test should return 77 (seventy-seven). This is the exit status that |
| would be recognized by automake's "test-driver" as _skipped_. |
| |
| ** Once your work is done, submit a patch via the flex development |
| mailing list, the github pull request mechanism or some other |
| suitable means. |