Method Interceptors page: an IMethodInterceptor receives dependency-constrained methods too

Page

src/main/asciidoc/docs/method_interceptors.adoc — "Method Interceptors"

Problem

The page describes a two-group model that TestNG has not implemented for the whole of the 6.x and 7.x line:

Once TestNG has calculated in what order the test methods will be invoked, these methods are split in two groups:

• Methods run sequentially. These are all the test methods that have dependencies or dependents. [...]
• Methods run in no particular order. [...]

In order to give you more control on the methods that belong to the second category, TestNG provides org.testng.IMethodInterceptor

The list of methods passed in parameters are all the methods that can be run in any order.

An IMethodInterceptor is in fact handed every test method of its <test>, the ones taking part in a dependsOnMethods or dependsOnGroups relation included.

This is the documentation half of testng-team/testng#1263, which reported the same claim in the IMethodInterceptor javadoc.

Why the code is not going to change

TestRunner builds the scheduling graph from what the interceptors return — deliberately, so that an interceptor removing methods cannot make the graph wait forever for a method that will never be invoked (the parallel methods lock-up fix). A method withheld from the interceptor would therefore be a method no implementation could ever drop.

Restoring the documented contract would also take from every filtering interceptor the ability to exclude a dependency-constrained test, silently running tests their author believes excluded, with no replacement API.

So the wording is what is wrong, not the behaviour.

What the javadoc now says

testng-team/testng has corrected IMethodInterceptor and ITestNGMethod to describe the actual contract:

• every test method of the <test> is passed, dependency-constrained ones included, and why;
• ITestNGMethod.upstreamDependencies() and downstreamDependencies() tell a constrained method from a free one, and are now populated before the interceptors run so an implementation can act on them;
• where a constrained method runs stays bounded by the graph, so reordering it cannot move it ahead of what it depends upon;
• dropping a method that another retained method depends upon ends the run with a TestNGException naming the dependency.

Suggested change

Replace the two-group framing with the above, and point readers at upstreamDependencies() / downstreamDependencies() for the distinction the old text promised TestNG would make for them.

Edit src/main/asciidoc/docs/method_interceptors.adoc; start by comparing the current two-group explanation with the actual IMethodInterceptor contract described in the issue. Replace that framing with the dependency-aware behavior and point to upstreamDependencies() and downstreamDependencies(); done when the page no longer claims only unconstrained methods are passed.