Documentation request: types/shapes of options in `[tool.pytest.ini_options]`

[abravalheri]

What's the problem this feature will solve?

Currently the docs mention that you can use [tool.pytest.ini_options] for configuring pytest but they don't specify which "type"/"shape" of TOML object can be associated with each option. Instead, there is just a small example with 3 options.

That is a bit confusing, because users don't know what is the best way of writing the correct values to add to pyproject.toml.

One example of such confusion in particular is addopts.
From the example in the docs, I currently interpret that addopts should be a string "object".
However, after a quick search on GitHub, I can also see that there is several projects using an array of strings for that option (so I suppose that also works). However, that brings another question: can I use an array of strings for addopts, but written in a way that each string contain multiple "arguments" (e.g.: addopts = ["--verbose", "-p no:cov", '-m "not integration"'])?

Describe the solution you'd like

Ideally either https://docs.pytest.org/en/8.0.x/reference/customize.html#pyproject-toml or https://docs.pytest.org/en/8.0.x/reference/reference.html#configuration-options should tell the users what are all the possibilities for encoding an specific configuration in pyproject.toml in addition to pytest.ini/setup.cfg/tox.ini.

Considering the example above, it would be great if the docs explicitly tell that addopts accepts wither an string or array of strings and that in the case the user decides to write an array of strings, each string should be a single "argument".

Alternative Solutions

Additional context

[webknjaz]

FWIW per my observations pyproject.toml is not very well suited for such settings. So I always keep it in a dedicated config..

My understanding is that the types of settings are the same as in pytest.ini. addopts is a string, although you can multi-line it. I think it's related to the fact that there's an environment variable for it which would also be a string, naturally.
Things like filterwarnings, OTOH, are lists and it's obvious from it's description which starts by saying "Sets a list of filters and actions..."

[abravalheri]

Thank you very much @webknjaz.

Another related question you might know:
If it is meant to be a string how are things like line breaks and comments handled?

In setup.cfg/pytest.ini/tox.ini you can have things like:

[tool:pytest]
addopts =
    # show 10 slowest invocations:
    --durations=10

    # a bit of verbosity doesn't hurt:
    -v

(e.g. https://github.com/aio-libs/aiohttp/blob/v3.9.5/setup.cfg#L117-L136)

Does it mean that something like the following in pyproject.toml would be valid?

[tool.pytest.ini_options]
addopts = """
    # show 10 slowest invocations:
    --durations=10

    # a bit of verbosity doesn't hurt:
    -v
"""

[webknjaz]

Does it mean that something like the following in pyproject.toml would be valid?

[tool.pytest.ini_options]
addopts = """
    # show 10 slowest invocations:
    --durations=10

    # a bit of verbosity doesn't hurt:
    -v
"""

I haven't tried it but I'd expect that the comments are handled on the structured config parsing level. And in your example, they are within a string. That's one of the reasons I use a pytest.ini everywhere. I think it's the stdlib configparser that handles this (though, there might be some post-processing within pytest for corner cases since IIRC it's not filtering out inline comments by itself).

Though, I'm guessing here. I haven't checked how the TOML parsing behaves in any of my projects 🤷‍♂️

[RonnyPfannschmidt]

coments in strings wont wotk - the ini parser hanlders the comments, the toml version just puts the values in place

the plan is to eventually replace it with real toml data

[abravalheri]

Thank you very much for the clarifications, I will adopt the follow approach in ini2toml then:

tool.pytest.ini_options.addopts should be an string with comments stripped out (instead of converting to array of string and converting the comments to TOML comments).

Probably it is still a good idea to document types/shapes that are acceptable as TOML (the addopts: string vs addopts: array of string is just one example, but there are more that can cause doubt, like doctest_optionflags, norecursedirs, required_plugins ...).