Write custom assertions docs kinda assume one already knows how to do it
adamcameron opened this issue · 3 comments
I'm reminded of this online joke:
Except in the case of these docs, all we get is the last image with a note "it should look like this".
It's all well and good showing what an in-built assertion looks like, but it's not immediately clear from that how one gets from there to be able to go $this->assertMyCustomRequirement($expected, $actual) in my test case. To be frank, It's not immediately obvious how the static inbuilt assertion methods end up being able to be called via $this-> in my test case.
I realise I could wade through the PHPUnit code and work it out, but - if I'm to be blunt - that code is wasn't exactly written with readability in mind (eg: what would phpmd or phpcs have to say about it? Or anyone who might have read Clean Code, etc). Now the codebase is what it is, that's fine. But having example code in the docs that pretty much requires fossicking around in the source code to work out what's going on is... less helpful than it could be, perhaps.
Let's say I am starting from an empty class file. What should I call it to be in-keeping with the PHPUnit idiom? Does it need to extend anything or implement any interface? Where should I put it in the file system (idiomatic recommendation or requirement)? What ought assertion method signatures be to follow the idiom? If I want to call inbuilt assertions from my method: how should I import them / call them? Do I have one assertion per file or can I have a library of them? What's the idiom there? How do I "register" my custom assertions with PHPUnit so they work seamlessly with my test cases (ie: $this->assertMyCustomRequirement)? These are the questions the docs should be answering. Not sure showing us a picture of a horse and say "like that" ;-)
I've looked online for other ppl solving the same problem, and their answers are never very well-realised. Basically "stick 'em in a trait" (ugh) or just sling them inline in one's test case, which is kinda what I'm hoping to avoid: assertions != tests, so don't really belong in a TestCase class, I think.
The PHPUnit documentation currently does not explain how to implement custom assertions.
https://phpunit-document-english.readthedocs.io/ is an outdated version of PHPUnit's documentation hosted on an unofficial account on ReadTheDocs that is not associated with the PHPUnit project.
You can find PHPUnit's official documentation here, as linked from its website.
Superseded by #310.
Ah right, interesting. I did not pay attn to the domain name in the link sorry, and am so used to landing on there from google I had not noticed there's a difference between that and the official docs.
Cheers for clarifying!