python-pytest.el
is an emacs package
to integrate the python pytest test runner.
most functionality can be used via a dispatcher popup menu built using transient, which gives a look and feel similar to the fantastic magit package.
python-pytest.el
offers these awesome features:
- various commands with ‘do what i mean’ (dwim) behaviour,
using heuristics to automatically detect test files and test
functions:
- run all tests
- rerun previous failures
- repeat the last invocation
- run only tests for the current python (test) module
- run only tests for the current (test) function
- easy way to change common switches and options, e.g. toggling output capture, failing after the first error, and so on.
- edit the automatically generated command line before executing,
by invoking commands with a prefix argument (
C-u
). - basic debugger integration using the pdb tracking support from the built-in python-mode package, which will automatically open source files at the right location.
- work simultaneously on multiple python projects. each project will use its own dedicated pytest output buffer.
- various customisation options, e.g. to change whether a generated command line should be shown for editing by default.
- hooks that get run before and after running pytest, which can be used to add custom behaviour.
Output -c color (--color) -q quiet (--quiet) -s no output capture (--capture=no) -v verbosity ([--verbose|--verbose --verbose]) Selection, filtering, ordering -k only names matching expression (-k=) --dm run doctests (--doctest-modules) -m only marks matching expression (-m=) --nf new first (--new-first) --sw stepwise (--stepwise) Failures, errors, debugging -l show locals (--showlocals) --ff failed first (--failed-first) -p debug on error (--pdb) --ft full tracebacks (--full-trace) -x exit after first failure (--exitfirst) --mf exit after N failures or errors (--maxfail=10) --rx run xfail tests (--runxfail) --tb traceback style (--tb=) --tr debug on each test (--trace) Run tests t all r repeat f file (dwim) m files d def/class (dwim) x last failed F file (this) M directories D def/class (this)
python-pytest.el
is available from melpa.
with use-package
:
(use-package python-pytest)
install manually:
M-x package-install RET python-pytest RET
note that python-pytest.el
uses projectile
for some of its features, e.g. finding associated test files.
this package is intended to work correctly
even without any projectile
configuration,
since it will likely do the right thing
if a project has a conventional layout.
the typical usage pattern is to invoke the popup menu,
named python-pytest-dispatch
.
it is a good idea to create a dedicated keybinding for this command,
but it can also be run manually:
M-x python-pytest-dispatch
this shows a dispatcher menu. change some switches and options, then run one of the actions.
a dedicated pytest comint
buffer will open,
showing the output in real time,
and allowing interaction with debuggers.
this package ultimately invokes pytest
.
python-pytest.el
does not guess execution environments,
so emacs needs to use the right exec-path
,
taking into account python virtual environments, and so on.
to manage the execution environment, consider using direnv:
it can change (and revert) paths and environment variables,
simply by switching to a project directory,
making it perfect for automatically ‘activating’ a virtualenv
.
use emacs-direnv and possibly exec-path-from-shell
to achieve the same inside emacs.
by default, pytest
is run from the project root directory. if
your package is not at the root of your repository, pytest
might
not find your modules.
a workaround is to add the the package root to PYTHONPATH
before
running the tests. this can be found by adding a dummy file in the package
root. the following hook looks for a .pyroot
file in parent directories.
if found, it adds the directory of the file to PYTHONPATH
.
(add-hook 'python-mode-hook
(lambda ()
(when-let ((r (locate-dominating-file default-directory ".pyroot")))
(setq python-pytest-executable
(concat "PYTHONPATH=" r " " "pytest")))))
to edit the command line before running it,
use a prefix argument before calling the action,
e.g.type C-u t
instead of just t
in the popup menu.
when the popup menu itself is invoked with a prefix argument,
this will run python-pytest-repeat
to rerun pytest.
this means a single key binding can be used for both
an initial run (via the popup), and for repeated calls.
this is great for quick ‘edit, test, edit, test` cycles.
the available commands are:
python-pytest
python-pytest-file
python-pytest-file-dwim
python-pytest-files
python-pytest-function
python-pytest-function-dwim
python-pytest-last-failed
python-pytest-repeat
all of these are available via the popup menu, but can also be executed directly (or bound to a key).
this package uses a few heuristics for its ‘do what i mean’ behaviour.
the python-pytest-file-dwim
command tries to
do the right thing both when editing the actual code
and its associated test module.
for instance, when editing foo/bar.py
,
this will automatically detect tests/test_bar.py
(thanks to the projectile
package),
and only run the tests from that test module.
the python-pytest-function-dwim
command
tries to run only tests related to the function
close to the cursor position
(‘point’ in emacs terminology).
when editing a test module, this runs only a single test function, namely the one currently being edited.
when editing the code itself,
things are more complicated.
this command will make a guess
to only run the right test functions.
the matching behaviour can be tweaked using
python-pytest-strict-test-name-matching
(see configuration below).
by default, the current function name will be used
as a pattern to match the corresponding tests.
for example, when editing foo()
inside utils.py
,
this will match test_foo()
as well as test_foo_xyz()
,
by invoking pytest test_utils.py -k test_foo
.
if a pattern was specified in the popup (the -k
option),
it will try to make a combined pattern,
by invoking pytest test_utils.py -k 'test_foo and other_filter'
.
on the other hand,
when python-pytest-strict-test-name-matching
is non-nil,
only test_foo()
will match, and nothing else,
by invoking pytest test_utils.py::test_foo
.
the behaviour of this package can be tweaked
by customising a few defcustom variables.
use the customize
interface to explore those
(each will show a description and possible values):
M-x customize-group RET python-pytest RET
to set those permanently without using the customize interface,
use something like this in init.el
:
(use-package python-pytest
:custom
(python-pytest-confirm t))
the available variables are:
python-pytest-confirm
whether to ask for confirmation (allowing editing) by default. this inverts the prefix argument (
C-u
) behaviour.python-pytest-strict-test-name-matching
Whether to require a strict match for the ‘test this function’ heuristic.
python-pytest-executable
the name of the pytest executable (
pytest
by default)python-pytest-unsaved-buffers-behavior
whether to ask whether unsaved buffers should be saved before running pytest. the check for unsaved buffers can be for only the current buffer, or for all project buffers, and those can be saved directly, or after confirmation. valid values:
ask-all
,ask-current
,save-all
,save-current
, ornil
.python-pytest-setup-hook
,python-pytest-started-hook
, andpython-pytest-finished-hook
hooks run before starting
pytest
, after startingpytest
, and afterpytest
finished.python-pytest-buffer-name
andpython-pytest-project-name-in-buffer-name
the defaults result in
*pytest*<project-name>
.python-pytest-pdb-track
whether to enable the pdb tracking support
when using pytest plugins that provide extra switches, it may be useful to integrate those into the popup. see the transient manual for more information.
as an example, this will add a -z
switch that,
when enabled, will invoke pytest --zzz
:
(use-package python-pytest
:config
;; just an extra `-y' after the `-x' suffix
(transient-append-suffix
'python-pytest-dispatch
"-x"
'("-y" "The Y" "-y"))
;; group with `-z' after second from the last group,
;; that is before `Run tests'
(transient-append-suffix
'python-pytest-dispatch
'(-2)
["My Z"
("-z" "The Z" "-z")]))
transient lets you save defaults you want for it.
just select all options on python-pytest-dispatch
and then
C-x C-s
to save current settings as default and make them persistent,C-x s
to save current settings as default for the current emacs session.
praise? complaints? bugs? questions? ideas?
please use the github issue tracker.
this package was created by wouter bolsterlee. i am @wbolster on github and twitter.
note:
melpa automatically ships the latest code from the git main
branch,
while melpa stable only contains tagged (released) versions.
- add dispatch options for pytest-xdist (#54)
- respect
projectile-compilation-dir
if it exists (#59) - Use
read-shell-command
instead ofread-from-minibuffer
(#60) - add
0
as a valid argument that can be passed to-n
(#61) - switch to
compilation-mode
after pytest process finishes (#62) - fix saving of verbosity setting (#64)
- do not use melpa unstable versions in package-requires (#52)
- make python-pytest-files show all files if no test files are found (#38)
- display buffer window before starting comint to fix size detection (#48)
- correctly handle -m and -k flags (#37)
- fix clearing test output buffer (#15)
- redesign the menu:
use better groupings,
use multi-column visual layout,
add some more flags,
make all flags start with either
-
or--
(mostly mimicking pytest flags) (#28) - add a
python-pytest-directories
command with interactive multi-directory selection (#21, #31)
- switch to
transient
(magit-popup
replacement); the command for the menu is nowpython-pytest-dispatch
(#18, #26) - add
python-pytest-files
command with interactive multi-file selection - improve
python-pytest-file-dwim
heuristic for nested functions/classes - make
next-error
and related-commands work - add a
-w
shortcut for very verbose (--verbose --verbose
) (#24)
- this package is useful for quite a few people. time to celebrate with a 1.x release!
- save (or ask to save) modified buffers before running pytest (#4)
- put customizable variables in the right group
- fix package version number for melpa stable
- repopulate the popup with the previously used values
when running
python-pytest-dispatch
from an output buffer. (#3)
- avoid
-as->
macro since thedash.el
version currently on melpa stable does not have it. (#2)
- fix autoloading for
python-pytest-popup
command
- now available from melpa (#1)
- more docs
- various ‘dwim’ improvements
- renamed and added a few popup flags
- improved relative path handling
- improved hooks
- improved history
- better shell escaping
- remember current command in output buffer to make repeating work
- misc other tweaks and fixes
- initial release
(this is the osi approved 3-clause "new bsd license".)
copyright 2018 wouter bolsterlee
all rights reserved.
redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- neither the name of the author nor the names of the contributors may be used to endorse or promote products derived from this software without specific prior written permission.
this software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. in no event shall the copyright holder or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.