{"id":13862280,"url":"https://github.com/wbolster/emacs-python-pytest","last_synced_at":"2025-07-05T02:01:51.329Z","repository":{"id":29232540,"uuid":"120122424","full_name":"wbolster/emacs-python-pytest","owner":"wbolster","description":"run pytest inside emacs","archived":false,"fork":false,"pushed_at":"2024-11-05T18:31:10.000Z","size":118,"stargazers_count":161,"open_issues_count":8,"forks_count":27,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-28T09:06:51.654Z","etag":null,"topics":["emacs","pytest","python","test","unit-testing"],"latest_commit_sha":null,"homepage":null,"language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wbolster.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.rst","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-03T19:26:51.000Z","updated_at":"2025-03-04T12:42:40.000Z","dependencies_parsed_at":"2024-08-26T11:43:33.841Z","dependency_job_id":"ce07100a-2113-4c11-94f6-3fc005fce685","html_url":"https://github.com/wbolster/emacs-python-pytest","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wbolster%2Femacs-python-pytest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wbolster%2Femacs-python-pytest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wbolster%2Femacs-python-pytest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wbolster%2Femacs-python-pytest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wbolster","download_url":"https://codeload.github.com/wbolster/emacs-python-pytest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247157274,"owners_count":20893219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emacs","pytest","python","test","unit-testing"],"created_at":"2024-08-05T06:01:41.041Z","updated_at":"2025-04-04T10:07:10.002Z","avatar_url":"https://github.com/wbolster.png","language":"Emacs Lisp","readme":"================\npython-pytest.el\n================\n\n.. image:: https://melpa.org/packages/python-pytest-badge.svg\n   :alt: melpa badge\n\n.. image:: https://stable.melpa.org/packages/python-pytest-badge.svg\n   :alt: melpa stable badge\n\n\noverview\n========\n\n``python-pytest.el`` is an `emacs`__ package\nto integrate the python `pytest`__ test runner.\n\n__ https://www.gnu.org/software/emacs/\n__ https://pytest.org/\n\nmost functionality can be used via\na dispatcher popup menu built using `transient`__,\nwhich gives a look and feel\nsimilar to the fantastic `magit`__ package.\n\n__ https://magit.vc/manual/transient\n__ https://magit.vc/\n\n\nfeatures\n========\n\n``python-pytest.el`` offers these awesome features:\n\n* various commands with ‘do what i mean’ (dwim) behaviour,\n  using heuristics to automatically detect test files and test\n  functions:\n\n  * run all tests\n\n  * rerun previous failures\n\n  * repeat the last invocation\n\n  * run only tests for the current python (test) module\n\n  * run only tests for the current (test) function\n\n* easy way to change common switches and options, e.g.\n  toggling output capture, failing after the first error,\n  and so on.\n\n* edit the automatically generated command line before executing,\n  by invoking commands with a prefix argument (``C-u``).\n\n* basic debugger integration using the pdb tracking support\n  from the built-in `python-mode` package,\n  which will automatically open source files at the right location.\n\n* work simultaneously on multiple python projects.\n  each project will use its own dedicated pytest output buffer.\n\n* various customisation options, e.g. to change whether\n  a generated command line should be shown for editing by default.\n\n* hooks that get run before and after running pytest,\n  which can be used to add custom behaviour.\n\n\nscreenshot\n==========\n\n::\n\n  Output\n   -c color (--color)\n   -q quiet (--quiet)\n   -s no output capture (--capture=no)\n   -v verbosity ([--verbose|--verbose --verbose])\n\n  Selection, filtering, ordering\n   -k only names matching expression (-k=)      --dm run doctests (--doctest-modules)\n   -m only marks matching expression (-m=)      --nf new first (--new-first)\n                                                --sw stepwise (--stepwise)\n\n  Failures, errors, debugging\n   -l show locals (--showlocals)                --ff failed first (--failed-first)\n   -p debug on error (--pdb)                    --ft full tracebacks (--full-trace)\n   -x exit after first failure (--exitfirst)    --mf exit after N failures or errors (--maxfail=10)\n                                                --rx run xfail tests (--runxfail)\n                                                --tb traceback style (--tb=)\n                                                --tr debug on each test (--trace)\n\n  Run tests\n   t all    r repeat         f file (dwim)    m files          d def/class (dwim)\n            x last failed    F file (this)    M directories    D def/class (this)\n\n\ninstallation\n============\n\n``python-pytest.el`` is available from `melpa`__.\n\n__ https://melpa.org/#/python-pytest\n\nwith ``use-package``:\n\n.. code-block:: elisp\n\n  (use-package python-pytest)\n\ninstall manually::\n\n  M-x package-install RET python-pytest RET\n\nnote that ``python-pytest.el`` uses `projectile`__\nfor some of its features, e.g. finding associated test files.\nthis package is intended to work correctly\neven without any ``projectile`` configuration,\nsince it will likely do the right thing\nif a project has a conventional layout.\n\n__ https://github.com/bbatsov/projectile\n\nto run function/class tests, ``tree-sitter`` is needed, including the python language grammar::\n\n  M-x treesit-install-language-grammar\n\n\nusage\n=====\n\nbasics\n------\n\nthe typical usage pattern is to invoke the popup menu,\nnamed ``python-pytest-dispatch``.\nit is a good idea to create a dedicated keybinding for this command,\nbut it can also be run manually:\n\n::\n\n  M-x python-pytest-dispatch\n\nthis shows a dispatcher menu.\nchange some switches and options,\nthen run one of the actions.\n\na dedicated pytest ``comint`` buffer will open,\nshowing the output in real time,\nand allowing interaction with debuggers.\n\nusing the correct environment\n-----------------------------\n\nthis package ultimately invokes ``pytest``.\n``python-pytest.el`` does *not* guess execution environments,\nso emacs needs to use the right ``exec-path``,\ntaking into account python virtual environments, and so on.\n\nto manage the execution environment, consider using `direnv`__:\nit can change (and revert) paths and environment variables,\nsimply by switching to a project directory,\nmaking it perfect for automatically ‘activating’ a ``virtualenv``.\nuse `emacs-direnv`__ and possibly `exec-path-from-shell`__\nto achieve the same inside emacs.\n\n__ https://direnv.net/\n__ https://github.com/wbolster/emacs-direnv\n__ https://github.com/purcell/exec-path-from-shell\n\nworking in a monorepo\n---------------------\n\nby default, ``pytest`` is run from the project root directory. if\nyour package is not at the root of your repository, ``pytest`` might\nnot find your modules.\n\na workaround is to add the the package root to ``PYTHONPATH`` before\nrunning the tests. this can be found by adding a dummy file in the package\nroot. the following hook looks for a ``.pyroot`` file in parent directories.\nif found, it adds the directory of the file to ``PYTHONPATH``.\n\n.. code-block:: elisp\n\n  (add-hook 'python-mode-hook\n            (lambda ()\n              (when-let ((r (locate-dominating-file default-directory \".pyroot\")))\n                (setq python-pytest-executable\n                      (concat \"PYTHONPATH=\" r \" \" \"pytest\")))))\n\n\nediting and repeating\n---------------------\n\nto edit the command line before running it,\nuse a prefix argument before calling the action,\ne.g.type ``C-u t`` instead of just ``t`` in the popup menu.\n\nwhen the popup menu itself is invoked with a prefix argument,\nthis will run ``python-pytest-repeat`` to rerun pytest.\nthis means a single key binding can be used for both\nan initial run (via the popup), and for repeated calls.\nthis is great for quick ‘edit, test, edit, test` cycles.\n\navailable commands\n------------------\n\nthe available commands are:\n\n- ``python-pytest``\n- ``python-pytest-file``\n- ``python-pytest-file-dwim``\n- ``python-pytest-files``\n- ``python-pytest-function``\n- ``python-pytest-function-dwim``\n- ``python-pytest-last-failed``\n- ``python-pytest-repeat``\n\nall of these are available via the popup menu,\nbut can also be executed directly (or bound to a key).\n\n\nheuristics\n==========\n\nthis package uses a few heuristics for its\n‘do what i mean’ behaviour.\n\ntest file heuristics\n--------------------\n\nthe ``python-pytest-file-dwim`` command tries to\ndo the right thing both when editing the actual code\nand its associated test module.\nfor instance, when editing ``foo/bar.py``,\nthis will automatically detect ``tests/test_bar.py``\n(thanks to the ``projectile`` package),\nand only run the tests from that test module.\n\ntest function heuristics\n------------------------\n\nthe ``python-pytest-function-dwim`` command\ntries to run only tests related to the function\nclose to the cursor position\n(‘point’ in emacs terminology).\n\nwhen editing a test module, this runs\nonly a single test function,\nnamely the one currently being edited.\n\nwhen editing the code itself,\nthings are more complicated.\nthis command will make a guess\nto only run the right test functions.\nthe matching behaviour can be tweaked using\n``python-pytest-strict-test-name-matching``\n(see configuration below).\n\nby default, the current function name will be used\nas a pattern to match the corresponding tests.\nfor example, when editing ``foo()`` inside ``utils.py``,\nthis will match ``test_foo()`` as well as ``test_foo_xyz()``,\nby invoking ``pytest test_utils.py -k test_foo``.\nif a pattern was specified in the popup (the ``-k`` option),\nit will try to make a combined pattern,\nby invoking ``pytest test_utils.py -k 'test_foo and other_filter'``.\n\non the other hand,\nwhen ``python-pytest-strict-test-name-matching`` is non-nil,\nonly ``test_foo()`` will match, and nothing else,\nby invoking ``pytest test_utils.py::test_foo``.\n\nconfiguration\n=============\n\nsettings\n--------\n\nthe behaviour of this package can be tweaked\nby customising a few `defcustom` variables.\nuse the ``customize`` interface to explore those\n(each will show a description and possible values)::\n\n  M-x customize-group RET python-pytest RET\n\nto set those permanently without using the customize interface,\nuse something like this in ``init.el``:\n\n.. code-block:: elisp\n\n  (use-package python-pytest\n   :custom\n   (python-pytest-confirm t))\n\nthe available variables are:\n\n- ``python-pytest-confirm``\n\n  whether to ask for confirmation (allowing editing) by default.\n  this inverts the prefix argument (``C-u``) behaviour.\n\n- ``python-pytest-strict-test-name-matching``\n\n  Whether to require a strict match for the ‘test this function’ heuristic.\n\n- ``python-pytest-executable``\n\n  the name of the pytest executable (``pytest`` by default)\n\n- ``python-pytest-unsaved-buffers-behavior``\n\n  whether to ask whether unsaved buffers should be saved before\n  running pytest. the check for unsaved buffers can be for only the\n  current buffer, or for all project buffers, and those can be saved\n  directly, or after confirmation. valid values: ``ask-all``,\n  ``ask-current``, ``save-all``, ``save-current``, or ``nil``.\n\n- ``python-pytest-setup-hook``,\n  ``python-pytest-started-hook``, and\n  ``python-pytest-finished-hook``\n\n  hooks run before starting ``pytest``, after starting ``pytest``,\n  and after ``pytest`` finished.\n\n- ``python-pytest-buffer-name`` and ``python-pytest-project-name-in-buffer-name``\n\n  the defaults result in ``*pytest*\u003cproject-name\u003e``.\n\n- ``python-pytest-pdb-track``\n\n  whether to enable the pdb tracking support\n\n\nextending the popup\n-------------------\n\nwhen using pytest plugins that provide extra switches,\nit may be useful to integrate those into the popup.\nsee the `transient`__ manual for more information.\n\n__ https://magit.vc/manual/transient\n\nas an example, this will add a ``-z`` switch that,\nwhen enabled, will invoke ``pytest --zzz``:\n\n.. code-block:: elisp\n\n  (use-package python-pytest\n   :config\n   ;; just an extra `-y' after the `-x' suffix\n   (transient-append-suffix\n     'python-pytest-dispatch\n     \"-x\"\n     '(\"-y\" \"The Y\" \"-y\"))\n   ;; group with `-z' after second from the last group,\n   ;; that is before `Run tests'\n   (transient-append-suffix\n     'python-pytest-dispatch\n     '(-2)\n     [\"My Z\"\n      (\"-z\" \"The Z\" \"-z\")]))\n\n`transient` lets you save defaults you want for it.\njust select all options on ``python-pytest-dispatch``\nand then\n\n- ``C-x C-s`` to save current settings as default and make\n  them persistent,\n- ``C-x s`` to save current settings as default for the\n  current emacs session.\n\n\ncontributing\n============\n\npraise? complaints? bugs? questions? ideas?\n\nplease use the github issue tracker.\n\n\ncredits\n=======\n\nthis package was created by wouter bolsterlee.\ni am @wbolster on `github`__ and `twitter`__.\n\n__ https://github.com/wbolster\n__ https://twitter.com/wbolster\n\n\nhistory\n=======\n\nnote:\n`melpa`__ automatically ships the latest code from the git ``main`` branch,\nwhile `melpa stable`__ only contains tagged (released) versions.\n\n__ https://melpa.org/\n__ https://stable.melpa.org/\n\ndevelopment branch\n------------------\n\n- prefer ``tree-sitter`` for function/class at point commands\n  (`#75 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/75\u003e`_)\n\n- add option ``--log-cli-level``\n  (`#74 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/74\u003e`_)\n\n- add ``project.el`` support\n  (`#73 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/73\u003e`_)\n\n- use ``completing-read-multiple`` for multiple files selection\n  (`#72 \u003chttps://github.com/wbolster/emacs-python-pytest/issues/72\u003e`_)\n\n3.4.0 (2024-03-14)\n------------------\n\n* add windows support\n  (`#68 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/68\u003e`_)\n\n* add ``-W`` argument to ignore warnings\n  (`#70 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/70\u003e`_)\n\n* add ``--collect-only`` option\n  (`#65 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/65\u003e`_)\n\n3.3.0 (2022-10-18)\n------------------\n\n* add dispatch options for pytest-xdist\n  (`#54 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/54\u003e`_)\n\n* respect ``projectile-compilation-dir`` if it exists\n  (`#59 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/59\u003e`_)\n\n* Use ``read-shell-command`` instead of ``read-from-minibuffer``\n  (`#60 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/60\u003e`_)\n\n* add ``0`` as a valid argument that can be passed to ``-n``\n  (`#61 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/61\u003e`_)\n\n* switch to ``compilation-mode`` after pytest process finishes\n  (`#62 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/62\u003e`_)\n\n* fix saving of verbosity setting\n  (`#64 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/64\u003e`_)\n\n3.2.0 (2021-11-11)\n------------------\n\n* do not use melpa unstable versions in package-requires\n  (`#52 \u003chttps://github.com/wbolster/emacs-python-pytest/issues/52\u003e`_)\n\n3.1.0 (2021-11-09)\n------------------\n\n* make python-pytest-files show all files if no test files are found\n  (`#38 \u003chttps://github.com/wbolster/emacs-python-pytest/issues/38\u003e`_)\n\n* display buffer window before starting comint to fix size detection\n  (`#48 \u003chttps://github.com/wbolster/emacs-python-pytest/issues/48\u003e`_)\n\n* correctly handle -m and -k flags\n  (`#37 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/37\u003e`_)\n\n* fix clearing test output buffer\n  (`#15 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/15\u003e`_)\n\n3.0.0 (2020-08-10)\n------------------\n\n* redesign the menu:\n  use better groupings,\n  use multi-column visual layout,\n  add some more flags,\n  make all flags start with either ``-`` or ``--``\n  (mostly mimicking pytest flags)\n  (`#28 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/28\u003e`_)\n\n* add a ``python-pytest-directories`` command with interactive\n  multi-directory selection\n  (`#21 \u003chttps://github.com/wbolster/emacs-python-pytest/issues/21\u003e`_,\n  `#31 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/31\u003e`_)\n\n2.0.0 (2020-08-04)\n------------------\n\n* switch to ``transient`` (``magit-popup`` replacement);\n  the command for the menu is now ``python-pytest-dispatch``\n  (`#18 \u003chttps://github.com/wbolster/emacs-python-pytest/issues/18\u003e`_,\n  `#26 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/26\u003e`_)\n\n* add ``python-pytest-files`` command with interactive multi-file\n  selection\n\n* improve ``python-pytest-file-dwim`` heuristic for nested functions/classes\n\n* make ``next-error`` and related-commands work\n\n* add a ``-w`` shortcut for very verbose (``--verbose --verbose``)\n  (`#24 \u003chttps://github.com/wbolster/emacs-python-pytest/pull/24\u003e`_)\n\n1.0.0 (2018-06-14)\n------------------\n\n* this package is useful for quite a few people.\n  time to celebrate with a 1.x release!\n\n* save (or ask to save) modified buffers before running pytest\n  (`#4 \u003chttps://github.com/wbolster/emacs-python-pytest/issues/4\u003e`_)\n\n* put customizable variables in the right group\n\n0.3.1 (2018–03-07)\n------------------\n\n* fix package version number for melpa stable\n\n0.3.0 (2018–03-07)\n------------------\n\n* repopulate the popup with the previously used values\n  when running ``python-pytest-dispatch`` from an output buffer.\n  (`#3 \u003chttps://github.com/wbolster/emacs-python-pytest/issues/3\u003e`_)\n\n0.2.2 (2018-02-26)\n------------------\n\n* avoid ``-as-\u003e`` macro since the ``dash.el`` version\n  currently on melpa stable does not have it.\n  (`#2 \u003chttps://github.com/wbolster/emacs-python-pytest/issues/2\u003e`_)\n\n0.2.1 (2018-02-22)\n------------------\n\n* fix autoloading for ``python-pytest-popup`` command\n\n0.2.0 (2018-02-19)\n------------------\n\n* now available from melpa\n  (`#1 \u003chttps://github.com/wbolster/emacs-python-pytest/issues/1\u003e`_)\n* more docs\n* various ‘dwim’ improvements\n* renamed and added a few popup flags\n* improved relative path handling\n* improved hooks\n* improved history\n* better shell escaping\n* remember current command in output buffer to make repeating work\n* misc other tweaks and fixes\n\n0.1.0 (2018-02-03)\n------------------\n\n* initial release\n\n\nlicense\n=======\n\n*(this is the osi approved 3-clause \"new bsd license\".)*\n\ncopyright 2018 wouter bolsterlee\n\nall rights reserved.\n\nredistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are met:\n\n* redistributions of source code must retain the above copyright notice, this\n  list of conditions and the following disclaimer.\n\n* redistributions in binary form must reproduce the above copyright notice, this\n  list of conditions and the following disclaimer in the documentation and/or\n  other materials provided with the distribution.\n\n* neither the name of the author nor the names of the contributors may be used\n  to endorse or promote products derived from this software without specific\n  prior written permission.\n\nthis software is provided by the copyright holders and contributors \"as is\" and\nany express or implied warranties, including, but not limited to, the implied\nwarranties of merchantability and fitness for a particular purpose are\ndisclaimed. in no event shall the copyright holder or contributors be liable\nfor any direct, indirect, incidental, special, exemplary, or consequential\ndamages (including, but not limited to, procurement of substitute goods or\nservices; loss of use, data, or profits; or business interruption) however\ncaused and on any theory of liability, whether in contract, strict liability,\nor tort (including negligence or otherwise) arising in any way out of the use\nof this software, even if advised of the possibility of such damage.\n","funding_links":[],"categories":["Emacs Lisp"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwbolster%2Femacs-python-pytest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwbolster%2Femacs-python-pytest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwbolster%2Femacs-python-pytest/lists"}