How do you start, and how do you know you’re finished? What do you test, and where? These questions can be answered hundreds of different ways, but here’s my way.

The first code I write: a feature

As a developer, rather than a designer, I’m always tempted to start with unit tests and work out towards a cucumber feature (“inside-out” testing). But that approach gets me into no end of trouble. I usually end up writing and testing stuff on the model that I don’t ultimately need. Plus once I’m down in the weeds coding, I lose track of the big picture.

So I like to do outside-in testing instead. I start each story I get from tracker with a cucumber feature that expresses how the PM will be able to accept it when I’m done. The feature helps me frame the problem properly, and focus on doing exactly what I need to make it work. Since I come back to it periodically while I’m coding, I keep focused on the higher-level goal. And finally – if I write it first, I can’t skip writing it once I’m done.

Before we get going…

There are certain types of tests I don’t write in this example (and in some cases, at all). Let’s get those out of the way so you don’t have to come up with a scathing comment at the bottom of the post.

• Model tests. In this example, my model doesn’t do anything other than default ActiveRecord behavior, so it doesn’t need any tests. Don’t test rails internals. Once my model has custom behavior, it will have specs, too.
• View tests. I have no tests that verify that my markup is what I expect. That’s because they’re a waste of time. Yes, even with complex views. Verify behavior with cucumber tests, unit-test Javascript with jasmine, and leave the rest to the humans. You’ll waste more developer time maintaining them than it would take humans to verify them. Verifiers are a whole lot cheaper than developers.
• Error case tests. In this example, there are no error cases. The model has no validations, and the table has no constraints. Once there are error cases, I generally put those in the model if I can, in the controller when I have to, and never in the cucumber tests. The latter is mostly a suite-speed consideration – cucumber tests run much more slowly than rspec. Cucumber’s great for for happy path tests; I leave the rest to rspec.

Let’s get going!

The first feature

Say I’m doing a library app and the first story is “User can enter a new book into the system.” Before I write any other code, I write this feature:

Feature: User manages books
  Scenario: User adds a new book
    Given I go to the new book page
    And I fill in "Name" with "War & Peace"
    And I fill in "Description" with "Long Russian novel"
    When I press "Create"
    Then I should be on the book list page
    And I should see "War & Peace"

Starting the fail-fix cycle

I run it using cucumber features, and it fails on the first line – Given I go to the new book page – because cucumber doesn’t know where the “new book page” is. So I add that to the cucumber paths helper.

    when /the new book page/
      new_book_path

Now when I run cucumber, it fails because it can’t find new_book_path. So I add that to routes.rb:

  map.resources :books, :only => [:new]

Now when I run cucumber, it complains that it can’t find the BooksController. That means it’s time to dive down to rspec controller tests.

My first spec experience

I create books_controller_spec.rb in spec/controllers, and add a test for the new method:

require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper.rb'))
describe BooksController do
  describe "#new" do
    it "should be successful" do
      get :new
      response.should be_success
    end
  end
end

When I run this spec, it complains that there is no BooksController. Fixed:

class BooksController < ApplicationController 
end

I re-run the spec and get "no action responded to new." So I add the new method.

class BooksController < ApplicationController
  def new
  end
end

Now the spec passes! Time to check back with cucumber.

Getting past the first line

I read through my cucumber feature again:

Feature: User manages books
  Scenario: User adds a new book
    Given I go to the new book page
    And I fill in "Name" with "War & Peace"
    And I fill in "Description" with "Long Russian novel"
    When I press "Create"
    Then I should be on the book list page
    And I should see "War & Peace"

Last time I ran it, it failed on the first line because it couldn't find the BooksController. This time, same location, but it says it can't find the view. So whiny! To placate it, I create an empty view called new.html.erb and run it again.

Now cucumber gets past line 1 (huzzah!!) and fails on line 2 (And I fill in "Name" with "War & Peace") with the message that it can't find a field called Name to fill in. So I add a standard rails form to the view.

