Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 45 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,44 +1,57 @@
# Pytrize

## Short summary

Helps navigating `pytest.mark.parametrize` entries and fixtures by virtual text and jump to declaration commands, using `pytest`s cache and `treesitter`.

![pytrize](https://user-images.githubusercontent.com/23341710/143510539-c025925c-0e4c-4990-83ab-1c0da076c0f8.gif)

## What problems does this plugin solve?

### Parametrize

`pytest` is amazing! The only thing that bothers me from time to time is if there are many entries in the parametrization of the test.
If a test fails you might see for example:

```
test.py::test[None2-a1-b-c1-8]
```

Now you want to see what test case this actually corresponds to.
What I sometimes do is to go to the entries in `pytest.mark.parametrize` and count the entries until I'm at the right one.
But this is really not nice and easy to make a mistake, we should let the computer do this for us.

Enter `pytrize`.

### Fixture

Another issue is knowing where a certain fixture is defined and what it does.

## What does the plugin do?
Three things:
* Populates virtual text at the entries of `pytest.mark.parametrize` (see gif above), such that you can easily see which one is which.

Several things:

- Populates virtual text at the entries of `pytest.mark.parametrize` (see gif above), such that you can easily see which one is which.
Done by calling `Pytrize` (and `PytrizeClear` to clear them).
Alternatively `lua require('pytrize.api').set()` (and `lua require('pytrize.api').clear()`).
* Provides a command to jump to the corresponding entry in `pytest.mark.parametrize` based on the test-case id under the cursor (see gif above).
- Provides a command to jump to the corresponding entry in `pytest.mark.parametrize` based on the test-case id under the cursor (see gif above).
Done by calling `PytrizeJump`.
Alternatively `lua require('pytrize.api').jump()`.
See the [Input](#input)-section below for cases where the file-path is not available.
* Provides a command to jump to the declaration of the fixture under the cursor (by name), see [fixture](#jump-to-fixture) below.
- Provides a command to jump to the declaration of the fixture under the cursor (by name), see [fixture](#jump-to-fixture) below.
Done by calling `PytrizeJumpFixture`.
Alternatively `lua require('pytrize.api').jump_fixture()`.
- Provides a command to rename the fixture under the cursor (by name), see [fixture](#rename-fixture) below.
Done by calling `PytrizeRenameFixture`.
Alternatively `lua require('pytrize.api').rename_fixture()`.

## Installation

For example using [`packer`](https://github.com/wbthomason/packer.nvim):

```lua
use { -- pytrize {{{
'AckslD/nvim-pytrize.lua',
'sigfriedcub1990/nvim-pytrize.lua',
-- uncomment if you want to lazy load
-- cmd = {'Pytrize', 'PytrizeClear', 'PytrizeJump'},
-- uncomment if you want to lazy load but not use the commands
Expand All @@ -48,9 +61,12 @@ use { -- pytrize {{{
```

For example using [`lazy.nvim`](https://github.com/folke/lazy.nvim):

```lua
use { -- pytrize {{{
'AckslD/nvim-pytrize.lua',
{
'sigfriedcub1990/nvim-pytrize.lua',
version = '*',
dependencies = { 'nvim-lua/plenary' },
ft = 'python', -- Load only for python files
opts = {},
-- uncomment if you want to lazy load
Expand All @@ -61,40 +77,54 @@ use { -- pytrize {{{
Requires [`plenary.nvim`](https://github.com/nvim-lua/plenary.nvim).

## Configuration

`require("pytrize").setup` takes an optional table of settings which currently have the default values:

```lua
{
no_commands = false,
highlight = 'LineNr',
preferred_input = 'telescope',
}
```

where:
* `no_commands` can be set to `true` and the commands `Pytrize` etc won't be declared.
* `highlight` defines the highlighting used for the virtual text.
* `preferred_input` which method to query input to prefer (if it's installed), see the [Input](#input)-section below.

- `no_commands` can be set to `true` and the commands `Pytrize` etc won't be declared.
- `highlight` defines the highlighting used for the virtual text.
- `preferred_input` which method to query input to prefer (if it's installed), see the [Input](#input)-section below.

## Details
* `pytest`s cache is used to find the test-case ids (eg `test.py::test[None2-a1-b-c1-8]`) which means that the tests have to be run at least once.

- `pytest`s cache is used to find the test-case ids (eg `test.py::test[None2-a1-b-c1-8]`) which means that the tests have to be run at least once.
Also old ids might confuse `pytrize`, but you can clear the cache with `pytest --cache-clear`.
* `treesitter` is used to find the correct entry in `pytest.mark.parametrize`.
- `treesitter` is used to find the correct entry in `pytest.mark.parametrize`.

## Jump to fixture

To jump to the declaration of a fixture under the cursor, do `PytrizeJumpFixture`:
![pytrize_fixture](https://user-images.githubusercontent.com/23341710/145707800-dcd49ae2-8fb1-46cc-8895-ed78ee5365b9.gif)

## Rename fixture

To rename the fixture under the cursor, do `PytrizeRenameFixture`:

## Input

In some cases the file-path is not printed by pytest, for example when a test fails when it might look something like:

```

_________________________________ test[None2-a1-b-c1-9] _________________________________
```

or similar.
If you trigger to jump to the declaration of the parameters in this case `pytrize` will find all files in the cache that matches this test-case id and if there is more than one ask you which one to jump to.
Currently three input methods are supported:
* [`telescope`](https://github.com/nvim-telescope/telescope.nvim)

- [`telescope`](https://github.com/nvim-telescope/telescope.nvim)
![pytrize_input_telescope](https://user-images.githubusercontent.com/23341710/145381466-42152977-f412-425d-9ddb-cc0c4dfde4fb.gif)
* [`nui`](https://github.com/MunifTanjim/nui.nvim)
- [`nui`](https://github.com/MunifTanjim/nui.nvim)
![pytrize_input_nui](https://user-images.githubusercontent.com/23341710/145381492-5e5abec0-c8c5-468c-90ee-b854e9d57146.gif)
* `inputlist` (neovim native)
- `inputlist` (neovim native)
![pytrize_input_builtin](https://user-images.githubusercontent.com/23341710/145381515-4afb6d1b-e6f5-4c55-bfc8-99d086f0f3b2.gif)