Subject: [Patch Debbugs] Infrastructure Improvements

From: Morgan Smith <[email-masked]>
Date: Thu, 20 Feb 2025 14:01:03 -0500

Hello!

Nothing too exciting in this series.  Just adjusting things so we can
split the tests into multiple files.  Also adding a makefile target to
run the "checkdoc" stuff with the spell checker enabled.

Thanks,

Morgan

>From 9c73769d4255c072655ff307939098a5dc058f86 Mon Sep 17 00:00:00 2001
From: Morgan Smith <[email-masked]>
Date: Fri, 14 Feb 2025 16:23:34 -0500
Subject: [PATCH 1/3] tests: Move helper and wrapper functions into their own
 file

* test/debbugs-test-helpers.el: New file.
* test/debbugs-tests.el: Move test helper and wrapper functions into the new
file and require it.
* Makefile(check): Load all files in the test directory.
---
 Makefile                     |   2 +-
 test/debbugs-test-helpers.el | 146 +++++++++++++++++++++++++++++++++++
 test/debbugs-tests.el        | 113 +--------------------------
 3 files changed, 148 insertions(+), 113 deletions(-)
 create mode 100644 test/debbugs-test-helpers.el

diff --git a/Makefile b/Makefile
index a7b6b0c7f3..1ab85d2b64 100644
--- a/Makefile
+++ b/Makefile
@@ -24,7 +24,7 @@ doc: $(INFOMANUALS)
 build: $(TARGET)
 
 check: build $(TESTTARGET)
-	@$(EMACS) -Q --batch -L . -l $(TESTSOURCE) -f ert-run-tests-batch-and-exit
+	@$(EMACS) -Q --batch -L . $(foreach file,$(TESTSOURCE), -l $(file)) -f ert-run-tests-batch-and-exit
 
 clean:
 	-rm -f $(TARGET) $(TESTTARGET) $(INFOMANUALS)
