source: trunk/flex/tests/README@ 3040

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 test suite consists of several directories, each containing 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.
  $ cd test-pthread-nr # for example
  $ make test

* HOW TO ADD A NEW TEST TO THE TEST SUITE

**- RUN the script `create-test` found in this directory with a single
argument of the name of the test you want to create.  If it fails with
a message about a non-existent file `config.status', then run the
configure script in the top-level directory and everything will be
fine.  If it fails to work for you other than this, report it as a
bug.

** Modify the files in the newly created directory so that they test
whatever feature of flex you are interested in.

** 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 file named, "OUTPUT",
in your test's directory.

** If your test is skipped (e.g., because bison was not found), then
   the test should return 2 (two). See "test-bison-nr/Makefile.am" for
   an example.

** You must modify the last few lines of the top-level configure.in by
   adding the Makefile for your test directory.  (This step is
   done automatically by `create-test`.)

** You must add the name of your test to the SUBDIRS variable in
   tests/Makefile.am. (This is also done automatically for you by `create-test'.)

** Add a description of your new test to the end of the file
    `descriptions'. Remember to keep the description as brief as
    possible, preferably to one line.

** You will have to run the autogen.sh script in the top-level
   directory as well as run the configure script in that
   directory. (Note that running config.status may prove easier or
   quicker.)

** The easiest way for you to submit your new test to the flex
   maintainers is by generating a patch. The flex maintainers only
   need to have the Makefile.am, the flex input file, the test input
   file (if there is one) and any other files necessary to compile the
   test. You do not need to submit files generated by autoconf,
   automake, configure etc. It would be helpful to include the file
   .cvsignore which you will find in your test directory if you used
   the `create-test' script.