1 files changed, 57 insertions, 0 deletions
diff --git a/tests/README b/tests/README
new file mode 100644
index 0000000..43387f4
--- /dev/null
+++ b/tests/README
@@ -0,0 +1,57 @@
+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 2 (two).
+
+** Once your work is done, submit a patch via the flex development
+   mailing list, the github pull request mechanism or some other
+   suitable means.