diff --git a/test/debbugs-test-helpers.el b/test/debbugs-test-helpers.el
new file mode 100644
index 0000000000..f98bab40ed
--- /dev/null
+++ b/test/debbugs-test-helpers.el
@@ -0,0 +1,146 @@
+;;; debbugs-test-helpers.el --- Helpers for testing debbugs -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2024-2025 Free Software Foundation, Inc.
+
+;; Author: Morgan Smith <[email-masked]>
+;; Package: debbugs
+
+;; This file is not part of GNU Emacs.
+
+;; This program is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Please ensure tests don't actually make network calls.
+
+;;; Code:
+
+(require 'debbugs)
+
+;;; Helper Data:
+
+;; Generated using this:
+;; (soap-invoke debbugs-wsdl debbugs-port "get_status" [64064])
+(defconst debbugs-test--bug-status-soap-return
+  '(((item
+      (key . 64064)
+      (value
+       (package . "emacs") (found_date) (last_modified . 1689593050)
+       (affects) (date . 1686745022) (fixed_versions)
+       (originator . "Morgan Smith <[email-masked]>")
+       (blocks) (archived . 1) (found) (unarchived) (tags . "patch")
+       (severity . "normal") (location . "archive") (owner) (fixed)
+       (blockedby) (pending . "done") (keywords . "patch") (id . 64064)
+       (found_versions) (mergedwith) (summary) (forwarded)
+       (log_modified . 1689593050)
+       (done . "Michael Albinus <[email-masked]>")
+       (source . "unknown")
+       (msgid
+        . "<[email-masked]>")
+       (bug_num . 64064) (subject . "[PATCH 0/4] debbugs improvements")
+       (fixed_date)))))
+  "Mock result from `soap-invoke' for bug 64064.")
+
+;; Generated using this:
+;; (debbugs-get-status 64064)
+(defconst debbugs-test--bug-status
+  '(((cache_time . 5000) (source . "unknown") (unarchived)
+     (keywords "patch") (blocks) (pending . "done") (severity . "normal")
+     (done . "Michael Albinus <[email-masked]>") (location . "archive")
+     (log_modified . 1689593050) (subject . "[PATCH 0/4] debbugs improvements")
+     (last_modified . 1689593050) (found) (tags "patch") (package "emacs")
+     (originator . "Morgan Smith <[email-masked]>") (archived . t)
+     (blockedby) (affects) (mergedwith) (summary) (date . 1686745022)
+     (fixed_versions) (id . 64064) (fixed) (found_date) (forwarded)
+     (msgid
+      . "<[email-masked]>")
+     (owner) (found_versions) (fixed_date) (bug_num . 64064)))
+  "Mock result from `debbugs-get-status' for bug 64064.")
+
+;;; Helper Functions:
+
+(defvar debbugs-test--soap-operation-name nil)
+(defvar debbugs-test--soap-parameters nil)
+(defun debbugs-test--soap-invoke-internal
+    (callback _cbargs _wsdl _service operation-name &rest parameters)
+  "Over-ride for testing."
+  (setq debbugs-test--soap-operation-name operation-name)
+  (setq debbugs-test--soap-parameters parameters)
+  (let ((return
+         (cond ((string-equal operation-name "get_status")
+                debbugs-test--bug-status-soap-return)
+               ((string-equal operation-name "get_usertag")
+                '(((hi))))
+               (t '((0))))))
+    (if callback
+        (progn
+          (funcall callback return)
+          nil)
+      return)))
+
+(defun debbugs-test--override-float-time (func &rest rest)
+  "Override `float-time' for FUNC with args REST."
+  (cl-letf (((symbol-function #'float-time)
+             (lambda (&optional _specified-time) 5000)))
+    (apply func rest)))
+
+(defun debbugs-test--setup ()
+  "Mock network and time functions.
+These mock functions are needed to make the tests reproducible."
+  (setq debbugs-test--soap-operation-name nil)
+  (setq debbugs-test--soap-parameters nil)
+
+  (add-function
+   :override (symbol-function #'soap-invoke-internal)
+   #'debbugs-test--soap-invoke-internal)
+
+  (add-function
+   :around (symbol-function #'debbugs-get-cache)
+   #'debbugs-test--override-float-time)
+
+  (add-function
+   :around (symbol-function #'debbugs-put-cache)
+   #'debbugs-test--override-float-time))
+
+(defun debbugs-test--teardown ()
+  "Restore functions to as they where before."
+  (setq debbugs-test--soap-operation-name nil)
+  (setq debbugs-test--soap-parameters nil)
+
+  (remove-function
+   (symbol-function #'soap-invoke-internal)
+   #'debbugs-test--soap-invoke-internal)
+
+  (remove-function
+   (symbol-function #'debbugs-get-cache)
+   #'debbugs-test--override-float-time)
+
+  (remove-function
+   (symbol-function #'debbugs-put-cache)
+   #'debbugs-test--override-float-time))
+
+(defmacro ert-deftest--debbugs (name args docstring &rest body)
+  "The same as `ert-deftest' but runs setup and teardown functions."
+  (declare
+   (doc-string 3)
+   (indent 2))
+  `(ert-deftest ,name ,args ,docstring
+                (debbugs-test--setup)
+                ,@body
+                (debbugs-test--teardown)))
+
+
+(provide 'debbugs-test-helpers)
+
+;;; debbugs-test-helpers.el ends here
diff --git a/test/debbugs-tests.el b/test/debbugs-tests.el
index f3abea2837..eb2e8b1768 100644
--- a/test/debbugs-tests.el
+++ b/test/debbugs-tests.el
@@ -27,118 +27,7 @@
 ;;; Code:
 
 (require 'debbugs)
-
-;;; Helper Data:
-
-;; Generated using this:
-;; (soap-invoke debbugs-wsdl debbugs-port "get_status" [64064])
-(defconst debbugs-test--bug-status-soap-return
-  '(((item
-      (key . 64064)
-      (value
-       (package . "emacs") (found_date) (last_modified . 1689593050)
-       (affects) (date . 1686745022) (fixed_versions)
-       (originator . "Morgan Smith <[email-masked]>")
-       (blocks) (archived . 1) (found) (unarchived) (tags . "patch")
-       (severity . "normal") (location . "archive") (owner) (fixed)
-       (blockedby) (pending . "done") (keywords . "patch") (id . 64064)
-       (found_versions) (mergedwith) (summary) (forwarded)
-       (log_modified . 1689593050)
-       (done . "Michael Albinus <[email-masked]>")
-       (source . "unknown")
-       (msgid
-        . "<[email-masked]>")
-       (bug_num . 64064) (subject . "[PATCH 0/4] debbugs improvements")
-       (fixed_date)))))
-  "Mock result from `soap-invoke' for bug 64064.")
-
-;; Generated using this:
-;; (debbugs-get-status 64064)
-(defconst debbugs-test--bug-status
-  '(((cache_time . 5000) (source . "unknown") (unarchived)
-     (keywords "patch") (blocks) (pending . "done") (severity . "normal")
-     (done . "Michael Albinus <[email-masked]>") (location . "archive")
-     (log_modified . 1689593050) (subject . "[PATCH 0/4] debbugs improvements")
-     (last_modified . 1689593050) (found) (tags "patch") (package "emacs")
-     (originator . "Morgan Smith <[email-masked]>") (archived . t)
-     (blockedby) (affects) (mergedwith) (summary) (date . 1686745022)
-     (fixed_versions) (id . 64064) (fixed) (found_date) (forwarded)
-     (msgid
-      . "<[email-masked]>")
-     (owner) (found_versions) (fixed_date) (bug_num . 64064)))
-  "Mock result from `debbugs-get-status' for bug 64064.")
-
-;;; Helper Functions:
-
-(defvar debbugs-test--soap-operation-name nil)
-(defvar debbugs-test--soap-parameters nil)
-(defun debbugs-test--soap-invoke-internal
-    (callback _cbargs _wsdl _service operation-name &rest parameters)
-  "Over-ride for testing."
-  (setq debbugs-test--soap-operation-name operation-name)
-  (setq debbugs-test--soap-parameters parameters)
-  (let ((return
-         (cond ((string-equal operation-name "get_status")
-                debbugs-test--bug-status-soap-return)
-               ((string-equal operation-name "get_usertag")
-                '(((hi))))
-               (t '((0))))))
-    (if callback
-        (progn
-          (funcall callback return)
-          nil)
-      return)))
-
-(defun debbugs-test--override-float-time (func &rest rest)
-  "Override `float-time' for FUNC with args REST."
-  (cl-letf (((symbol-function #'float-time)
-             (lambda (&optional _specified-time) 5000)))
-    (apply func rest)))
-
-(defun debbugs-test--setup ()
-  "Mock network and time functions.
-These mock functions are needed to make the tests reproducible."
-  (setq debbugs-test--soap-operation-name nil)
-  (setq debbugs-test--soap-parameters nil)
-
-  (add-function
-   :override (symbol-function #'soap-invoke-internal)
-   #'debbugs-test--soap-invoke-internal)
-
-  (add-function
-   :around (symbol-function #'debbugs-get-cache)
-   #'debbugs-test--override-float-time)
-
-  (add-function
-   :around (symbol-function #'debbugs-put-cache)
-   #'debbugs-test--override-float-time))
-
-(defun debbugs-test--teardown ()
-  "Restore functions to as they where before."
-  (setq debbugs-test--soap-operation-name nil)
-  (setq debbugs-test--soap-parameters nil)
-
-  (remove-function
-   (symbol-function #'soap-invoke-internal)
-   #'debbugs-test--soap-invoke-internal)
-
-  (remove-function
-   (symbol-function #'debbugs-get-cache)
-   #'debbugs-test--override-float-time)
-
-  (remove-function
-   (symbol-function #'debbugs-put-cache)
-   #'debbugs-test--override-float-time))
-
-(defmacro ert-deftest--debbugs (name args docstring &rest body)
-  "The same as `ert-deftest' but runs setup and teardown functions."
-  (declare
-   (doc-string 3)
-   (indent 2))
-  `(ert-deftest ,name ,args ,docstring
-                (debbugs-test--setup)
-                ,@body
-                (debbugs-test--teardown)))
+(require 'debbugs-test-helpers "./test/debbugs-test-helpers")
 
 ;;; Tests:
 
-- 
2.48.1

>From b585fc479503e96a42d966f90fbb8d13f4e2d26e Mon Sep 17 00:00:00 2001
From: Morgan Smith <[email-masked]>
Date: Fri, 14 Feb 2025 16:23:57 -0500
Subject: [PATCH 2/3] tests: Add tests for debbugs-gnu

* test/debbugs-gnu-tests.el: New file.
---
 test/debbugs-gnu-tests.el | 60 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 test/debbugs-gnu-tests.el

diff --git a/test/debbugs-gnu-tests.el b/test/debbugs-gnu-tests.el
new file mode 100644
index 0000000000..7b038b7411
--- /dev/null
+++ b/test/debbugs-gnu-tests.el
@@ -0,0 +1,60 @@
+;;; debbugs-gnu-tests.el --- tests for debbugs-gnu.el -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2025 Free Software Foundation, Inc.
+
+;; Author: Morgan Smith <[email-masked]>
+;; Package: debbugs
+
+;; This file is not part of GNU Emacs.
+
+;; This program is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Please ensure tests don't actually make network calls.
+
+;;; Code:
+
+(require 'debbugs)
+(require 'debbugs-gnu)
+(require 'debbugs-test-helpers "./test/debbugs-test-helpers")
+
+;;; Tests:
+
+(ert-deftest--debbugs debbugs-test-debbugs-gnu-search ()
+  "Test `debbugs-gnu-search'.
+Also test `debbugs-gnu-patches' and `debbugs-gnu-tagged' which are
+simple wrappers for `debbugs-gnu-search'."
+  (cl-letf (((symbol-function #'debbugs-gnu)
+             #'list))
+
+    (should (equal '(nil ("emacs") nil nil "patch")
+                   (debbugs-gnu-patches)))
+    (should (equal debbugs-gnu-current-query nil))
+    (should (equal debbugs-gnu-current-filter nil))
+
+    (should (equal '(("tagged"))
+                   (debbugs-gnu-tagged)))
+    (should (equal debbugs-gnu-current-query nil))
+    (should (equal debbugs-gnu-current-filter nil))
+
+    (should
+     (equal '(nil ("guix" "guix-patches") nil)
+            (debbugs-gnu-search "frogs" '((pending . "pending")) nil '("guix" "guix-patches") nil)))
+    (should (equal debbugs-gnu-current-query '((phrase . "frogs"))))
+    (should (equal debbugs-gnu-current-filter '((pending . "pending"))))))
+
+(provide 'debbugs-gnu-tests)
+
+;;; debbugs-gnu-tests.el ends here
-- 
2.48.1

>From 9d8234d59a854b2bfcec37d5ef99c3244ef351f6 Mon Sep 17 00:00:00 2001
From: Morgan Smith <[email-masked]>
Date: Thu, 20 Feb 2025 12:55:42 -0500
Subject: [PATCH 3/3] Makefile: Add target to run checkdoc on all files

* Makefile: Add target to run checkdoc on all files.
* .dir-locals.el: Run ispell with checkdoc with some words added to the
dictionary.
---
 .dir-locals.el | 18 ++++++++++++++++++
 Makefile       | 12 +++++++++++-
 2 files changed, 29 insertions(+), 1 deletion(-)
 create mode 100644 .dir-locals.el

diff --git a/.dir-locals.el b/.dir-locals.el
new file mode 100644
index 0000000000..fa8707345f
--- /dev/null
+++ b/.dir-locals.el
@@ -0,0 +1,18 @@
+;;; Directory Local Variables            -*- no-byte-compile: t -*-
+;;; For more information see (info "(emacs) Directory Variables")
+
+((emacs-lisp-mode . ((checkdoc-package-keywords-flag . t)
+                     (checkdoc-ispell-lisp-words
+                      .
+                      ("ChangeLog" "ChangeLogs" "UTF" "alist" "args"
+                       "armstrong" "backend" "bcc" "bugreport" "cdate" "cedet"
+                       "coreutils" "cygwin" "debbugs" "debian" "el" "emacs"
+                       "etags" "freemail" "fsf" "guix" "gw" "henoch" "hu"
+                       "hyperestraier" "keymap" "magit" "magnus" "maint"
+                       "maintainer" "maintainer's" "mbox" "mboxes" "minibuffer"
+                       "moreinfo" "multibyte" "notabug" "paren" "persistency"
+                       "regexp" "rescan" "rgm" "rmail" "severities" "sexp"
+                       "solaris" "src" "sublist" "submitter" "submitter's"
+                       "subproduct" "subqueries" "subquery" "teardown"
+                       "unarchived" "unibyte" "unreproducible" "url" "util"
+                       "wishlist" "wontfix" "wsdl" "www" "xsd" "zltuz")))))
diff --git a/Makefile b/Makefile
index 1ab85d2b64..3b39b4f692 100644
--- a/Makefile
+++ b/Makefile
@@ -8,7 +8,7 @@ TESTTARGET=$(patsubst %.el,%.elc,$(TESTSOURCE))
 
 INFOMANUALS=debbugs.info debbugs-ug.info
 
-.PHONY: all build check clean
+.PHONY: all build check clean checkdoc
 .PRECIOUS: %.elc
 
 %.elc: %.el
@@ -23,6 +23,16 @@ doc: $(INFOMANUALS)
 
 build: $(TARGET)
 
+# We need to set `enable-local-variables' to load '.dir-locals.el' while in batch mode.
+# We load '.dir-locals.el' to set the ispell wordlist for checkdoc.
+# We don't set `checkdoc-spellcheck-documentation-flag' in '.dir-locals.el'
+# so that developers don't need to have ispell set up and because flymake
+# doesn't seem to respect the word list.
+checkdoc: $(SOURCE) $(TESTSOURCE)
+	@$(EMACS) -Q --batch "--eval=(setq enable-local-variables :all \
+                                       checkdoc-spellcheck-documentation-flag t)" \
+    -L . $(foreach file,$^,"--eval=(checkdoc-file \"$(file)\")")
+
 check: build $(TESTTARGET)
 	@$(EMACS) -Q --batch -L . $(foreach file,$(TESTSOURCE), -l $(file)) -f ert-run-tests-batch-and-exit
 
-- 
2.48.1