Tests should be Documentation with Examples

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:

- requires an address
- can have users as members
  organisation.members << User


describe Organisation do
  it "requires an address" do
    @organisation.should_not be_valid?
    @organisation.address = Address.new
    @organisation.should be_valid

  it "can have users as members" do
    @organisation.should be_valid
    @organisation.members << User.new
    @organisation.should be_valid
#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.

One thought on “Tests should be Documentation with Examples

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s