From c0ec08349c54ce3877e9ff94bfc7c87484fc2a6e Mon Sep 17 00:00:00 2001
From: Vladimir Kazanov <vekazanov@gmail.com>
Date: Mon, 4 Dec 2023 12:07:46 +0000
Subject: [PATCH] add ert-font-lock docs

Document ert-font-lock:
* doc/misc/ert.texi: expand the manual
* etc/NEWS: mention ert-font-lock
---
 doc/misc/ert.texi | 97 +++++++++++++++++++++++++++++++++++++++++++++++
 etc/NEWS          |  7 ++++
 2 files changed, 104 insertions(+)

diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi
index f4a072cf2bc..20608516e37 100644
--- a/doc/misc/ert.texi
+++ b/doc/misc/ert.texi
@@ -526,6 +526,7 @@ How to Write Tests
 * Tests and Their Environment:: Don't depend on customizations; no side effects.
 * Useful Techniques::           Some examples.
 * erts files::                  Files containing many buffer tests.
+* Syntax Highlighting Tests:: Tests for face assignment.
 @end menu


@@ -942,6 +943,102 @@ erts files
 If you need to use the literal line single line @samp{=-=} in a test
 section, you can quote it with a @samp{\} character.

+@node Syntax Highlighting Tests
+@section Syntax Highlighting Tests
+
+Syntax highlighting is normally provided by the Font Lock minor mode
+that assigns face properties to parts of the buffer. The
+@code{ert-font-lock} package makes it possible to introduce unit tests
+checking face assignment. Test assertions are included in code-level
+comments directly and can be read either from inline strings or files.
+
+Test assertion parser extracts tests from comment-only lines. Every
+comment assertion line starts either with a caret ('^') or an arrow
+('<-'). A caret/arrow should be followed immedately by the name of a
+face to be checked.
+
+The test then checks if the first non-assertion column above the caret
+contains a face expected by the assertion:
+
+@example
+var variable = 11;
+//   ^ font-lock-variable-name-face
+//             ^ font-lock-literal-face
+//               ^ font-lock-punctuation-face
+// this is not an assertion, it's just a comment
+//   ^ font-lock-comment-face
+@end example
+
+The arrow means that the first non-empty column will be used in the
+assertion:
+
+@example
+var variable = 1;
+// <- font-lock-keyword-face
+11;
+// <- font-lock-literal-face
+@end example
+
+@findex ert-font-lock-test-string
+
+The @code{ert-font-lock-test-string} function extracts ERT assertions
+from an inline string. The @code{javascript-mode} symbol below
+specifies the major mode used for comments and font locking:
+
+@lisp
+(ert-deftest test-font-lock-test-string--correct ()
+  (ert-font-lock-test-string
+   "
+var abc = function(d) @{
+// <- font-lock-keyword-face
+//   ^ font-lock-variable-name-face
+    //        ^ font-lock-keyword-face
+    //             ^ font-lock-variable-name-face
+@};
+"
+   'javascript-mode))
+@end lisp
+
+@findex ert-font-lock-test-file
+
+It is also possible to extract test assertions from a file:
+
+@lisp
+(ert-deftest test-font-lock-test-file--correct ()
+  (ert-font-lock-test-file
+   (ert-resource-file "correct.js")
+   'javascript-mode))
+@end lisp
+
+@findex ert-font-lock-deftest
+
+The @code{ert-font-lock-deftest} macro simplifies inline test
+definition:
+
+@lisp
+(ert-font-lock-deftest test-macro-test--inline
+    emacs-lisp-mode
+  "
+(defun fun ())
+;; ^ font-lock-keyword-face
+;;      ^ font-lock-function-name-face")
+@end lisp
+
+@findex ert-font-lock-deftest-file
+
+The @code{ert-font-lock-deftest-file} macro reads assertions from a
+file:
+
+@lisp
+(ert-font-lock-deftest-file test-macro-test--file
+    "Test reading correct assertions from a file"
+  javascript-mode
+  "correct.js")
+@end lisp
+
+The @code{ert-font-lock-deftest} and @code{ert-font-lock-deftest-file}
+macros accept the same keyword parameteres as @code{ert-deftest},
+i.e. @code{:tag} and @code{:expected-result}.

 @node How to Debug Tests
 @chapter How to Debug Tests
diff --git a/etc/NEWS b/etc/NEWS
index 29f4e5c0b66..37e54f4865a 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1102,6 +1102,13 @@ will return the URL for that bug.
 *** New command 'customize-dirlocals'.
 This command pops up a buffer to edit the settings in ".dir-locals.el".

+** ERT
+
++++
+*** Syntax highlighting unit testing support
+An ERT extension ('ert-font-lock') now provides support for face
+assignment unit testing.
+
 
 * New Modes and Packages in Emacs 30.1

--
2.34.1