Need to document how assertions should almost always be included with the call and try to avoid test section. #14
Description
The "tests" section would ideally never be written since the expect in the call should be all we ever need. However, there are many scenarios where this is the only way to test the outcome of a sequence of tests (ie. make sure that the new ID returned from a create user call is the same as the href returned from a search). However, this test section comes after all the calls are made. A pattern that showed up in the very first files written using the early framework was that these tests were hundreds of lines below the actual calls. It was difficult to keep track of what was being saved and what was later tested.
So, in the documentation for this framework, we should strongly discourage this pattern. The tests section is only to be used if the expect section of the calls can't implement the assertion desired.
Nothing to worry for this PR, except to maybe remove this test section from examples. In this case (I have not looked yet), you are probably asserting that these tests don't run, so you need them.
Originally posted by @dreich-nucleus in #13