ExpectedException#expect() should take Matcher<? extends Throwable> as its argument

[UrsMetz]

Consider the following test:

...
public class WrongUsageOfExpectedExceptionApi {
    @Rule
    public ExpectedException thrown = ExpectedException.none();

    @Test
    public void wrongUsageOfExpectedExceptionApi() throws Exception {
        thrown.expect(RuntimeException.class);

        // thrown.expectMessage() should be used here
        // because an exception cannot start with a string
        thrown.expect(startsWith("some message"));
        throw new RuntimeException("some message");
    }
}
...

When you have something like this in a test it can be quite hard to figure out why the test fails.
At the moment ExpectedException#expect takes a Matcher<?> as its argument. By changing it to take only arguments of the type Matcher<? extends Throwable> the compiler could spot the mistake in the test given above.
I tried the code changes needed for the suggested change in the API with the current master (92a3f73) and all tests pass.
I understand that these changes break the API and non-generic Matchers won't work with the new signature of the method but is there any other reason not to have ExpectedException#expect only take arguments of the type Matcher<? extends Throwable>?
Apart from the exclusion of non-generic Matchers the only downside I see is that now you have to specify the generic type: That is you have to write for example

ExpectedException#expect(CoreMatchers.<Throwable>not(CoreMatchers.<Throwable>instanceOf(type)));

instead of

ExpectedException#expect(not(instanceOf(type)));

[dsaff]

In my experience, getting stricter with Matcher type parameters almost always results in unexpected negative consequences, similar to the much more verbose required syntax you mention.

What is the error message thrown in the above case?

[UrsMetz]

The error message is

java.lang.AssertionError: 
Expected: (an instance of java.lang.RuntimeException and a string starting with "some message")
     but: a string starting with "some message" was a java.lang.RuntimeException (<java.lang.RuntimeException: some message>)
...

which is correct and gives you a hint what the problem might be. But when you don't read the error message carefully you might wonder why the test isn't green.
I think the problem is that the hamcrest matcher's error message isn't that expressive because it should state explicitly that the matcher type doesn't match the type of the object it is asked to match. But on the other hand you could argue that with the stricter signature of ExpectedException#expect() the compiler would spot that mismatch of types.
Maybe a matcher wrapper for ExpectedException#expect() or something else ensuring the right type could make it easier to spot such wrong usage of the API while sticking to the current signature.
Nevertheless I still think that a stricter signature for ExpectedException#expect() should be considered: Only Matcher<? extends Throwable>s make sense for ExpectedException#expect because you can't match an exception with e.g. a Matcher<String> .

[dsaff]

I'll consider it, but I'm not sure it will be worth the type pain.

[kcooney]

@UrsMetz Note that we are considering removing our Hamcrest dependencies, so you might want to file this bug against the java-hamcrest project (https://github.com/hamcrest/hamcrest-junit).

[UrsMetz]

@kcooney I re-raised this issue at hamcrest-junit: hamcrest/hamcrest-junit#12.
I think this issue can now be closed?

[marcphilipp]

@UrsMetz Thanks!