abl-mode

abl-mode is a minor mode for python programmers who develop using virtual environments, version control branches and unit tests.

What does it do?

abl-mode is ideal for developers who switch development branches frequently, and create python virtual environments for these individual branches. When you run a test with C-c t or start a server with C-c r, abl-mode checks the availability of a virtual environment for the branch you're on. The name of the virtual environment is determined according to the name of the project and the VCS branch. If there is no such virtual environment, the user is prompted either for the name of a replacement virtual environment, or y for creating a new virtual environment. Once you've run a test, and made some changes depending on the results, you can rerun the same test with C-c u.

Installing

abl-mode is on melpa, so you should be able to install it with package. An easy way to automatically download on first load and configure abl-mode is using the excellent use-package tool, by including the following in your Emacs configuration:

(use-package abl-mode
  :ensure t
  :custom (abl-mode-install-command "pip install -r requirements.txt && python setup.py develop")
  (abl-mode-test-path-module-class-separator ":")
  :hook python-mode)

Development

Check out this repository, and include the following in your Emacs configuration:

(use-package abl-mode
  :load-path "~/projects/abl-mode"
  :hook python-mode)

Commands and their default key bindings

Key	Function
M-x abl-mode	Toggle abl-mode
C-c t	Run test at point. See below for detailed explanation
C-c u	Rerun last test entity (whatever was run the last time with C-c t)
C-c s	Run the python shell for the virtualenv of this branch
C-c o	Open the python entity at point. The python entity must be in the format package.name:ClassName.function_name

Running Tests

Here is how the tests to run are determined:

If the name of the file does not match abl-mode-test-file-regexp, it is assumed that this is not a test file, but a code file. In that case, the beginning of the file is searched (using the regular expressions in abl-mode-code-file-tests-regexps) for a line that lists the tests for that file. The format for this line is tests: wherever/the_tests_are.py. If no such header is found, an error is shown.

If the file is a test file, which test is run depends on the location of the cursor. If it is at the start of the file, the whole file is run. If it is in an individual test, that test is run. If it is in a test class but not in a test, that test class is run.

Customization

You can set any of the following options either by including a line such as the following in your .emacs file::

(setq option-name new-value)

Or by listing project-local customization options in a file named .abl at the base level of a project, i.e. where the setup.py file is located. The customization line in such a file should start with the option name, followed by the value, such as::

abl-mode-test-command "ENV_VAR=\"env var value\"" pytest -x %s"

As you can see here, the value should be as you would include it in your configuration; it is read and evaluated, so that logical values such as nil or t can also be used. String formatting is similar to the way it is done in Python; %s gets replaced by the relevant value when the option gets used.

Option	Function
abl-mode-check-and-activate-ve	Whether a the existence of a suitable virtual environment should be checked, and the virtualenv activation command should be included with each command run. Default: t
abl-mode-ve-activate-command	The command used for activating a python virtual environment. Default: workon %s
abl-mode-ve-create-command	The command used for activating a python virtual environment. Default: mkvirtualenv create %s
abl-mode-test-command	The command used to run unit tests. Default: python -m unittest %s
abl-mode-ve-base-dir	The directory in which new virtual environments are stored. This should be the same directory in which the above mentioned virtualenv commands create the environments. Default: ~/.virtualenvs
abl-mode-install-command	The command used to install a development package. This command is run to install dependencies when a virtualenv is created. Default: python setup.py develop
abl-mode-test-file-regexp	Regular expression used to determine whether a file contains tests. Default: .*_tests.py
abl-mode-code-file-tests-regexps	List of regular expressions used to search for a test files list in a code file.
abl-mode-branch-shell-prefix	The string appended to the name of the shell buffer created to run tests. Default: ABL-SHELL:

Running the tests

export HOME=/tmp/temporaryhome
mkdir -p $HOME/.emacs.d
cp testing-files/init.el $HOME/.emacs.d
emacs -L . -l ert -l $HOME/.emacs.d/init.el  -l test.el --batch -f ert-run-tests-batch-and-exit

This will run all the tests in test.el. If you want to run a single test, use the following, more complicated command:

emacs -L . -l ert -l $HOME/.emacs.d/init.el  -l test.el --batch --eval '(let ((ert-quiet t)) (ert-run-tests-batch-and-exit "test-git-abl"))'

TODOs

[ ] Unify configuration option names [ ] Keybinding to run all tests [ ] abl-mode for go [ ] abl-mode for elisp [ ] abl-mode for js [ ] Option to add an argument to test run with C-u (e.g. -x for pytest)

[x] Fix failing tests & improve testing (23.09.2021)