Fixture docs - possible point of confusion

[JamEnergy]

Very minor gripe here, but I lost some time over it and I wanted to give feedback :)

https://docs.pytest.org/en/latest/fixture.html

I got very confused in this page.
TLDR: Variable naming in examples made it difficult for me to figure out how to adapt examples to my own use case

# content of conftest.p
import pytest
import smtplib

@pytest.fixture(scope="module")
def smtp():
    return smtplib.SMTP("smtp.gmail.com", 587, timeout=5)

# content of test_module.py

def test_ehlo(smtp):
    response, msg = smtp.ehlo()
    assert response == 250
    assert b"smtp.gmail.com" in msg
    assert 0  # for demo purposes

def test_noop(smtp):
    response, msg = smtp.noop()
    assert response == 250
    assert 0  # for demo purposes

If you don't know anything about the smtp module, example reads as if you have to call a method on "smtp" that matches your test name (minus test_).

When looking at an example, a key thing that helps is if you can quickly discover what is arbitrary, and what "has to match something else".

When writing examples, I try to make arbitrary names look arbitrary by munging them in some way or making them look frivolous.

Eg, is smtp here an arbitrary name, or is it something special? smtp is a general protocol, so it's strange to use it as a variable name. It's also almost a module name. Protocols don't tend to "do things",

I would do something like this.

# content of conftest.p
import pytest
import smtplib

@pytest.fixture(scope="module")
def my_fixture():
    return smtplib.SMTP("smtp.gmail.com", 587, timeout=5)

# content of test_module.py

def test_something(my_fixture):
    response, msg = my_fixture.ehlo()
    assert response == 250
    assert b"smtp.gmail.com" in msg
    assert 0  # for demo purposes

def test_anotherthing(my_fixture):
    response, msg = my_fixture.noop()
    assert response == 250
    assert 0  # for demo purposes

[pytestbot]

GitMate.io thinks possibly related issues are #1683 (Add "advanced fixtures" topic to docs), #2201 (Doc error in fixtures section), #2300 (Is dynamic updation of fixture scope possible ? ), #795 (Docs typo), and #698 (Wrong test outputs in fixture docs).

[nicoddemus]

Hi @JamEnergy,

Thanks for the feedback, we appreciate it.

I agree we could use another name for the fixture. How about smtp_connection instead of my_fixture though? I think it would convey more clearly what the fixture provides.

Perhaps you would like to contribute a PR with that change?