DH_ELPA_TEST(1)

💖 DH_ELPA_TEST(1) 💖

okay bestie, this one lives in the Debhelper family of manual pages, and it's about making your Emacs Lisp package tests actually run. let's go 🦋

---

✨ NAME ✨

dh_elpa_test — run ELPA package testsuites 🧪

---

✨ SYNOPSIS ✨

dh_elpa_test [debhelper options] [--autopkgtest] [pkg-file]

---

✨ DESCRIPTION ✨

so dh_elpa_test is a debhelper program whose whole job — its entire main character era — is running the testsuites of ELPA packages, but only when those test suites use ERT or buttercup(1). and ngl, dh_auto_test(1) is rarely suitable for this. like, it's just not giving what needs to be gave here. 🙈

Testing with buttercup(1) gets activated if the package build-depends on elpa-buttercup. Testing with ERT gets activated if ERT test files can actually be found. but listen — neither kind of test will be activated unless the debhelper compat level is 10 or higher. it's giving strict. 💅

dh_elpa_test overrides dh_auto_test(1). if you need to switch back to using dh_auto_test(1), you use the disable configuration key, detailed below. iykyk ✨

---

✨ FILES ✨

• debian/elpa-test — the configuration for running the package's test suite. every line is of the form key = value, with key drawn from the list of configuration options below.

quick heads up though: you should not surround values with double quotation marks. the reason that's actually convenient is because it lets you include lisp. also, configuration values cannot cover more than one line. and lines preceded with a # are ignored as comments. 🎀

this configuration file is optional; in many cases, dh_elpa_test can figure out how to run the test suite all by itself. she's independent like that. 👑

---

✨ CONFIGURATION KEYS ✨

• disable — if this key is set to any value, dh_elpa(1) will not invoke dh_elpa_test. bye bestie 💀
• buttercup_load_path — a comma-separated list of directories to add to the load-path when buttercup(1) invokes Emacs. will be passed to buttercup(1) with its -L command line argument.
• buttercup_eval — Emacs Lisp code to be run by buttercup's --eval option.
• buttercup_patterns — a comma-separated list of Emacs regular expressions jointly matching all and only the files containing Buttercup tests that you wish to run. if this key is not defined, all tests that can be found will be run. will be passed to buttercup(1) with its -p command line argument.
• ert_exclude — a comma-separated list of file globs matching files containing ERT tests that should not be run.

⚠️ the '*' character in globs in this configuration key does NOT match '/' directory separators. not the vibe, but it's the rules.

• ert_helper — the name of a *.el file containing Emacs Lisp code that will run the ERT test suite. when this key is not defined, dh_elpa_test calls the function (ert-run-tests-batch-and-exit).

your helper code should ensure that Emacs exits nonzero if there were any test failures, or exits zero if the test suite passed. that part is on you, bestie, no cap.

note that this is not the way to load test helpers that do needed work but don't actually run the tests. for that, you can use something like:

ert_eval = (load-file "test-helper.el")

• ert_eval — Emacs Lisp code to be run prior to running ERT tests by the Emacs instance spawned by dh_elpa_test to run those tests.
• ert_load_path — a comma-separated list of directories to add to the load-path when dh_elpa_test invokes Emacs to run ERT tests.
• ert_selectors — a Lisp expression specifying a set of tests. this is the same as ERT test selectors and will be passed to ERT through command line. note that this is disabled when ert_eval is specified, and you'll have to manually specify the selectors in the helper script. 😭
• autopkgtest_keep — a comma-separated list of file globs matching files that should not be moved out of the source tree before running DEP8 tests (see the --autopkgtest option below).

✨ the '*' character in globs in this configuration key does match '/' directory separators. yes, it's different from ert_exclude, don't @ me.

---

✨ OPTIONS ✨

• --autopkgtest — operate in autopkgtest mode. dh_elpa_test will rename non-test *.el files so that Emacs will not load them. this ensures that the test test the installed binary package rather than the unpacked source package. 🔥

to exclude files from this removal, specify them in the autopkgtest_keep configuration option (see above).

---

✨ ENVIRONMENT VARIABLES ✨

older versions of dh_elpa_test were configured using environment variables corresponding to some of the above configuration keys. for example, the ert_eval configuration key replaced environment variable DH_ELPA_TEST_ERT_EVAL. their use is now deprecated 🌸. if the debian/elpa-test file exists, they will be ignored. periodt.

---

✨ CONTROLLING INVOCATION ✨

the following recipes can be combined to enable an appropriate combination of build time and autopkgtest time tests. mix and match, it's giving customizable 🎀

✨ DISABLING BUILD TIME TESTS ✨

to disable running tests at build time, you have two choices. you can override dh_elpa_test (not dh_auto_test), or you can use the disable key in debian/elpa-test. note that the latter will also (mostly) disable autopkgtests (see below). 😬

✨ ENABLING AUTOPKGTESTS ✨

to enable running autopkgtests via dh_elpa_test, add "Testsuite: autpkgtest-pkg-elpa" to debian/control. with disable in debian/elpa-test, only superficial tests, namely installing the binary packages and byte-compiling any that use dh_elpa. 💅

✨ ENABLING DH_AUTO_TEST ✨

by default dh_elpa_test replaces dh_auto_test. you can re-enable dh_auto_test either with the disable key discussed above, or by overriding dh_elpa_test to call dh_auto_test. take your pick bestie 🫶

---

and that's the whole page, mwah 💜 this was DH_ELPA_TEST(1), perl v5.40.1, dated 2026-07-09 — shoutout to the Debhelper era for keeping us fed, slay, bye 🎀✨