Fix incorrect javadoc of the Rule running order

[Jimmy-Shi]

In the javadoc of Rule and ClassRule, it says field rules are applied before method rules. Actually, method rules are applied before field rules.

[Jimmy-Shi]

Why this pull request is not getting merged for 4 months?

[marcphilipp]

Sorry for the delay. I just double-checked: Field rules are applied before method rules.

Example

public class Example {

    @Rule
    public TestWatcher methodWatcher() {
        return testWatcher("method");
    }

    @Rule
    public TestWatcher fieldWatcher = testWatcher("field");

    @Test
    public void test() {
        System.out.println("test");
    }

    private static TestWatcher testWatcher(final String prefix) {
        return new TestWatcher() {
            @Override
            protected void starting(Description description) {
                System.out.println(prefix + ": starting");
            }

            @Override
            protected void finished(Description description) {
                System.out.println(prefix + ": finished");
            }
        };
    }

}

This prints:

field: starting
method: starting
test
method: finished
field: finished

---

Do you have an example where methods are actually applied before fields?

[kcooney]

Actually, technically field rules are applied after method rules, but when a rule is applied the new rule runs "around" the existing rule chain.

[Jimmy-Shi]

@marcphilipp
I run your example and check my example again. The conclusion is:

• My Example shows that: Method rules are applied before field rules.
• You example shows that: Statements returned by field rules' apply methods are evaluated before statements returned by method rules' apply method.

My Example:

public class MethodOrfieldFirst {
    @Rule
    public TestRule fieldRule = new MyRule("FieldRule");

    @Rule
    public TestRule methodRule() {
        return new MyRule("MethodRule");
    }

    @Test
    public void test() {
        System.out.println("Running Test");
    }

    static class MyRule implements TestRule {

        private String name;

        MyRule(String name) {
            this.name = name;
        }

        @Override
        public Statement apply(Statement base, Description description) {
            System.out.println("applying: "+ name);
            return base;
        }
    }
}

This prints:

applying: MethodRule
applying: FieldRule
Running Test

[marcphilipp]

Thanks for your example. I now get what you meant. I think the original intention of the Javadoc was do describe the execution order of the Statements returned by rules. We should definitely clarify this.

How about:

Rules defined by fields will always be applied after Rules defined by methods, i.e. the Statements returned by the former will be executed around those returned by the latter.

Is that clearer? I'm not really satisfied with it and open to your suggestions.

[Jimmy-Shi]

Besides exchange the word method and field, I added below comment and update the pull request:

Since almost all of the in-box org.junit.rules.TestRule implementations are adding decorators to the passed in statement, the added decorators are evaluated in a reversed order that rules are applied.

Is it better?

[kcooney]

Which rules don't add decorators to the statement chain?

[Jimmy-Shi]

Some Rules added in the feature.

[kcooney]

(doing a pass at trying to close old issues)

Let's try to get this merged.

[kcooney]

All in-box rule implementations are adding decorators (in fact, all rules are decorators) so this is confusing. Can we fix it?

[Jimmy-Shi]

Sorry for late response, I was on a long holiday without computers.
How about removing the word almost

[kcooney]

How about "Since all {@link org.junit.rules.TestRule} implementations..." ?

[Jimmy-Shi]

Implementing with decorator pattern is not a requirement. We should not say "all" with out the limitation "in-box". What do you think.

[kcooney]

All rules are decorate the statement chain. Even if a given rule doesn't "look like" a decorator it is one

[Jimmy-Shi]

I could not get your point. I could not see any decorating in below implementation.

    static class MyRule implements TestRule {

        private String name;

        MyRule(String name) {
            this.name = name;
        }

        @Override
        public Statement apply(Statement base, Description description) {
            System.out.println("applying: "+ name);
            return base;
        }
    }

[kcooney]

No one should write rules like that. The implementation of the rule should occur when the returned statement is run.

A test rule is a factory for decorators for statements. On very rare occasions, that factory might returned the passed-in statement but even then it is clearly the decorator pattern.

If you still disagree, let's drop this sentence completely.

[Jimmy-Shi]

Yes, I disagree. Let's drop this sentence and take Marc Philipp's

Rules defined by fields will always be applied after Rules defined by methods, i.e. the Statements returned by the former will be executed around those returned by the latter.

[kcooney]

SGTM

[Jimmy-Shi]

Updated ^_^