NAME

       dh_elpa_test - run ELPA package testsuites

SYNOPSIS

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

DESCRIPTION

       dh_elpa_test is a debhelper program that is responsible for running the testsuites of ELPA packages, when
       those test suites use ERT or buttercup(1).  dh_auto_test(1) is rarely suitable.

       Testing with buttercup(1) will be activated if the package build-depends on elpa-buttercup.  Testing with
       ERT will be activated if ERT test files can be found.  Neither kind of test will be activated unless the
       debhelper compat level is 10 or higher.

       dh_elpa_test overrides dh_auto_test(1).  If you need to switch back to use dh_auto_test(1), use the
       disable configuration key, below.

FILES

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

           Note that you should not surround values  with  double  quotation  marks.   This  is  convenient  for
           including  lisp.   Configuration values cannot cover more than one line.  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 itself.

CONFIGURATION KEYS

       disable
           If this key is set to any value, dh_elpa(1) will not invoke dh_elpa_test.

       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.

       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.

           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.

       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 matches '/' directory separators.

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.

CONTROLLING INVOCATION

       The  following recipes can be combined to enable an appropriate combination of build time and autopkgtest
       time tests.

   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.

perl v5.36.0                                       2023-09-15                                    DH_ELPA_TEST(1)