Last week, for example, I wanted to speed up our builds by upgrading Bundler to 1.0.10 and RubyGems to 1.5.2. Because of the new partial caching of the dependency graph, the upgrades shaved two whole minutes off the build locally, and I wanted to get that on CI.

Trouble is, once I did the upgrades, I got this upon restarting CC.rb:

It turns out that older versions of Rails 2.3 aren’t compatible with the new version of RubyGems. To fix this, I added the following to CC.rb’s config/environment.rb, between the definition of ABSOLUTE_RAILS_ROOT and the Rails::Initializer block.

Both the 1.8 and 1.9 builds are now about 2 minutes faster which is awesome. Highly recommend the upgrades.

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,  nly => [: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,  nly => [: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,  nly => [: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| -%>
    <%= h book.name %>
    <%= 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!

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!

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!!

As we got into it we realized it was really, really ambitious. But I am profoundly thrilled to report that the SF Ruby community came together this weekend and made it happen.

O HAI NEW RAILS PPL

It was really, really incredible. More than 60 people spent their Friday evening installing Rails. Then they came back on Saturday and learned how to use it. A lot of them had never programmed before, but now they have Github accounts and a URL on Heroku. Watch out world!

I’ll be following up in this space with more lessons learned (and some further events), but for now, I want to share some feedback we got last night from one of the participants:

In addition to learning way more than I expected, I enjoyed the tone of the entire weekend. It was the only attitude-free, newbie-safe and mama-friendly tech event I have ever attended.

There were lots of things I could have organized better – projectors, class allocations, installation instructions – but I’m really happy that these folks got to experience a bit of the Ruby MINASWAN. In fact, I think something just got in my eye. *sniff*

So a million thanks to our sponsors, our volunteers, and the entire SF Ruby community for making this happen. Seriously. You ROCK.

So I’m super stoked about Heroku, who’s come to put the easy into Rails deployment. Register, install the gem, and deploying – with a real URL and everything – is as easy as git push heroku.

Sounds great! But it turns out that using the Heroku client on Windows is slightly problematic. With the standard Rails crowd, I wouldn’t worry, but it looks like about half the attendees will bring some flavor of Windows. So my choices were either make it work on Windows, or scrap the idea of, you know, putting apps on the internet.

So I fixed it. It turned out to be relatively straightforward. The shell method, which takes a command and returns its output, was doing this:

`cd '#{Dir.pwd}' && #{cmd}`

Windows thinks ' is a perfectly good character for directory names, so all calls to shell in Windows generated this error:

The filename, directory name, or volume label syntax is incorrect.

How helpful. In any case, it won’t be doing that anymore. My changes are up on github, and I’ve sent the official heroku client a pull request.

The client still has two spec failures on Windows (running within MsysGit’s Git Bash) that are unrelated to this change, and actually represent fairly significant cross-platform challenges.


'Heroku::Command::Auth sets ~/.heroku/credentials to be readable only by the user' FAILED
expected: 16832,
got: 16877 (using ==)
./spec/commands/auth_spec.rb:49:


The client fails to chmod your credentials file to user-only read, because File.chmod doesn’t do anything. As I’m sure you’re aware, there are significant differences between POSIX-style file permissions and Windows ACLs (access control lists).

So your credentials file, which has your Heroku username and password in plaintext, may be readable by other users. This generally isn’t as much of an issue on Windows as it is on *nix but it’s something to be aware of. You may want to adjust the ACLs by hand if you’re on a multi-user system.


NotImplementedError in 'Heroku::Command::App Git Integration before(:all)'
fork() function is unimplemented on this machine
./spec/commands/app_spec.rb:103:


Yep, as the error message suggests, Kernel::fork is not implemented in Windows Ruby. The Heroku client does not use fork – it’s in one of the gems, Session, which is used by Rush, which the Heroku test framework uses to create a sandbox git installation.

I haven’t looked too extensively at this one, but it might be possible to rewrite it to work on Windows. Rush does have some code specific to Windows, and there are alternate ways to sandbox the git install as well.

So given that neither of these failures affects the functioning of the client, I’m confident it’ll be usable on everyone’s laptop. I’m also super excited that one of the Heroku engineers, Pedro, has volunteered to help out with installation at the workshop!

We’re still looking for other volunteers – if you’re interested please email ruby workshop at gmail dot com.

So I’ll be offering a free workshop in San Francisco to reach out to women who want to learn Ruby and Rails. Sarah Allen and I are spearheading with the assistance of the San Francisco Ruby Meetup and Devchix and (your org here?).

The first one is June 12th and 13th – Friday night is a mixer and installfest, then Saturday is the workshop and hacking space. We’ll go from nothing to a fully-operational web application on the internet (mwa ha haaa!).

Registration will be open next week – check back for details then.

I’m posting this today, though, because RailsBridge, a grassroots effort to make the Rails community welcoming to everyone, is launching today. We’ll be releasing the slides, talking points, and logistics info for these workshops (oh yes, there will be more) under their umbrella.

Now, I’m a developer, not a trainer or an event planner, but…they’re all nails, right? And Github is a mighty fine hammer. Fork the kit and use it to your own ends. Maybe, if I’m feeling generous, I’ll merge you back in. But my goal is to have a continuously updated presentation that any Rails developer can pick up and use to run a similar event in their city.

Want to help? Maybe you actually know something about how to run a workshop like this? Get in touch and let’s talk.