testing - 我可以对 ELisp 函数进行文档测试吗？

Question

我喜欢 doc-tests 的 Python 功能，可以独立测试功能。 Emacs Lisp 是否有类似的东西，或者我可以用某种方式模仿它吗？

例如，此函数从 Org 模式时钟段获取时间戳:

(defun org-get-timestamps (line)
  "Parses a clock segment line and returns the first and last timestamps in a list."
  (let* ((org-clock-regexp (concat "CLOCK: " org-ts-regexp3 "--" org-ts-regexp3))
     (t1 (if (string-match org-clock-regexp line)
         (match-string 1 line)
           (user-error "The argument must have a valid CLOCK range")))
     (t2 (match-string 9 line)))
    (cons t1 (cons t2 '()))))

我想要一个文档测试，例如:

(org-get-timestamps "CLOCK: [2019-09-26 Thu 00:29]--[2019-09-26 Thu 01:11] =>  0:42")("2019-09-26 Thu 00:29" "2019-09-26 Thu 01:11")

user-error 的测试也很好。

我也想确保任何重构都通过文档测试，所以它也是一个回归测试。

存在吗？

Answer 1

Python doctest 的一个重要特性是它的输入看起来像 Python 交互式 REPL session ，如 doctest documentation 中所述。 :

The doctest module searches for pieces of text that look like interactive Python sessions, and then executes those sessions to verify that they work exactly as shown.

我不知道有任何类似这样的 elisp 工具，但我认为你可以使用 Emacs Lisp Regression Testing (ERT) framework 实现你想要的。 ，它支持交互式和批量测试执行。

要测试 org-get-timestamps 函数，您可以像这样定义一个测试:

(require 'ert)

(ert-deftest org-timestamp-test ()
  (should (equal
           (org-get-timestamps "CLOCK: [2019-09-26 Thu 00:29]--[2019-09-26 Thu 01:11] => 0:42")
           '("2019-09-26 Thu 00:29" "2019-09-26 Thu 01:11"))))

要以交互方式运行测试，您可以键入 M-x ert，按 enter，然后再次按 enter 以使用默认 t 参数选择所有测试或键入要运行的测试的名称，然后按回车，测试结果将显示在 *ert* 缓冲区中:

Selector: org-timestamp-test
Passed:  1
Failed:  0
Skipped: 0
Total:   1/1

Started at:   2019-09-27 08:44:57-0400
Finished.
Finished at:  2019-09-27 08:44:57-0400

.

上面最后的点字符代表运行的测试。如果执行了多个测试，则会有多个点。

要以批处理模式运行测试，请将其保存到文件 org-timestamp-test.el 并假设 org-get-timestamps 函数驻留在文件 org-timestamps.el，从您的 shell 命令行像这样运行它:

emacs -batch -l ert -l org-timestamps.el -l org-timestamp-test.el -f ert-run-tests-batch-and-exit

然后测试结果显示在 shell 输出上:

Running 1 tests (2019-09-27 06:03:09-0700) passed 1/1 org-timestamp-test

Ran 1 tests, 1 results as expected (2019-09-27 06:03:09-0700)