Development targets Emacs 30.1, which is also the minimum the package declares: what CI runs, and what most users are on. 29 was supported until Eglot's differences there became a source of bugs – one sent every language server request to a local process, answering about the wrong machine's files, and stayed invisible for weeks because 29 was where it was being tested.

make versions says which Emacs is in use and whether it is the target.

The sources are in src/, listed here from the bottom layer up. Each file requires only files earlier in this table, never later ones.

Each check runs once per event, in one workflow unless only another can do it:

Pushes to other branches run nothing until a pull request is opened, and a newer push to the same branch cancels a run still going. Build also runs for changes to the documentation, the tools, the notebook corpus and the MELPA recipe, not only the Lisp.

The release tests what it ships, and is the only run a tag starts: the version commit is often pushed with [skip ci], so nothing else has tested it. Path filters do not apply to tag pushes, which is why a tag used to start Build and Coverage as well – the suite four times over.

What CI runs, in the order worth running it: the cheap checks first, so a typo does not cost a server start-up.

The self-contained suite requires only websocket:

make test
# which is
emacs -batch -Q -L src -l src/emjupy-run-tests.el

websocket is resolved from load-path first, then from EMJUPY_WEBSOCKET_DIR, and only then from GNU ELPA – so the suite also runs offline / in CI:

EMJUPY_WEBSOCKET_DIR=/path/to/emacs-websocket make test

emjupy-integration-test.el talks to a live Jupyter server and runs real Python in a real kernel. These are opt-in and ert-skip unless the environment points at a running server, so the default run stays fast and hermetic.

Some things only break against a live server – an image arriving that this Emacs cannot display, a WebSocket URL that drops its base path, a saved notebook no other tool will open – so they are worth running before trusting a change.

To exercise the remote path, point EMJUPY_TEST_URL at the local end of an ssh tunnel rather than at the server directly:

# server side: jupyter listens only on loopback
jupyter server --no-browser --port=8888 --ip=127.0.0.1 --IdentityProvider.token=abc

# client side: forward a local port through ssh
ssh -N -L 18888:127.0.0.1:8888 user@remote-host &

EMJUPY_TEST_URL=127.0.0.1:18888 EMJUPY_TEST_TOKEN=abc \
EMJUPY_TEST_ROOT=/path/to/notebook/root make check

The language-server tests come in two kinds. Those of the WebSocket transport need jupyter-lsp and python-lsp-server in the environment running the server – the pip line above installs both. Those of the local fallback need a language server on this machine's PATH (pylsp, pyright-langserver or jedi-language-server), and skip if none is found.

src/emjupy-robustness-test.el holds the tests that make their own inputs. They run with the rest of make test, and each found a bug the hand-written tests had not.

A unit test must give the same answer on every machine. Two things in emjupy make that easy to lose: the host of an SSH tunnel is found by reading the process list, and whether LaTeX can be rendered is decided by looking for the programs that render it. Both are correct in use and wrong in a test.

emjupy-probe-environment governs both, and the unit test runner binds it to nil. A test that needs the detection tested – as opposed to merely used – binds it back to t and stubs what it examines.

This is not hypothetical: two tests asking what a tunnelled server resolves to passed here and failed on a machine that happened to be forwarding that port, and a LaTeX test depended on whether LaTeX was installed.

Other rules worth following, each learned from a test that passed while the thing it covered was broken:

• Test the key binding, not only the function behind it. A command bound to DEL alone is not reached in a graphical Emacs that sends <backspace>.
• Do not wrap the action under test in ignore-errors. A test that guards against remote connections passed because the connection it should have caught raised an error which was then swallowed.
• When a stub replaces a function used by Emacs itself, call through for the cases the test is not about.
• Prefer asserting an invariant over asserting a mechanism; mechanisms differ between Emacs versions, invariants do not.

M-x emjupy-debug-check-invariants reports how a buffer and its cells disagree: which cell, and whether its overlay is missing, overlapping, out of order, detached from its output box, or showing text the cell does not hold. The last means what is displayed and what would be saved have come apart.

Tests call it after every operation. It has caught overlays left overlapping after a split, and a sync that turned an empty cell into one containing a newline.

Three tests guard against regressions rather than measuring speed:

• work done after every command does not grow with the notebook;
• redrawing output does not grow with the notebook, since only the cell concerned is redrawn;
• nothing on a path that runs after a command touches a remote file.

The last matters most. A remote operation costs a round trip, TRAMP blocks Emacs while it waits, and anything on the per-command path pays that on every keystroke. The test asserts the absence of such calls rather than a duration, since a duration would depend on a network.

The per-command costs these keep small are measured in Language server support.

1. Set the version. From GitHub: Actions, "Set version", "Run workflow", and give it the new version as X.Y.Z. It writes the version everywhere the current one appears – the ;; Version: header, emjupy-version, src/emjupy-pkg.el and the sample output in docs/usage.org – checks they agree, and commits the change. Or locally, the same script: make set-version VERSION=X.Y.Z.

1. Tag the commit with the same version and push the tag. That starts the release: the tests, the tarball on the release page, and the documentation site, all from that commit. The workflow does not tag for you: a tag pushed from a workflow does not start other workflows, so the release would not run.

   A commit whose message contains [skip ci] is skipped for tag pushes too. Tag a commit without it, or the release never starts.

C-h P emjupy shows the ;;; Commentary: section of src/emjupy.el: what emjupy is, what it needs, and how to start. It is written for someone who has only just installed the package and has not seen the repository.

package.el prefers an installed package's README to its Commentary, and the README is a web page – badges, screenshots, links into the repository – so the tarball make package builds carries no README. MELPA leaves it out for the same reason, so both describe themselves alike. An install from git with package-vc is the whole checkout, and shows the README.

The opening paragraph is the same in three places – the Commentary, the README and docs/index.org – and is worth keeping so when one changes. The one-line summary is the same in the header of src/emjupy.el and in src/emjupy-pkg.el.

The recipe must list the files explicitly. A recipe without :files takes every .el in the repository, which here would ship the tests to users and include emjupy-run-tests.el, a script with no provide form that package-lint rejects.

The recipe used is kept at .github/melpa-recipe:

(emjupy :fetcher github
        :repo "mathren/emjupy"
        :files ("src/emjupy.el"
                "src/emjupy-core.el"
                "src/emjupy-http.el"
                "src/emjupy-render.el"
                "src/emjupy-cells.el"
                "src/emjupy-kernel.el"
                "src/emjupy-figures.el"
                "src/emjupy-widgets.el"
                "src/emjupy-widget-page.el"
                "src/emjupy-figure-window.py"
                "src/emjupy-remote.el"
                "src/emjupy-lsp.el"
                "src/emjupy-eglot.el"
                "src/emjupy-mode.el"
                "src/emjupy-notebook.el"))

The recipe lists the sources by name rather than by wildcard, so a development file added to src/ does not ship by accident. The melpazoid job in CI reads this same file, so there is one list.

Before submitting:

make check                 # unit and integration tests
make lint                  # checkdoc and package-lint
make package               # builds the tar

and check that:

• melpazoid reports nothing – its CI job runs it against the recipe above, with warnings treated as errors;
• the tar installs into an empty package-user-dir and M-x emjupy-mode works there;
• each module loads on its own in a fresh Emacs, since that is how an accidental dependency on load order shows up.