<%- form_for @book do |f| -%>
    <%= f.label :name %>
    <%= f.text_field :name %>
    <%= f.label :description %>
    <%= f.text_area :description %>
    <%= f.submit "Create" %>
<%- end -%>

Uh oh. Cucumber is mad at me because there is no @book object. Back to rspec for me!

rspec: The Return

In my controller's new method, I need to create a book object that the form will use. I first add a test for that in the controller spec:

require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper.rb'))
describe BooksController do
  describe "#new" do
    before do
      get :new
    end
    it "should be successful" do
      response.should be_success
    end
    it "should create a book object" do
      assigns(:book).should_not be_nil
    end
  end
end

This fails the right way - it says assigns(:book) is nil. So then I add the creation of the book object to the controller.

class BooksController < ApplicationController
  def new
    @book = Book.new
  end
end

Now the spec fails, saying it can't find the Book class. It has a point - I haven't created the model yet. Fixed:

class Book < ActiveRecord::Base
end

Now it fails saying it can't find the books table. So I write a migration that creates that.

class CreateBooksTable < ActiveRecord::Migration
  def self.up
    create_table :books do |t|
      t.string :name
      t.text :description
    end
  end
  def self.down
    drop_table :books
  end
end

Once I do rake db:migrate and rake db:test:prepare, I re-run my controller spec....and it passes! Back to the cucumber feature!

Cucumber...again.

In our last episode, cucumber was visibly annoyed because there was no @book object for the form to operate on. I run it again to see if it's still sulking.

Yep. This time it tells me that it can't find books_path. form_for tries to submit to the create path by default, which I haven't added yet. I add it to the routes.

  map.resources :books, :only => [:new, :create]

This time, when I run cucumber, it gets through the first three lines (woo hoo!) and fails on the 4th, saying no action responded to create. Back to the rspec-cave, batman!

rspec: The Sequel to The Return

I add a controller spec for the create method.

  describe "#create" do
    it "should create a new book" do
      post :create, "book" => {"name" => "Jane Eyre", "description" => "Something Victorian"}
      assigns(:book).should_not be_nil
      assigns(:book).name.should == "Jane Eyre"
    end
  end

When I run it, I get the same message as in cucumber: no action responded to create. So I create the create:

class BooksController < ApplicationController
  def new
    @book = Book.new
  end
  def create
  end
end

Now when I re-run the spec, it fails saying that assigns(:book) is nil, which makes sense. I put in the guts of create to make that pass.

  def create
    @book = Book.new(params[:book])
    @book.save
  end

Now rspec passes! Back to cucumber.

So...cucumber. We meet again.

When I re-run the feature, it says I'm missing a template for create, which is correct. However, in this case, I don't want to make a template for create - I want to redirect to the book list page. So once again, I'm back with rspec.

rspec: Back so soon?

I add that expectation to the controller spec for create.

    it "should redirect to the book list page" do
      response.should redirect_to books_path
    end

It fails saying there's no redirect. So to make it pass, I add a redirect to the controller code.

  def create
    @book = Book.new(params[:book])
    if @book.save
      redirect_to books_path
    end
  end

Now my controller specs pass. Cucumber, I'm coming for you!

Oh, you again.

Last time, we got through the first 3 lines of the feature and failed on line 4 (When I press "Create"). When I run it this time, it gets through the same 3 lines and then fails in the same place again, saying that no action responded to index. I add index to the routes.

  map.resources :books, :only => [:new, :create, :index]

I re-run the feature and get the same error message. WTF, cucumber?! It turns out that rails' implementation of REST uses the same path helper for create and index, so the path helper for index already exists, even though the method does not. A little strange, I know. But we need an index method, so it's back to rspec.

rspec: For the first time, for the last time...

I write a spec for the index method.

  describe "#index" do
    it "should be successful" do
      get :index
      response.should be_success
    end
  end

