Should all pytest docs examples use types?

[ssbarnea]

At this moment, only some of pytest documentation uses types and that is not teach test authors to start using them.

Finding the right types to add to test method signatures is not obvious for all users. If we would include already fully types examples across the documentation, it would be much easier to disseminate their use, especially as lots of people start with a copy/paste from documentation.

Once they want to change anything to the copied example, they would be able to benefit from IDE suggestions (auto-complete) when they have types.

Optionally, once we do add missing type, we should also be able to add a check to documentation building that ensures that mypy --strict is passing on examples, so regressions would be prevented.

Yes, adding types would make the examples more verbose. Still, I do think that this is a small price to pay for getting them more informative and more practical to use. This downside is likely not so bad as adding types would likely also reduce the need for code comments a little bit, due to the extra information being provided by the argument type.

Here is an example about what to expect:

Current example

# content of test_tmp_path.py
def test_needsfiles(tmp_path):
    print(tmp_path)
    assert 0

New example

# content of test_tmp_path.py
from pathlib import Path

def test_needsfiles(tmp_path: Path) -> None:
    print(tmp_path)
    assert 0

[ssbarnea]

@okken I hope that the next revision of your book will have fully typed examples. While this makes them bit more verbose, it would make it much easier for people learning to use pytest, to also write them future proof and easy to maintain.

[The-Compiler]

I'm going for a [citation needed] here. As someone who has done some 30-40 pytest trainings in companies and at conferences so far: While I recommend type annotations for fixture arguments on tests (because those are rather implicit, and e.g. VS Code doesn't resolve them otherwise), my experience is that they're typically more of a distraction (especially for people who have not seen them before) - I certainly wouldn't claim they make it "much easier for people learning to use pytest".

[ssbarnea]

@The-Compiler Yep, the keep an example simple does conflict with the goal of making someone become proficient. When you write your first test, probably is easier to forget about types, but once you start doing it for "production" purposes (long term maintained code), you likely do not want to avoid the types.

There is also another aspect which makes me believe that probably (new) engineers should learn about types before learning about pytest: the less experimented are more likely to use an IDE like vscode, and if they use types, that will give them a huge boost while using the IDE (that is why I sad about easier to learn).

While I do probably have more than a decade using pytest, I got used to the extra type verbosity in the last two years. The ugly part is that is still hard to find example with types for pytest and that does not help people wanting to use types.

Maybe the same question should be applied to official documentation? My take is to go fully typed.

In the end, why we should teach poorly examples to others when most of us we already know that good ones look different -- we are not giving a chance to the ones learning to do it right from the first day?

[Pierre-Sassoulas]

I think more example with typing provided would permit the "advanced" python users to have an easier time to add typing to the detriment of the python "beginners" who would have more to learn before understanding the examples. For example the capsys fixture, how do you type this ? If all the examples with capsys are capsys: CaptureFixture then it's going to be really simple to know that. It really depends on the aim of the presentation. Is it to teach pytest to beginner without drowning them in things they don't know yet, or teach pytest and typing in pytest at the same time ?

[RonnyPfannschmidt]

if there was a easy way to show/hide them and switch that, id be all for it - it downs beginners at the start but its a critical tool later on

for now my personal subjective perception is that we have to err on the side of avoiding overwhelm, thus no types in general

it may help to have a extra reference page with exampels or links to code that uses it