aboutsummaryrefslogtreecommitdiff

Overview

pearl uses ERT for tests, Eask to manage the test sandbox and dependencies, and undercover for coverage reports. A root Makefile drives everything and delegates test targets to tests/Makefile.

Prerequisites

  • Emacs 27.1+
  • Eask on PATH (npm install -g @emacs-eask/cli, or the standalone installer)

First-time setup

make setup

Installs runtime deps (request, dash, s) and development deps (elisp-lint, package-lint, undercover) into a project-local .eask/ sandbox.

Note on Eask's global package store

Eask keeps a global package store at ~/.eask/<emacs-version>/elpa/. When a dependency already sits there at the version the project wants, eask install-deps skips installing it into the project sandbox — but eask emacs (which runs the tests) only activates the project sandbox, so the dependency ends up "installed" yet unloadable. make setup guards against this: after eask install-deps it verifies each runtime dep is present in the sandbox and installs any that were skipped. The guard is a no-op where the global store is empty (fresh clones, CI).

Running tests

make test                      # all tests, excluding :slow
make test-all                  # all tests, including :slow
make test-unit                 # unit tests only
make test-integration          # integration tests only
make test-file FILE=mapping    # one file (fuzzy match on name)
make test-one TEST=priority    # one test (fuzzy match on name)
make test-name TEST='pattern'  # tests matching an ERT name pattern

Coverage

make coverage

Cleans .elc files (so undercover can instrument the source), runs every test file in its own Emacs process with pearl.el instrumented, and merges per-file results into .coverage/simplecov.json. Under CI (CI=true) it emits .coverage/coveralls.json instead for upload.

Other targets

make validate    # parens-balance check (no deps needed)
make compile     # byte-compile pearl.el (warnings are errors)
make lint        # elisp-lint over pearl.el
make count       # count tests per file
make list        # list all test names
make clean       # remove .elc, logs, and .coverage
make help        # full target list

make compile (warnings as errors), make lint, and eask lint checkdoc are all clean; keep them that way as part of normal maintenance.

Writing tests

  • One test file per source function/area: tests/test-pearl-<area>.el.
  • Start each file with (require 'test-bootstrap (expand-file-name "test-bootstrap.el")) — it loads the deps and the package source.
  • Name tests test-pearl-<function>-<scenario>-<expected>.
  • Cover Normal, Boundary, and Error cases.
  • Tag slow tests with :tags '(:slow) so the default make test skips them.
  • Integration files are named tests/test-integration-*.el.

Mirrored at github.com/cjennings.