bug#67621: [PATCH] documentation for ert-font-lock

bug#67621: [PATCH] documentation for ert-font-lock

[Vladimir Kazanov]

[-- Attachment #1: Type: text/plain, Size: 239 bytes --]

Hi team,

As (reasonably) requested in emacs-devel@ [1], sending a patch that
adds ert-font-lock to NEWS and expands the ERT manual.

[1] https://lists.gnu.org/archive/html/emacs-devel/2023-12/msg00082.html

-- 
Regards,

Vladimir Kazanov

[-- Attachment #2: 0001-add-ert-font-lock-docs.patch --]
[-- Type: text/x-patch, Size: 4352 bytes --]

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.
+
 \f
 * New Modes and Packages in Emacs 30.1

--
2.34.1

bug#67621: [PATCH] documentation for ert-font-lock

[Michael Albinus via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Vladimir Kazanov <vekazanov@gmail.com> writes:

> Hi team,

Hi Vladimir,

> As (reasonably) requested in emacs-devel@ [1], sending a patch that
> adds ert-font-lock to NEWS and expands the ERT manual.

Thanks. Just some few comments.

> --- 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

Align the entries. "Tests" must be at the same position as "Files".

> +Syntax highlighting is normally provided by the Font Lock minor mode
> +that assigns face properties to parts of the buffer. The

Use two spaces at sentence end. This is for everything in ert.texi and
NEWS.

> +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.

Use @samp here, like (@samp{^}) and (@samp{<-}) .

> +i.e. @code{:tag} and @code{:expected-result}.

Please write i.e.,

> --- a/etc/NEWS
> +++ b/etc/NEWS
> +** ERT
> +
> ++++
> +*** Syntax highlighting unit testing support

This needs a trailing period.

> +An ERT extension ('ert-font-lock') now provides support for face
> +assignment unit testing.

Since it doesn't tell details, you might refer to the manual. like

--8<---------------cut here---------------start------------->8---
An ERT extension ('ert-font-lock') now provides support for face
assignment unit testing.  For more information, see the "(ert) Syntax
Highlighting Tests" node in the ERT manual.
--8<---------------cut here---------------end--------------->8---

> Regards,
>
> Vladimir Kazanov

Best regards, Michael.

bug#67621: [PATCH] documentation for ert-font-lock

[Vladimir Kazanov]

[-- Attachment #1: Type: text/plain, Size: 2227 bytes --]

Michael,

Thank you for reviewing the patch!

Attached is an updated patch.

Thanks,
Vlad

On Mon, 4 Dec 2023 at 13:01, Michael Albinus <michael.albinus@gmx.de> wrote:
>
> Vladimir Kazanov <vekazanov@gmail.com> writes:
>
> > Hi team,
>
> Hi Vladimir,
>
> > As (reasonably) requested in emacs-devel@ [1], sending a patch that
> > adds ert-font-lock to NEWS and expands the ERT manual.
>
> Thanks. Just some few comments.
>
> > --- 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
>
> Align the entries. "Tests" must be at the same position as "Files".
>
> > +Syntax highlighting is normally provided by the Font Lock minor mode
> > +that assigns face properties to parts of the buffer. The
>
> Use two spaces at sentence end. This is for everything in ert.texi and
> NEWS.
>
> > +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.
>
> Use @samp here, like (@samp{^}) and (@samp{<-}) .
>
> > +i.e. @code{:tag} and @code{:expected-result}.
>
> Please write i.e.,
>
> > --- a/etc/NEWS
> > +++ b/etc/NEWS
> > +** ERT
> > +
> > ++++
> > +*** Syntax highlighting unit testing support
>
> This needs a trailing period.
>
> > +An ERT extension ('ert-font-lock') now provides support for face
> > +assignment unit testing.
>
> Since it doesn't tell details, you might refer to the manual. like
>
> --8<---------------cut here---------------start------------->8---
> An ERT extension ('ert-font-lock') now provides support for face
> assignment unit testing.  For more information, see the "(ert) Syntax
> Highlighting Tests" node in the ERT manual.
> --8<---------------cut here---------------end--------------->8---
>
> > Regards,
> >
> > Vladimir Kazanov
>
> Best regards, Michael.



-- 
Regards,

Vladimir Kazanov

[-- Attachment #2: 0001-add-ert-font-lock-docs.patch --]
[-- Type: text/x-patch, Size: 4712 bytes --]

From 4e7ebdaf62a434fa04b89a9494047bcfeeb652da 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 | 99 ++++++++++++++++++++++++++++++++++++++++++++++-
 etc/NEWS          |  8 ++++
 2 files changed, 106 insertions(+), 1 deletion(-)

diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi
index f4a072cf2bc..35b15fc92af 100644
--- a/doc/misc/ert.texi
+++ b/doc/misc/ert.texi
@@ -521,11 +521,12 @@ How to Write Tests


 @menu
-* The @code{should} Macro::          A powerful way to express assertions.
+* The @code{should} Macro::     A powerful way to express assertions.
 * Expected Failures::           Tests for known bugs.
 * 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 (@samp{^}) or an
+arrow (@samp{<-}).  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 of the assertion line
+will be used for the check:
+
+@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..456d9e783f9 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1102,6 +1102,14 @@ 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.  For more information, see the "(ert) Syntax
+Highlighting Tests" node in the ERT manual.
+
 \f
 * New Modes and Packages in Emacs 30.1

--
2.34.1

bug#67621: [PATCH] documentation for ert-font-lock

[Michael Albinus via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Vladimir Kazanov <vekazanov@gmail.com> writes:

> Michael,

Hi Vlad,

> Attached is an updated patch.

Almost fine. Except

>  @menu
> -* The @code{should} Macro::          A powerful way to express assertions.
> +* The @code{should} Macro::     A powerful way to express assertions.

Please don't change, it is intended. The @code{} clause isn't visible in
the resulting output. Best would be you check the result in info.

> +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.,
                                  ^^ typo?

> Thanks,
> Vlad

Best regards, Michael.

bug#67621: [PATCH] documentation for ert-font-lock

[Vladimir Kazanov]

[-- Attachment #1: Type: text/plain, Size: 867 bytes --]

Michael,

Thanks a lot! Here's the fixed patch.

Vlad

On Mon, 4 Dec 2023 at 14:02, Michael Albinus <michael.albinus@gmx.de> wrote:
>
> Vladimir Kazanov <vekazanov@gmail.com> writes:
>
> > Michael,
>
> Hi Vlad,
>
> > Attached is an updated patch.
>
> Almost fine. Except
>
> >  @menu
> > -* The @code{should} Macro::          A powerful way to express assertions.
> > +* The @code{should} Macro::     A powerful way to express assertions.
>
> Please don't change, it is intended. The @code{} clause isn't visible in
> the resulting output. Best would be you check the result in info.
>
> > +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.,
>                                   ^^ typo?
>
> > Thanks,
> > Vlad
>
> Best regards, Michael.



-- 
Regards,

Vladimir Kazanov

[-- Attachment #2: 0001-add-ert-font-lock-docs.patch --]
[-- Type: text/x-patch, Size: 4483 bytes --]

From 0c7fdf5765eabc11e328284fa6529a82592f29ea 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          |  8 ++++
 2 files changed, 105 insertions(+)

diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi
index f4a072cf2bc..892ff4dd5e4 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 (@samp{^}) or an
+arrow (@samp{<-}).  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 of the assertion line
+will be used for the check:
+
+@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 parameters 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..456d9e783f9 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1102,6 +1102,14 @@ 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.  For more information, see the "(ert) Syntax
+Highlighting Tests" node in the ERT manual.
+
 \f
 * New Modes and Packages in Emacs 30.1

--
2.34.1

bug#67621: [PATCH] documentation for ert-font-lock

[Michael Albinus via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Vladimir Kazanov <vekazanov@gmail.com> writes:

> Michael,

Hi Vlad,

> Thanks a lot! Here's the fixed patch.

Fine. Let's wait for a couple of days, and if nobody objects, I'll push
it for you.

> Vlad

Best regards, Michael.

bug#67621: [PATCH] documentation for ert-font-lock

[Vladimir Kazanov]

Hi Michael,

It seems that there are no objections to the documentation update.
Should we add it, or do you have any other worthwhile additions in
mind?

Thank you,
Vlad

On Mon, 4 Dec 2023 at 15:16, Michael Albinus <michael.albinus@gmx.de> wrote:
>
> Vladimir Kazanov <vekazanov@gmail.com> writes:
>
> > Michael,
>
> Hi Vlad,
>
> > Thanks a lot! Here's the fixed patch.
>
> Fine. Let's wait for a couple of days, and if nobody objects, I'll push
> it for you.
>
> > Vlad
>
> Best regards, Michael.



-- 
Regards,

Vladimir Kazanov

bug#67621: [PATCH] documentation for ert-font-lock

[Michael Albinus via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Vladimir Kazanov <vekazanov@gmail.com> writes:

> Hi Michael,

Hi Vlad,

> It seems that there are no objections to the documentation update.
> Should we add it, or do you have any other worthwhile additions in
> mind?

Usually, we give people a week or so for comments. Some of them, like
the maintainers, are very busy.

However, I have already scheduled to push your patch later this weekend
(which is less than a week). I don't expect serious objections.

> Thank you,
> Vlad

Best regards, Michael.

bug#67621: [PATCH] documentation for ert-font-lock

[Michael Albinus via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Vladimir Kazanov <vekazanov@gmail.com> writes:

> Michael,

Hi Vlad,

> Thanks a lot! Here's the fixed patch.

Pushed to the master branch.

> Vlad

Best regards, Michael.