[nongnu] elpa/org-superstar b196dc10af 025/162: adding first draft of public testing facilities

[Stefan Kangas]

branch: elpa/org-superstar
commit b196dc10afc203763bf867815f79cb7d61ce3167
Author: D. Williams <d.williams@posteo.net>
Commit: D. Williams <d.williams@posteo.net>

    adding first draft of public testing facilities
---
 tests/README.org        | 36 ++++++++++++++++++++
 tests/composure-test.el | 87 +++++++++++++++++++++++++++++++++++++++++++++++++
 tests/minimal-setup.el  |  6 ++++
 tests/sample.org        | 35 ++++++++++++++++++++
 4 files changed, 164 insertions(+)

diff --git a/tests/README.org b/tests/README.org
new file mode 100644
index 0000000000..3e218cf2e4
--- /dev/null
+++ b/tests/README.org
@@ -0,0 +1,36 @@
+#+TITLE: Testing Routines: There be Dragons
+
+* Purpose
+This is where I will put cleaned up testing routines meant for testing
+and debugging ~org-superstar-mode~.  However, as the title suggests,
+*none of these files are meant for normal package usage*.  Consequently,
+I advise to run these files with a minimal setup (think =emacs -Q=) and
+only keep sessions involving them open /as long as necessary/.  Since
+the things I want to test are very side effect reliant, I see myself
+forced to rely on ~advice~ and family.  To further emphasize that I do
+not intend to ship any of these functions as part of my package, I use
+the non-standard (yet popular) naming convention
+~org-superstar/variable-name~.  See below for the purpose of the
+individual files included here.
+
+** =sample.org=
+A harmless sample file.  An earlier version was used for the sample
+image in the top-level README.
+
+** =minimal-setup.el=
+This file contains a minimal setup useful for testing.  Just run:
+#+BEGIN_SRC bash
+emacs -Q -l ../org-superstar.el -l minimal-setup.el sample.org
+#+END_SRC
+
+To run additional test files, it is easiest to just =-l= them as well.
+
+** =composure-test.el=
+This file adds lots of information regarding calls to ~compose-region~
+for functions defined in =org-superstar.el=.  They are written to the
+=*Messages*= buffer.  It also makes sure all ~--prettify-~ functions
+return proper faces (or ~nil~).
+
+
+
+#  LocalWords:  README el
diff --git a/tests/composure-test.el b/tests/composure-test.el
new file mode 100644
index 0000000000..618ec369de
--- /dev/null
+++ b/tests/composure-test.el
@@ -0,0 +1,87 @@
+;;; composure-test.el --- Track how org-superstar primitives modify the 
buffer.  -*- lexical-binding: t; -*-
+
+;;; Commentary:
+
+;; This file purposefully breaks naming conventions to indicate that
+;; it is *NOT* part of the main package.
+
+;; WARNING: This testing package is *not* suitable for any purpose
+;; other than testing org-superstar-mode.  ONLY use this code on a
+;; clean Emacs install ("emacs -Q") and ONLY keep the Emacs session
+;; running for as long as you need to.  DO NOT use an Emacs session
+;; loading this file for everyday editing.
+
+;; THIS FILE ADVISES EMACS INTERNALS FOR DEBUGGING PURPOSES ONLY.
+;; USE AT YOUR OWN RISK.
+
+;;; Code:
+
+(require 'cl-macs)
+
+(defvar-local org-superstar/listen nil
+  "If t, activate the advice ‘org-superstar/comp-test’.
+The idea is to only let ‘org-superstar/comp-test’ listen in on
+‘compose-region’ when another function is advised to let-bind
+this variable.")
+
+;;; Advice definitions
+
+(defun org-superstar/comp-test (start end &optional components mod-func)
+  "Advise ‘compose-region’ to log modifications made to buffer.
+START, END, COMPONENTS and MOD-FUNC correspond to the arguments
+of ‘compose-region’."
+  (when org-superstar/listen
+    (message "compose-region called: from %d to %d" start end)
+    ;; I currently *do not* want to touch more than one character at a
+    ;; time.  This test will only fail when I mess up regex grouping,
+    ;; but it serves as a reminder that composing a region is not as
+    ;; trivial as making the region bigger.
+    (cl-assert (= 1 (- end start)))
+    (cond
+     ((stringp components)
+      (message
+       "composing ‘%s’ using string ‘%s’"
+       (buffer-substring-no-properties start end)
+       components))
+     ((characterp components)
+      (message
+       "composing ‘%s’ using string ‘%s’"
+       (buffer-substring-no-properties start end)
+       components))
+     (t
+      (message
+       "composing ‘%s’ using a sequence"
+       (buffer-substring-no-properties start end))))))
+
+(defun org-superstar/wrap-prettify (face-function &rest args)
+  "Wrap FACE-FUNCTION and call with ARGS.
+Ensure the return value is a face or nil.  Also toggle
+‘compose-region’ calls to log behavior."
+  (let ((org-superstar/listen t)
+         (returned-face nil))
+    (message "Entered function")
+    (prog1 (setq returned-face (apply face-function args))
+      (cl-assert (or (facep returned-face)
+                     (null returned-face)))
+      (when (facep returned-face)
+        (message "Applied face ‘%s’ to group."
+                 returned-face))
+      (message "Exited" face-function))))
+
+
+
+;;; Adding advice
+
+;; listen in on compose-region
+(advice-add 'compose-region :before #'org-superstar/comp-test)
+
+;; advise prettifyers to snoop
+
+(advice-add 'org-superstar--prettify-ibullets
+            :around #'org-superstar/wrap-prettify)
+(advice-add 'org-superstar--prettify-main-hbullet
+            :around #'org-superstar/wrap-prettify)
+(advice-add 'org-superstar--prettify-other-hbullet
+            :around #'org-superstar/wrap-prettify)
+(advice-add 'org-superstar--prettify-leading-hbullets
+            :around #'org-superstar/wrap-prettify)
diff --git a/tests/minimal-setup.el b/tests/minimal-setup.el
new file mode 100644
index 0000000000..46c3987194
--- /dev/null
+++ b/tests/minimal-setup.el
@@ -0,0 +1,6 @@
+;;; A small init file setting you up for tests.
+(add-hook 'org-mode-hook
+          (lambda ()
+            (org-superstar-mode 1)))
+
+(setq debug-on-error t)
diff --git a/tests/sample.org b/tests/sample.org
new file mode 100644
index 0000000000..b95b373957
--- /dev/null
+++ b/tests/sample.org
@@ -0,0 +1,35 @@
+#+TITLE: Sample File
+#+STARTUP: showeverything
+* Lorem ipsum dolor sit amet
+** Consectetur adipiscing elit
+*** Eiusmod tempor incididunt
+    Ut labore et dolore magna aliqua. Fringilla phasellus faucibus
+    scelerisque eleifend donec pretium vulputate sapien. Odio pellentesque
+    diam volutpat commodo.
+    * Varius morbi enim nunc
+    * faucibus, ultrices vitae
+      + auctor eu augue ut lectus arcu bibendum.
+      + neque egestas congue quisque
+        - Et ultrices neque ornare aenean euismod.
+    * Tristique nulla!
+
+#+BEGIN_SRC C
+/*
+,* This is not a header
+  + this
+    + is not
+      * a list.
+*/
+#+END_SRC
+
+
+*************** Inline task?
+**************** second
+***************** third
+
+* 1
+** 2
+*** 3
+**** 4
+***** 5
+****** 6