1d0a931583
Add retained state, Data Controller, and Resource lifecycle applications under examples, with paired guidance and public-path interaction tests. Verified with make check (57 behavior tests and 5 docs tests), make load, byte compilation, checkdoc, and GUI width checks at 784px body width.
122 lines
4.9 KiB
EmacsLisp
122 lines
4.9 KiB
EmacsLisp
;;; etaf-docs-tests.el --- ETAF documentation contract tests -*- lexical-binding: t; -*-
|
|
|
|
;; SPDX-License-Identifier: GPL-3.0-or-later
|
|
|
|
;;; Code:
|
|
|
|
(require 'ert)
|
|
(require 'cl-lib)
|
|
|
|
(defconst etaf-docs-test--root
|
|
(file-name-directory
|
|
(directory-file-name (file-name-directory (or load-file-name
|
|
buffer-file-name))))
|
|
"Absolute path of the ETAF repository under test.")
|
|
|
|
(defun etaf-docs-test--read (relative-file)
|
|
"Return the contents of RELATIVE-FILE in the repository."
|
|
(with-temp-buffer
|
|
(insert-file-contents (expand-file-name relative-file etaf-docs-test--root))
|
|
(buffer-string)))
|
|
|
|
(defun etaf-docs-test--elisp-blocks (contents)
|
|
"Return the fenced Elisp blocks found in documentation CONTENTS."
|
|
(let (blocks)
|
|
(with-temp-buffer
|
|
(insert contents)
|
|
(goto-char (point-min))
|
|
(while (re-search-forward "^```elisp[[:space:]]*$" nil t)
|
|
(let ((start (line-beginning-position 2)))
|
|
(unless (re-search-forward "^```[[:space:]]*$" nil t)
|
|
(error "Unclosed Elisp documentation block"))
|
|
(push (buffer-substring-no-properties start
|
|
(line-beginning-position))
|
|
blocks))))
|
|
(nreverse blocks)))
|
|
|
|
(defun etaf-docs-test--read-all (source)
|
|
"Read every form in Elisp documentation SOURCE and return its count."
|
|
(with-temp-buffer
|
|
(insert source)
|
|
(goto-char (point-min))
|
|
(let ((count 0))
|
|
(condition-case err
|
|
(while t
|
|
(read (current-buffer))
|
|
(cl-incf count))
|
|
(end-of-file count)
|
|
(error (error "Cannot read documentation form: %S" err))))))
|
|
|
|
(ert-deftest etaf-docs-have-paired-long-lived-files ()
|
|
"Keep the public architecture, guide, and plan in both languages."
|
|
(dolist (file '("README.md"
|
|
"README.zh-CN.md"
|
|
"DESIGN.md"
|
|
"DESIGN.zh-CN.md"
|
|
"examples/README.md"
|
|
"examples/README.zh-CN.md"
|
|
"docs/architecture.en.md"
|
|
"docs/architecture.zh.md"
|
|
"docs/user-guide.en.md"
|
|
"docs/user-guide.zh.md"
|
|
"docs/implementation-plan.en.md"
|
|
"docs/implementation-plan.zh.md"
|
|
"postmortem/2026-08-05-executable-core-examples.en.md"
|
|
"postmortem/2026-08-05-executable-core-examples.zh.md"))
|
|
(should (file-exists-p (expand-file-name file etaf-docs-test--root)))))
|
|
|
|
(ert-deftest etaf-docs-user-surface-has-one-current-vocabulary ()
|
|
"Reject old public entry names and stale View examples in user docs."
|
|
(dolist (file '("README.md" "README.zh-CN.md"
|
|
"examples/README.md" "examples/README.zh-CN.md"
|
|
"docs/architecture.en.md" "docs/architecture.zh.md"
|
|
"docs/user-guide.en.md" "docs/user-guide.zh.md"
|
|
"docs/implementation-plan.en.md"
|
|
"docs/implementation-plan.zh.md"))
|
|
(let ((contents (etaf-docs-test--read file)))
|
|
(should-not
|
|
(string-match-p
|
|
(regexp-opt '("etaf-template" "etaf-create-app")) contents))
|
|
(should-not (string-match-p "(text \"[^\"]+\" :" contents))))
|
|
(let ((guide (etaf-docs-test--read "docs/user-guide.en.md")))
|
|
(dolist (token '("etaf-view" "etaf-mount" "etaf-define-component"
|
|
"etaf-data-grid" "etaf-resource"))
|
|
(should (string-match-p (regexp-quote token) guide)))))
|
|
|
|
(ert-deftest etaf-docs-elisp-examples-are-readable ()
|
|
"Keep fenced Elisp examples syntactically readable by Emacs."
|
|
(dolist (file '("README.md" "README.zh-CN.md"
|
|
"examples/README.md" "examples/README.zh-CN.md"
|
|
"docs/architecture.en.md" "docs/architecture.zh.md"
|
|
"docs/user-guide.en.md" "docs/user-guide.zh.md"
|
|
"docs/implementation-plan.en.md"
|
|
"docs/implementation-plan.zh.md"))
|
|
(dolist (block (etaf-docs-test--elisp-blocks
|
|
(etaf-docs-test--read file)))
|
|
(should (> (etaf-docs-test--read-all block) 0)))))
|
|
|
|
(ert-deftest etaf-source-uses-only-public-ebox-names ()
|
|
"Keep the ETAF implementation independent of Ebox private functions."
|
|
(dolist (file
|
|
(append
|
|
(directory-files etaf-docs-test--root t "\\.el\\'")
|
|
(directory-files
|
|
(expand-file-name "examples" etaf-docs-test--root)
|
|
t "\\.el\\'")))
|
|
(with-temp-buffer
|
|
(insert-file-contents file)
|
|
(should-not (re-search-forward "ebox--" nil t)))))
|
|
|
|
(ert-deftest etaf-examples-use-only-public-etaf-names ()
|
|
"Keep executable examples on the public ETAF contract."
|
|
(dolist (file
|
|
(directory-files
|
|
(expand-file-name "examples" etaf-docs-test--root)
|
|
t "\\.el\\'"))
|
|
(with-temp-buffer
|
|
(insert-file-contents file)
|
|
(should-not
|
|
(re-search-forward (regexp-opt '("etaf--" "ebox--")) nil t)))))
|
|
|
|
;;; etaf-docs-tests.el ends here
|