https://github.com/szermatt/turtles
Library for writing ERT-based tests that check how Emacs renders buffers and windows
https://github.com/szermatt/turtles
elisp emacs testing
Last synced: about 1 year ago
JSON representation
Library for writing ERT-based tests that check how Emacs renders buffers and windows
- Host: GitHub
- URL: https://github.com/szermatt/turtles
- Owner: szermatt
- License: gpl-3.0
- Created: 2024-12-15T18:20:06.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-01-13T12:49:37.000Z (over 1 year ago)
- Last Synced: 2025-01-13T13:37:52.704Z (over 1 year ago)
- Topics: elisp, emacs, testing
- Language: Emacs Lisp
- Homepage:
- Size: 395 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: license
Awesome Lists containing this project
README
# Turtles
[](https://github.com/szermatt/turtles/actions)
[](https://turtles.readthedocs.io/en/latest/?badge=latest)
[](https://stable.melpa.org/#/turtles)
[](https://melpa.org/#/turtles)
This package help write ERT-based tests to that check how Emacs
renders buffers and windows. The ERT tests can be run interactively or
in batch mode.
It's especially suited to test:
- the effect of display, before-string, after-string text properties
- the effect of overlays
- text visibility
- status line
- colors changes
- complex minibuffer interactions
Read the full documentation on
[turtles-readthedocs.io](https://turtles.readthedocs.io/en/latest/index.html)
or in the info manual that comes with the package.
## Status
Version 2.0.1 is the latest version. Please depend on that tag or the
branch 2.0.
Since this is a library, versioning matters: This project follows
[Semantic Versioning 2.0.0](https://semver.org/), that is, versions
follow the format MAJOR.MINOR.PATCH with:
- MAJOR incremented for incompatible API changes
- MINOR when functionality is added that is backward-compatible
- PATCH for bugfixes
To avoid surprises, you should aim to depend on a specific, tagged
version and only increase that version when you need to.
## Installation
Install Turtles:
- on a recent version of Emacs (29 or later), from the
github repository by doing `M-x package-vc-install https://github.com/szermatt/turtles`
- using [eldev](https://github.com/emacs-eldev/eldev) to run tests in
batch mode:
```elisp
(eldev-add-extra-dependencies 'test 'turtles)
(eldev-use-vc-repository 'turtles :github "szermatt/turtles" :commit "2.0.1")
```
- from [MELPA](https://melpa.org/#/getting-started), by typing `M-x
package-install turtles`. Note that there's no practical difference
between the stable and unstable melpa package, as development
happens on a branch. You'll always get the latest release.
Turtles requires Emacs 26.1 or later. Emacs 29.1 or later is recommended.
## How it works
Turtles starts another Emacs process inside of a term buffer, runs ERT
test in that instance and grab snapshot of the display whenever
instructed.
The result is that the frame, minibuffer, window content and status
line are available to tests as text with font-lock-face properties
specifying things like color.
Here's a quick example of a test that checks a text with an invisible
section.
For more details, see the
[Tutorial](https://turtles.readthedocs.io/en/latest/tutorial.html)
```elisp
(require 'turtles)
(turtles-ert-deftest turtles-test-hello-world ()
;; The body of turtles-ert-deftest runs inside a
;; secondary Emacs instance.
(ert-with-test-buffer ()
(insert "hello, ") ;; Fill in the buffer
(insert (propertize "the " 'invisible t))
(insert "world!\n")
(turtles-with-grab-buffer () ;; Grab the current buffer content
;; Check the buffer content that was displayed
(should (equal "hello, world!"
(buffer-string))))))
```
## Something is wrong!
Please check the [doc](https://turtles.readthedocs.io/en/latest/)
and, if that doesn't help, take the time to [file a bug report](https://turtles.readthedocs.io/en/latest/contrib.html#reporting-issues).
## Contributing
See the [Contributing](https://turtles.readthedocs.io/en/latest/contrib.html)
section of the documentation.