I still get no action responded to index. So l add the method in BooksController, empty to start.

  def index
  end

Specs pass, back to cucumber!

How can I miss you if you won't go away?

Cucumber tells me there's no template for index. So I create an empty one, and re-run. This run, for the first time, I pass line 4 (yaaaaay) but then it fails on line 5 (Then I should be on the book list page) because it can't figure out what I mean by "the book list page." That goes in the cucumber path helper.

    when /the book list page/
      books_path

OMG five out of six steps pass! Now cucumber says it can't find "War & Peace" on the page, so let's make the index view list the existing books. Back to rspec...

Don't go away mad...just go away.

I add the following it block to the spec for index.

    it "should assign a list of existing books" do
      Book.create!(:name => "Endymion", :description => "weird")
      get :index
      assigns(:books).should_not be_nil
      assigns(:books).length.should == 1
    end

It fails because I'm not creating @books in the controller, so I fix that.

  def index
    @books = Book.all
  end

Now the specs pass - back to cucumber.

We really have to stop seeing each other like this.

Cucumber still says it can't find War & Peace, because I haven't added printing out the books to the index view. I'll fix that.

<%- @books.each do |book| -%>
    <strong><%= h book.name %></strong>
    <%= h book.description %>
<%- end -%>

Re-run cucumber and ... ta-da! The feature passes! I've done everything I need to call the story done. I have the minimum amount of code I need, because all the code I wrote was driven by the feature. Story: delivered!

You’re welcome to bring any sort of Ruby-related project! The theme for the evening is Javascript testing, following on this month’s monthly meetup. But I won’t make you write any Javascript if you don’t want to.

The peninsula has all kinds of neat hack events like SuperHappyDevHouse and various Hacker Dojo events. But I hate driving all the way down there just to hang out with hackers and get something done on a project. There are plenty of hackers in San Francisco. There might even be more of the type of hackers I want to hang out with.

So I’ve decided to host a monthly hack night, to be held on the Tuesday following the monthly SF Ruby meetup. My employer, Pivotal Labs, has graciously volunteered their space. Since tonight is the SF Ruby meetup, the next hack night is next Tuesday, April 27th, from 7-9:30 (ish).

RSVP now! See you next Tuesday.

Short version: it was a lot of work.

A lot of people have asked us about this, though, so it seemed worth distilling. The slides don’t convey everything I talked about. In the next few weeks I’d like to try putting together a blog post that does a better job. But for now, here they are.

Update (3/6/2010): MP3 audio is now available – thanks SCALE folks! Also, I’ve posted a PDF version of the slides for those of you without flash.

• Shoes – a simple way to create desktop applications in Ruby. Cross-platform, pure awesome. (code on github)
• Hackety Hack – built on Shoes, this is a toolkit specifically for learning how to program.
• Small Ruby – learn to program for the smaller set – think turtle drawing. Coming soon.
• PDF version of the slides (exactly the same as slides below)

LEARN ME

…is now open for registration. Last year Sarah Allen and I did three workshops for women and this year we’re going for four. So, if you’d like to learn Rails and can come BOTH Friday, February 26th in the evening AND Saturday, February 27th during the day, go sign up! There are only a few spots left.

And yep, still free.

We’re also seeking Rails developers (of any gender) to assist as TAs. Tell us about that here. Past TAs and teachers have found it quite rewarding. Plus you get a drink ticket for the afterparty.

And finally, some logistics: it’ll be in an office space in downtown San Francisco, near transit. Next week we’ll send out the exact address. We’ll have informal childcare and space for pumping or nursing – please tell us if you think you’ll be using those services when you register.

See you there!

I’ve been working on a side project that deals with Japanese text in Ruby. I installed rtranslate, a gem that gives me programmatic access to Google Translate. I wanted to try it out in irb.

>> require 'rtranslate'
=> true

So far so good.

