attempted to clarify test and suite generation

[FND]

This is very much a light version of what I had planned originally: I was considering introducing a set of intermediate classes (GabbiTestDescriptor[Collection]?) to encapsulate and shuffle around some of the logic in both test_suite_from_yaml and TestMaker, but I'm no longer convinced it's worth the effort (for now anyway).

Nevertheless, these leftovers of that aborted effort seem to better describe what's going on, if only by grouping related aspects within the existing function.

What still irks me is that test_suite_from_yaml actually doesn't have anything to do with YAML: It's merely processing a dictionary that once happened to originate from a YAML file. However, I couldn't figure out how to get around that without introducing new terminology (see above).

[cdent]

Yeah, this seems like a good bit of tidying.

If you've seen my recent 2.0 related blog posting then you will see your thoughts "to encapsulate and shuffle around some of the logic" reflected there.

The lack of yaml in test_suite_from_yaml irks me too. It's probably safe to rename it as it is not really a part of the public api[1], which would bring things closer to something easier to abstract and indirect.

[1] The public api is effectively:

• the format of the tests
• the functionality of the things that will eventually be in ContentHandlers:
  • response handlers
  • replacers
  • data to request bodies
• the build_test method
• the arguments of and inputs to gabbi-run

If we do rename test_suite_from_yaml we might want to leave behind a shim to protect people who have done their own integrations like the hypothesis + gabbi thing linked from #94 or at least tell those people about the change.