Clearly document what `paths_to_mutate` does (or rename it)

[Otto-AA]

In several issues paths_to_mutate was used to select specific files that should be mutated (For instance, see #370). Given the name, this is a natural interpretation of what it does, and the docs do not clearly say otherwise. However, mutmut uses it as paths to the source code (/packages / modules; not sure about the terminology), and it needs to contain all the code necessary to run the test suite.

I would consider to rename it (e.g. to source_paths) and make paths_to_mutate a deprecated alias for it, showing a warning that suggests switching to source_paths.

Also, apparently people want to configure which files are mutated in the source code. Similar to the do_not_mutate config, we could have a only_mutate option, taking a list of paths that we mutate. Something similar is possible with the CLI positional arg (e.g. mutmut run "narwhals._arrow.series*"), but this only changes which mutants get tested, not which files are mutated on the disk.

[waltervos]

Interesting. I was considering making an issue reporting that overlap between paths_to_mutate and also_copy causes mutmut to not find a forced fail test. In our case it looked something like:

[tool.mutmut]
paths_to_mutate = [ "my_package/subfolder/" ]
also_copy = ["my_package/"]

I believe this generates the mutants, but then overwrites the mutants with code from the also_copy path(s).

Your suggestion to create a source_paths and a only_mutate setting would solve this issue for us, I believe. It would look like:

[tool.mutmut]
source_paths = [ "my_package/" ]
only_mutate = [ "my_package/subfolder/" ]

All this to say: +1 ;)

[Otto-AA]

@waltervos As a potential workaround for only_mutate, depending on your setup:

If you use the current main branch (not released as of writing) you could use following toml:

mutate_only_covered_lines=true
pytest_add_cli_args_test_selection = ["tests/test_for_module_a/"]

This should only mutate lines of code that are covered by tests in tests/test_for_module_a (and later on only use these tests for the mutation analysis). You could also use different test selectors, similar to how you do it on the CLI on the terminal. So if your tests resemble your source code structure, you can achieve somewhat similar to only_mutate.