pitest icon indicating copy to clipboard operation
pitest copied to clipboard

Command Line API Documentation Improvements

Open chaosflaws opened this issue 1 year ago • 0 comments

When chasing down a bug in the pitest gradle plugin, I used the command line API to reproduce the problem. I would like to suggest some improvements to https://pitest.org/quickstart/commandline/ that hopefully makes life easier for future readers:

  • The --projectBase flag, used by at least the maven plugin, is currently undocumented.
  • The examples use absolute paths only. A note on how relative paths are interpreted would be helpful. (Yes, in the obvious way, but you can only confirm this after at least one successful run.)
  • --sourceDirs is currently undocumented. It can be deduced from the FAQ and the argument names, but it might be worth mentioning that the --sourceDirs argument should point to the folder containing java files, and that the test sources need not be included.
  • The bug in my setup had something to do with modules, so I tried prefixing --targetClasses and --targetTests with module names (com.example.module/com.example.api), which did not work. Might be worth a mention.
  • --tagetClasses and --targetTests refer to "glob syntax". It might just be me, but I expected com.* to match any immediate sub-packages, while something like com.** would match any subpackage of com. Also, --targetClasses * and --targetClasses ** both do not seem to work; they both result in no mutations being found. A clarification would be helpful.

After some digging, I found a reference to the issue-starter repository. It might be helpful for troubleshooting to include this on the API description.

chaosflaws avatar Dec 18 '23 14:12 chaosflaws