Improve the explanation about custom assertions

[rocboronat]

Hello from South Korea! 🌏

#254 is a great PR, but I needed to read its code twice to understand what it was offering. The readme didn't explain the whole power of the new feature.

This PR will try to better explain it. Feel free to improve it as much as possible. I tried to focus on newbies instead of Espresso experts because that's what I am 🤗

By the way, if I misunderstood the API that was offered, feel free to shame on me 💩and commit on this PR without previous notice.

[alorma]

Cool addition @rocboronat!

Maybe we should add the examples @Sloy made
on: https://twitter.com/sloydev/status/1046741921979387905

What do you think?

[alorma]

common or custom Matcher?

[rocboronat]

Mmmmm you can also use a common withId or those given by Espresso... but you are right. I think I could just avoid the word and it will work better 💃

[rocboronat]

@alorma totally! Tomorrow I'll update the PR

[rocboronat]

@alorma done! I copied them and I think I improved them a bit. Now the examples show all the power of the feature. Let's check again! There's always space for the improvement 🚀🍌

[rocboronat]

After some time, I think it's good enough. At least for a while. We can always open a new PR to improve it even more. Thanks for the reviews!

[Sloy]

Hi! I'm off this week, but the error message is wrong :)
It's not an error message, it's the "expected" message. Because when the matcher fails Espresso will print "condition didn't match ".
It's not very intuitive, but it's how matchers work. They're called descriptions, not error messages.

[rocboronat]

@Sloy totally agree, but we are hiding the complexity and counterintuitive things of the Matchers with our approach, aren't we?
If we aren't, what do you think about changing assertion error message by assertion description message in the README?

[Sloy]

@rocboronat no, in this case we aren't. Because when assertion like this fails assertAny(R.id.button, "The button was not enabled") { .... } it will print an error like didn't match condition (The button was not enabled). And we know a double negation is an affirmation, so it doesn't make sense 😅

We don't have control of the message outside the parentheses. That's just how Espresso works (well, it's Hamcrest actually). It will append parts of matchers and assertions to create a full message. I don't think we should go against it.

If we aren't, what do you think about changing assertion error message by assertion description message in the README?

Yes, that's how it should be called in my opinion ^.^
Also, since we're using Kotlin there we could encourage people to use named parameters in the readme to avoid confusion, like assertAny(R.id.button, description = "is enabled") { ... }. It's common to use them with optional parameters, and add that little bit of extra context.

[rocboronat]

@Sloy thanks for the clarification! The thing is that description is broad enough that I didn't understand its meaning. I thought you were talking about the description of the View, not the assertion.

By the way, going to fix the comment inlined in the code.