>> Translate.t("

Here’s where I started to run into problems. I changed the input mode to Japanese and tried to enter はい (hai). All I got was beeping – irb wouldn’t let me enter any Japanese characters at all. I tried pasting from somewhere else – also a no go.

Long story short: by default, Ruby links against editline instead of GNU readline, and editline doesn’t support multi-byte characters. If I started irb with the –noreadline option, it worked fine, but then none of the arrow keys worked. Highly annoying.

I read five different articles [1] [2] [3] [4] [5] that fixed variants of the problem; none of the solutions worked fully for me. My machine is running Snow Leopard, and I had installed Ruby 1.8.7 from source following the Hivelogic directions. So if you’re in the same boat, here’s how you get multi-byte input working:

1. Install GNU readline.

cd ~/src
curl -O ftp://ftp.gnu.org/gnu/readline/readline-6.0.tar.gz
tar xzvf readline-6.0.tar.gz
cd readline-6.0
./configure --prefix=/usr/local
make
sudo make install


The –prefix in the configure line is crucial.

2. Recompile Ruby, pointing at the new readline. I still had the Ruby source directory in ~/src from when I compiled it the first time (this is a relatively new laptop). If you don’t, you can just download it again.

cd ~/src
curl -O ftp://ftp.ruby-lang.org/pub/ruby/1.8/ruby-1.8.7-p174.tar.gz
tar xzvf ruby-1.8.7-p174.tar.gz
cd ruby-1.8.7-p174
make clean
autoconf
./configure --enable-shared --with-readline-dir=/usr/local
make
sudo make install


3. My profile had gotten out of whack, so I had to add this line (again) to ~/.bash_profile:

export PATH=/usr/local/bin:/usr/local/sbin:/usr/local/mysql/bin:$PATH


Now I can enter multi-byte characters into irb, or copy them in from elsewhere. Now I can get on with what I was actually going to do.

>> require "rtranslate"
=> true
>> Translate.t("はい", "JAPANESE", "ENGLISH")
=> "Yes"


LEARN ME

This is a two-day event open to total programming novices, system administrators, and developers in other languages. In other words – everyone! All the details are on the meetup pages.

RSVP yes for both Friday and Saturday to reserve your spot.
Day 1, Friday 7/31: http://www.meetup.com/sfruby/calendar/10804417
Day 2, Saturday 8/1: http://www.meetup.com/sfruby/calendar/10804438

As before, men are welcome to register as the +1 of a woman doing the workshop. So guys, I know there’s a woman somewhere in your life who you’ve always thought would make a great programmer. Recruit her and you can come along too.

The workshop includes dinner on Friday, and breakfast and lunch on Saturday. Child care and private space for nursing and/or pumping are available. Partners are welcome to stay with the kids but that’s not required.

We are looking for experienced Rails developers of all genders to volunteer at the event. This time we have a separate volunteer coordinator so that things run more smoothly. Volunteering will be fun and educational, plus it’ll be a great networking opportunity. Stay tuned for info on how to get on the volunteer list.

The format will be similar to our first workshop: Friday night is a mixer and installfest. Attendees bring their laptops, and, with the help of our volunteers, install anything they’re missing to run Rails. Saturday is the workshop itself, starting with a short general presentation at 10am. Then we’ll break into smaller groups for the workshop itself. Lunch is included, and child care and nursing/pumping space is available.

If you came to the first workshop, you’re welcome to return for this one! Newcomers are likewise encouraged to register. When you register, you’ll be asked to answer some questions that will help us figure out how to allocate the class space we have.

The June event generated some great word-of-mouth, so I’m expecting this one to fill up quickly once registration is open. To find out when you can register, watch this space, check out the new site sfrubyworkshops.com, and join the low-traffic announcement-only mailing list (hosted by Google):

Lastly, we’re looking for sponsors to help us make this event fantastic. If your company or organization would like to assist, please email rubyworkshop at gmail dot com, which goes to both me and Sarah Allen.

UPDATE: The fine folks at Engine Yard are buying lunch. Thanks EY!!