Since no one wants to write the documentation, the simplest solution would be to let everyone write documentation, without noticing…
Normal documentation:
An Organisation is a firm or school that has an
address(required) and can have users as members.
Pragmatig documentation with examples:
Organisation:
- requires an address
organisation.address
- can have users as members
organisation.members << User
Test:
describe Organisation do
it "requires an address" do
@organisation.should_not be_valid?
@organisation.address = Address.new
@organisation.should be_valid
end
it "can have users as members" do
@organisation.should be_valid
@organisation.members << User.new
@organisation.should be_valid
end
end
#before :each omitted
With the help of some spec -f or agiledox magic, we can extract:
An Organisation:
- requires an address
- can have users as members
looks familliar ?
I prefer this kind of testing, since it does not generate so many 3-liners(2(do/end)+1) nor uses “it should” all the time, which makes it look more documentation-ish.
DISCLAIMER: This way of writing tests is not RSpec-pure in that it does not use ‘it should’ and has more than on assertion (should) per example.
Michael Grosser, the Blog 