From 651e4b440ad3019a63b10d972ee36a296020e2c8 Mon Sep 17 00:00:00 2001
From: Neil <nyamatongwe@gmail.com>
Date: Sun, 22 Dec 2019 22:43:28 +1100
Subject: Lexilla testing framework.

---
 lexilla/test/README | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 lexilla/test/README

(limited to 'lexilla/test/README')

diff --git a/lexilla/test/README b/lexilla/test/README
new file mode 100644
index 000000000..119f08cf2
--- /dev/null
+++ b/lexilla/test/README
@@ -0,0 +1,65 @@
+README for testing lexers with lexilla/test.
+
+The TestLexers application is run to test the lexing of a set of example files
+and thus ensure that the lexers are working correctly.
+
+Lexers are accessed through the Lexilla shared library which must be built first
+in the lexilla/src directory.
+
+TestLexers works on Windows, Linux, or macOS and requires a C++20 compiler.
+MSVC 2019.4, GCC 9.0, Clang 9.0, and Apple Clang 11.0 are known to work.
+
+MSVC is only available on Windows.
+
+GCC and Clang work on Windows and Linux.
+
+On macOS, only Apple Clang is available.
+
+To use GCC run lexilla/test/makefile:
+	make test
+
+To use Clang run lexilla/test/makefile:
+	make CLANG=1 test
+On macOS, CLANG is set automatically so this can just be
+	make test
+
+To use MSVC:
+	nmake -f testlexers.mak test
+There is also a project file TestLexers.vcxproj that can be loaded into the Visual
+C++ IDE.
+
+
+
+Adding or Changing Tests
+
+The lexilla/test/examples directory contains a set of tests located in a tree of
+subdirectories.
+
+Each directory contains example files along with control files called
+SciTE.properties and expected result files with a .styled suffix.
+If an unexpected result occurs then files with the suffix .new may be created.
+
+Each file in the examples tree that does not have an extension of .properties, .styled, or
+.new is an example file that will be lexed according to settings found in SciTE.properties.
+The results of the lex will be compared to the corresponding .styled file and if different
+the result will be saved to a .new file for checking.
+So, if x.cxx is the example, its lexed form will be checked against x.cxx.styled and a
+x.cxx.new file may be created. The .new and .styled files contain the text of the original
+file along with style number changes in {} like:
+	{5}function{0} {11}first{10}(){0}
+After checking that the .new file is correct, it can be promoted to .styled and committed
+to the repository.
+
+The SciTE.properties file is similar to properties files used for SciTE but are simpler.
+The lexer to be run is defined with a lexer.{filepattern} statement like:
+	lexer.*.d=d
+
+Keywords may be defined with keywords settings like:
+	keywords.*.cxx=int char
+	keywords2.*.cxx=open
+
+Other settings are treated as lexer properties and forwarded to the lexer:
+	lexer.cpp.track.preprocessor=1
+
+If there is a need to test additional configurations of keywords or properties then
+create another subdirectory with the different settings in a new SciTE.properties.
-- 
cgit v1.2.3