Documentation for selecting which test to run it outdated

[cschreib]

Describe the bug
The documentation for selecting which test to run from the command line is outdated and incomplete.

Expected behavior
Here is what I noticed to be a mismatch; there may be more.

1. Combination of multiple arguments:

a* ~ab* abc             Matches all tests that start with 'a', except those that
                        start with 'ab', except 'abc', which is included

This suggests that "<filter1> <filter2>" behaves like an OR operation, given the comment "except 'abc', which is included". Trying this in practice shows that 'abc' is not actually included. This suggests the real behavior is actually closer to an AND operation. The example should be updated.

2. Commas:

A series of tags form an AND expression whereas a comma-separated sequence forms an OR expression.

This suggests that commas can be used for OR operations when filtering by tags, but in practice this also works when filtering by names, and in fact a comma can be put in between a name and a tag filter within the same "filter". It seems like it would be worth showing this as an example.

3. Not sure about that one, but I think the order of the filters is now irrelevant?

Reproduction steps
Read the docs.

Platform information:
N/A

Additional context
Add any other context about the problem here.

[horenmar]

Hmmm, that might not be outdated as much as just flat out wrong.

Not sure about that one, but I think the order of the filters is now irrelevant?

Actually I don't remember it being relevant in the last ~7 years. The closest the order comes to being relevant is that I think having negative matches at the end is more readable.

Commas:

Yes, commas are generally an OR, and it doesn't matter whether they are between tags, exact name, wildcarded name, or an AND-joined filter.

Combination of multiple arguments:

Technically this is not an OR, but rather successively applied filters. Some CLI utilities provide these, but I don't like them much in practice. The actual rules are that

• without positive filters, all non-hidden tests are included by default
• with positive filters, all tests that match them are included
• matching with any negative filter disqualifies the test from being included