Add high-level docs page "how pytest works"?

[cdeil]

Is there a high-level docs page "how pytest works"?

What I'm looking for is a high-level explanation of what happens during a pytest run, things like that there are different phases (collection, running, reporting, others?) and at which points modules are imported (during test collection or running?), and what else pytest does.

I remember that when I was new to pytest (and also Python) a few years ago, I found the whole process or running pytest fascinating, but had no idea of what was going on really. And I had some misconceptions, e.g. I thought that TestSomething.setup only runs once per test session, and then when I found out that setup and tests are more isolated, I thought that probably pytest would start one Python interpreter per test, but then I found out that module-level variables in library or test code files are shared between tests, i.e. tests aren't fully isolated that way. So really it's been mostly a trial and error process of building up a mental model of what pytest does, and actually even after years of using it I'm not really sure that my understanding is correct or not, and I would find docs page that gives a good overview of "how pytest works" very interesting.

Does that page exist? If no, do you think it would be a useful addition to the pytest or not?
Maybe it could be a short intro / overview page that links to other existing docs pages?

[nicoddemus]

Hi @cdeil, thanks for writing.

I don't think anything like this currently exists, it might be a good addition to the docs. The topics should probably be separated in intermediate/advanced levels probably.

[bilderbuchi]

In the same vein, it would have been useful to me when learning pytest to have an overview about the different "magic" things going on, e.g. how conf.py is used without being imported in test files, or how some variable names, e.g. pytestmark are "special". I don't know if that is too tall an order, though. :D

[nicoddemus]

Perhaps a quick cheat-sheet would be a good addition.