User Guide: Need some clarification on alternatives to test filtering


(davidmichaelkarr) #1

This will be somewhat of an archeology exercise, but I want to clarify a section in the user guide that refers to obsolete features.

23.13.3, “Test filtering”, of the user guide starts with this paragraph (there’s one more sentence at the end of the paragraph):

Starting with Gradle 1.10, it is possible to include only specific tests, based on the test name pattern. Filtering is a different mechanism than test class inclusion / exclusion that will be described in the next few paragraphs (-Dtest.single, test.include and friends). The latter is based on files, e.g. the physical location of the test implementation class. File-level test selection does not support many interesting scenarios that are possible with test-level filtering.

I understand the test filtering concept, I’m just trying to understand exactly what the “other thing” is that this is referring to. It refers to this as “test class inclusion/exclusion”. I’m not certain what is meant by “will be described in the next few paragraphs”. The next few paragraphs describe the test filtering feature, which is probably not the “test class inclusion/exclusion” feature.

The next section after this, 23.13.4, “Single test execution via System Properties” mentions the “test.single” property, but the section also states that this feature has been superceded by “test filtering”. In the previous paragraph that I’m asking about, it also mentions “test.include” and “friends”. I searched the entire document for “test.include”, and only found “test.includes” in a description of list literals. I have no idea what “friends” refers to.

Can someone pull this together and help me clarify it?


(Peter Niederwieser) #2

“Test class inclusion/exclusion” refers to the use of the ‘Test#include’, ‘Test#exclude’, and related methods (‘Test#getIncludes’, ‘Test#setIncludes’, etc.).


(davidmichaelkarr) #3

I suppose the “friends” refers to the related methods, then.

The other confusion here is the statement of “that will be described in the next few paragraphs” followed immediately by the parenthetical reference to “test.include”, which I’ve already mentioned is not described anywhere in this document except for this parenthetical reference. The only thing described “in the next few paragraphs” is the supported “test filtering” capability.

If I had to guess, I would think that the reference to “the next few paragraphs” is spurious, and should be removed. I think I’ll also add a statement pointing out that the “test class inclusion/exclusion” feature is not described in detail in this document.