Next: Various Helper Functions, Previous: Syntax Highlighting Tests, Up: How to Write Tests [Contents][Index]

3.7.1 Creating temporary buffers ¶

The ert-with-test-buffer macro can be used to create a temporary buffer during a test, which is cleaned up automatically if the test is successful. But if the test fails, the buffer stays around so that you can more easily investigate the test failure. When you are done, you can use the command ert-kill-all-test-buffers to kill all test buffers that have been created by this macro.

Macro: ert-with-test-buffer ((&key ((:name name-form :selected select-form))) &body body) ¶

This macro creates a test buffer and runs body in that buffer. If body finishes successfully, the test buffer is killed; if there is an error, the test buffer is kept around for further inspection. The return value is the last form in body.

The test buffer name is derived from the name of the ERT test and the result of NAME-FORM. Example:

(ert-deftest backtrace-tests--variables ()
 (ert-with-test-buffer (:name "variables")
 ...))

This uses the test buffer *Test buffer (backtrace-tests--variables): variables*.

If select-form is non-nil, select the buffer after creating it. This has the same effect as combining ert-with-test-buffer with ert-with-buffer-selected. Example:

(ert-deftest whitespace-tests--global ()
 (ert-with-test-buffer (:name "global" :selected t)
 ...))

The select-form shall be set non-nil when body contains some call to ert-play-keys to generate programmatically user input events inserting text into the test buffer, or starting commands acting on the test buffer.

Macro: ert-with-buffer-selected (buffer &body body) ¶

The macro display a buffer in a temporary selected window and runs body. If buffer is nil, the current buffer is used.

The buffer is made the current buffer, and the temporary window becomes the selected-window, before body is evaluated. The modification hooks before-change-functions and after-change-functions are not inhibited during the evaluation of body, which makes it easier to use execute-kbd-macro to simulate user interaction. The window configuration is restored before returning, even if body exits nonlocally. The return value is the last form in body. Example:

(with-temp-buffer
 (ert-with-buffer-selected nil
 ...))

This displays a temporary buffer like *temp*-739785*.

One of the use of ert-with-buffer-selected is to set the buffer to which user input events generated programmatically by one or more calls to ert-play-keys are targetted, which is needed when those events are supposed to insert text into this buffer, or start commands acting on it.

3.7.2 Protecting buffers ¶

Macro: ert-with-buffer-renamed ((buffer-name-form) &body body) ¶

This macro protects the buffer buffer-name from side-effects and runs body. It renames the buffer buffer-name to a new temporary name, creates a new buffer named buffer-name, executes body, kills the new buffer, and renames the original buffer back to buffer-name.

This is useful if body has undesirable side-effects on an Emacs buffer with a fixed name such as *Messages*. Example:

(ert-with-buffer-renamed ("*Messages*") ...)