Move @fails annotation into main test decorators about hypothesis

[Zac-HD]

See test.common.utils.fails_with; I'm also adding a similar decorator for "this test is for a deprecated thing" as part of #599.

[DRMacIver]

I think this issue was actually about making fails part of the public API, but I don't think this was ever a good idea and people should be using pytest's xfail or equivalent for it really (maybe we should too)

[Zac-HD]

Ah, right. I agree that it's a separate concern to the rest of the Hypothesis API, and users should look to their test runner of choice. Probably still useful for us to have a runner-agnostic fails_with though.

[DRMacIver]

Yup. It's perfectly sensible to have extra decorators like this internally and/or in the test helpers, just not part of the public API. Past-@DRMacIver had some odd ideas about API design which I've had to unlearn the hard way. :-)

[Zac-HD]

people should be using pytest's xfail or equivalent for it really (maybe we should too)

For posterity: @pytest.mark.xfail(raises=FooError) is semantically different to @fails_with(FooError) - the former indicates that raising FooError is expected behaviour due to an unfixed bug (and the test is reported as xfailed rather than passed), while the latter indicates that the test should raise FooError to pass.

Our internal decorator is instead more like a decorator form of with pytest.raises(FooError): ....