Update documentation to reference that a parametrized fixture might be set up more than once in its scope.

[jeffreyrack]

Right now, the fixture documentation states:

Extending the previous example, we can add a scope="module" parameter to the @pytest.fixture invocation to cause the decorated smtp_connection fixture function to only be invoked once per test module

While this statement is true in that example that is given, it leads the user to believe that fixtures are always only generated once for the scope that they are passed.

However, this doesn't match what @nicoddemus described in #3161 discussions:

One aspect of the fixture caching is that only a single instance of a fixture can exist at any given time; for example if test requires fixture foo with param=1, if another fixture requires foo with param=2 then it means that foo[1] will be destroyed and foo[2] will be created

While this behavior from pytest makes sense, I can't find any reference to this behavior in the fixture documentation, and it's surprising as the documentation led me to believe that a fixture would only be created once for the scope that it is being ran in.

Simple example that highlights the behavior I'm talking about:

import pytest

@pytest.fixture(params=[0,1], scope='session')
def fix1(request):
    print(f"Setting up fix1 with {request.param}")
    return request.param
    
@pytest.fixture(params=[2,3], scope='session')
def fix2(request):
    print(f"Setting up fix2 with {request.param}")
    return request.param

def test_a(fix1):
    assert True

def test_b(fix1, fix2):
    assert fix1 or fix2

And then when ran:

example.py::test_a[0] Setting up fix1 with 0
PASSED
example.py::test_b[0-2] Setting up fix2 with 2
PASSED
example.py::test_b[1-2] Setting up fix1 with 1
PASSED
example.py::test_a[1] PASSED
example.py::test_b[1-3] Setting up fix2 with 3
PASSED
example.py::test_b[0-3] Setting up fix1 with 0
PASSED

In this case, we see fix1 runs the setup for the param value 0 twice, which is not an obvious behavior from the documentation.

[nicoddemus]

Thanks for writing up the issue @jeffreyrack!