Improve Yaks's testing story

[plexus]

There should be a clear and well documented way to test your Yaks app.

I see two main types of tests: mapper tests and "API/integration" tests.

In mapper tests you shove an object in a mapper, and then assert stuff on the resulting resource. Here is an example.

All those literal objects can get a bit unwieldy though, so for Ticketsolve we write our tests a bit more compact, like this. Those matchers you see (match_attributes, match_links, match_forms) are defined here. I can imagine these becoming part of yaks-rspec gem, although they are quite ugly at the moment. Would definitely need some cleanup or maybe even a rewrite to be released as a gem. I'm also not sure if they follow latest best practices for writing RSpec matchers, this has evolved a bit over the versions I believe.

Secondly, integration tests. They consist of "browsing" your API. Since it's hypermedia we can follow links, submit forms, etc. Currently I think the best option for that is using the HTML output format combined with Capybara. I've been adding "rel" attributes in the relevant places so you should be able to

find(:xpath, '//a[@rel="next"]).click

within(:xpath, "//form[@rel='...']") do
  fill_in 'Name', :with => 'Jimmy'
end

Alternatively you could have a Capybara-like DSL, but that follows more closely the vocabulary and concepts of hypermedia. You would just give it the rack app of your API, and would be able to "browse" like with Capybara. I would use custom output format for this that simply does a Marshal.dump (or equivalent, this could actually just be a resource.pp to dump, and eval to load) of the Yaks::Resource, then unmarshal that in the test layer and work directly with the Resource.

I'll be exploring some of these options in Yakscart