ERT (Emacs Lisp Regression Testing)

Built-in testing framework for Emacs Lisp, providing comprehensive test definition, execution, and debugging capabilities.

Quick Start

Basic Test

(require 'ert)

(ert-deftest test-addition ()
  "Test that addition works correctly."
  (should (= 4 (+ 2 2)))
  (should (= 0 (+ -5 5))))

Run Tests

Interactively:

M-x ert RET t RET

From Command Line:

emacs -batch -l ert -l my-tests.el -f ert-run-tests-batch-and-exit

Assertions

;; Assert true
(should (= 2 (+ 1 1)))

;; Assert false
(should-not (= 3 (+ 1 1)))

;; Assert error
(should-error (/ 1 0) :type 'arith-error)

Key Features

Built-in: No installation required (Emacs 24+)
Interactive debugging: Backtrace inspection, test reruns
Flexible selectors: Run specific tests by name, tag, or status
Batch mode: CI/CD integration with exit codes
Mocking support: Easy mocking via dynamic binding
Rich assertions: Detailed failure reporting with subexpression values

Common Patterns

Temporary Buffers

(ert-deftest test-buffer-operation ()
  (with-temp-buffer
    (insert "test content")
    (my-function)
    (should (string= (buffer-string) "expected"))))

Cleanup with unwind-protect

(ert-deftest test-with-cleanup ()
  (let ((temp-file (make-temp-file "test-")))
    (unwind-protect
        (progn
          (write-region "data" nil temp-file)
          (should (file-exists-p temp-file)))
      (delete-file temp-file))))

Mocking Functions

(ert-deftest test-with-mock ()
  (cl-letf (((symbol-function 'external-call)
             (lambda () "mocked result")))
    (should (string= "mocked result" (my-function)))))

Test Organization with Tags

(ert-deftest test-quick-operation ()
  :tags '(quick unit)
  (should (fast-function)))

;; Run only quick tests
M-x ert RET :tag quick RET

Interactive Debugging Commands

When viewing test results (after M-x ert):

. - Jump to test definition
d - Re-run test with debugger
b - Show backtrace
r - Re-run test
R - Re-run all tests
l - Show executed assertions
m - Show messages

Best Practices

Name tests descriptively: package-test-feature format
One assertion focus per test: Makes failures clear
Isolate test environment: Use let, temporary buffers
Always cleanup: Use unwind-protect for resources
Tag tests: Organize by speed and type
Test error cases: Use should-error for edge cases
Mock external dependencies: Avoid filesystem/network I/O

Using the Skill

This skill provides:

Complete API reference for all ERT functions
Comprehensive best practices and patterns
Detailed examples for common testing scenarios
Debugging techniques and workflow integration
CI/CD integration examples

Consult SKILL.md for in-depth documentation.

Learning Path

Basics: ert-deftest, should, running tests interactively
Assertions: should-not, should-error with error types
Environment: with-temp-buffer, let, unwind-protect
Organization: Tags, test naming, selectors
Advanced: Mocking, fixtures, custom assertions
Integration: Batch mode, CI/CD, Makefiles

3.5 KiB Raw Permalink Blame History