Nick Gauthier's Blog

Chris Strom and I have finished our e-book on Backbone JS: "Recipes with Backbone". It is now available at http://recipeswithbackbone.com for $24.

The book is targeted at the intermediate to advanced level backbone developer, but that's not to say beginners won't get anything out of it. To quote the site:

• This is not the definitive guide to Backbone.js.
• This is not an introduction to Backbone.js.
• This is the book you read after you read the tutorial.
• This is the book that teaches you to kick ass with the hottest Javascript MVC framework around.
• This is Recipes with Backbone
• Preview the table of contents

So if you want to learn more about backbone js, buy it!

Gregory Moeck's awesome post Stubbing is Not Enough got my brain back on the subject of mocking. Readers of this blog may note that I had quite a rant against mocking almost a year ago and Gregory posted a response. I think the result of that post and the discussion that ensued was not that mocking and/or stubbing were bad practices, but that when they are applied inappropriately they can quickly deteriorate the tests and the design of an application.

After reading Gregory's article, I wanted to revisit the state of mocking in Rails applications. One of the things I noticed in his article was that he was addressing some ruby classes and their interactions. He enforced the OO concepts of message passing and how mocks are better than stubs at testing very OO code. While I really like his solution, something was nagging at me: how can I do this in Rails?

For example, here is the stock rails scaffold controller and functional test:

class PostsController < ApplicationController
  # GET /posts
  # GET /posts.json
  def index
    @posts = Post.all

    respond_to do |format|
      format.html # index.html.erb
      format.json { render :json => @posts }
    end
  end
end

class PostsControllerTest < ActionController::TestCase
  setup do
    @post = posts(:one)
  end

  test "should get index" do
    get :index
    assert_response :success
    assert_not_nil assigns(:posts)
  end
end

What can I mock? In Gregory Moeck's example, the ticket reservation object was passed in to the ticket machine interface (dependency injection) so we could easily mock the ticket reservation role and assert that the ticket machine interface interacted with it properly. He also intentionally doesn't touch the @current_display variable because it is internal to the system.

In our Rails controller and functional test, we can observe the following:

1. The actions taken by the controller are internal, not based on roles it should interact with
2. The functional test is testing internal state (assigns) and not messages passed by the controller

My gut at this point says I'm on an integration boundary between the user and my internal system. So that means I would have an integration test on the controller. But still, the signature of a rails controller to call activerecord and render doesn't seem to lend itself to encapsulation and mocking.

At this point I attempted to write what I thought was a change to the way controllers work using dependency injection and object composition, but I failed at it. So I'm leaving this post with some open questions:

1. What is the proper way to test rails requests with mocking?
2. What is the proper way to do an integration test, and how deep should it go (i.e. beyond the point that you have covered with unit tests)?
3. Are there other web frameworks out there with great encapsulation as a best-practice?

Super extra bonus points if you post links to open source projects that have a test suite that actually do these things well. Thanks.

Chris Strom and I have released the alpha of Recipes with Backbone. It's an e-book containing intermediate to advanced design patterns and best practices for Backbone.js. Grab it now for 50% off the list price. You'll get future versions of the book for free when you buy the alpha.

http://recipeswithbackbone.com

Thanks!

Ah yes, the Rails Controller, a source of much contention among Rails developers. So many different ways to manage control flow, load objects, respond in standard and erroneous ways. My opinion up until recently was "I'll just put a bunch of conditionals in there for different situations."

Recently, I've been working more on API endpoints and so responding with nice error messages has been more of a priority. I started using Exceptions more throughout my code thanks to Avdi Grimm, and I recently wrote and action that I'm particularly proud of. Check it out:

# This controller's job is to exchange twitter credentials for Shortmail credentials
class TwitterReverseAuthController < ApplicationController
  # First, let's make our own subclass of RuntimeError
  class Error < RuntimeError; end

  def api_key_exchange
    # Here are our required parameters. If any are missing we raise an error
    screen_name = params.fetch(:screen_name) { raise Error.new('screen_name required')  }
    token =       params.fetch(:oauth_token) { raise Error.new('oauth_token required')  }
    secret =      params.fetch(:oauth_secret){ raise Error.new('oauth_secret required') }

    # OK now let's authenticate that user. If we can't find a valid user, raise an error
    @user = User.by_screen_name(screen_name).where(
      :oauth_token => token,
      :oauth_secret => secret
    ).first or raise Error.new('user not found')

    # Now we'll build a device. I'm not catching an exception on create! here because
    # It should never fail. (I.e. a failure is actually a 500 because we don't expect it)
    @device = Device.find_or_create_by_token!(
      params.slice(:token, :description).merge(:user_id => @user.id)
    )

    render :json => { :api_key => @device.api_key }

  # Now I can simply catch any of my custom exceptions here
  rescue Error => e
    # And render their message back to the user
    render :json => { :error => e.message }, :status => :unprocessable_entity
  end
end

Here are the things I really like about this solution:

• The happy path is really clear because there's no if/else branching
• Errors are really obvious because I'm raising an exception (as opposed to "else render json that complains" which looks like a render which is not immediately apparent as a failure)
• It's super easy to handle the errors in the same way. Instead of repeating the json render with a different message all throughout the method (i.e. it's DRY)

How's this look to you? How do you organize controller control flow?

EventMachine's asynchronous and evented nature can be pretty tough to test. Here are some simple Test::Unit helpers I use along with a sample example:

def eventmachine(timeout = 1)
    Timeout::timeout(timeout) do
      EM.run do
        EM.epoll
        yield
      end
    end
  rescue Timeout::Error
    flunk 'Eventmachine was not stopped before the timeout expired'
  end

This is a helper that runs eventmachine in a timeout so that if it hangs the test suite flunks out after a second. Very handy.

def set_em_steps(*steps)
    @@_em_steps = *steps
  end

  def em_step_complete(step)
    @@_em_steps.delete(step)
    EM.stop if @@_em_steps.empty?
  end

This is a flow-control helper to make sure I complete all the steps I expected. Sometimes you run two chunks of EM code and then make assertions in the callbacks. Generally, you call EM.stop in your last callback, but what if they don't chain one after another? Then you have to call stop after both have finished. These two helpers just make it so that I can define my steps, then mark each as completed. They stop EM once all the steps are completed.

Example

Here is an example test from Shortmail.com's test suite for iPhone push notifications:

test 'send a push notification to the push daemon' do
  token = Factory.next :iphone_device_token
  message = 'hello world'
  # define two steps that must be completed before stopping
  set_em_steps :payload, :notification

  # run the following code, but time out after 1 second
  eventmachine do
    # MockServer is a fake iphone push server (pretending to be apple) 
    # it yields responses back to the instantiator
    Test::Helpers::PushD::MockServer.listen do |response|
      # Unpack the push
      id, exp, device, payload = PushD::Pusher.unpack(response)

      # make sure that the payload has the right into in it
      assert_equal token, device
      assert_equal message, JSON.parse(payload)['aps']['alert']

      # mark the payload step as complete, meaning we've received
      # and verified it
      em_step_complete :payload
    end
    PushD::WebServer.listen

    # This is another part of code under test.
    # This is how we send a push message
    PushNotifier.notify(token, :message => message) do |success|
      # When the push message is sent it runs the callback block with
      # a boolean and we ensure it's ok
      assert success
      # now make sure that this step is marked as finished
      em_step_complete :notification
    end
  end
end

Now, we can be sure our assertions are run, or it will time out because it won't stop.

How do you test eventmachine?

A nice thing about backbone is being able to bind a view render to new data. But sometimes you get new data, but it's not actually new, it's the same data that has not been updated. This will still cause the view to repaint because the event will fire.

To combat this, I've started putting signatures on my views.

In the initializer for the view:

this.signature = "";

Then in the render method, I do a reduction on the data that drives the view and compare signatures and decide to paint or not:

// Create a signature from the "Posts" that this view renders
var new_signature = _.reduce(posts, function(memo, post) {
  // Store the id and number of comments. This represents what a
  // "changed" post is for the view
  memo.push([post.get('id'), post.get('num_comments')].join(','));
  return memo;
}, []).join('|'); // joined with pipes for each post

// If the signature is the same, end the render
if (new_signature === this.signature) {
  this.signature = new_signature;
  return;
}
// Otherwise store the signature
this.signature = new_signature;
// Your view code down here

This is essentially caching with a custom cache key. Except instead of retrieving a cached value, we leave the dom as-is. This cuts down on repaint "flickering".

Backbone is a really interesting framework, and my favorite part so far is the following idea:

If you use a callback, you're Doing It Wrong

This has held true for me for my development with Backbone so far. When you make data calls to the server, you let the appropriate events notify interested parties when objects are changed or updated or refreshed.

However, with non-data operations, callbacks can be really useful. Today, I needed to animate an object, using jQuery's slideUp. I wanted the slideUp to go hand-in-hand with a deletion of an object. Because slideUp is asynchronous, and the deletion action is asynchronous, I needed a callback to synchronize them. The reason I couldn't do them simultaneously is that when an object is deleted, many view elements refresh themselves, and if the slideUp wasn't finish the dom refreshing would interrupt the slideUp and it looked gross.

So, I need a callback on slideUp to call remove. Here arose an SRP problem: the view should not concern itself with the removal of the model from the collection. One solution is for the view's removal method to take a callback and pass it along to slideUp. But I wanted something more flexible. Enter jQuery Deferred.

Deferred objects let you chain callbacks and return promises as objects. For you Rails readers, imagine AREL had a hot sister written in Javascript that was into AJAX.

So here is my view method that runs slideUp and returns a deferred object:

return $(this.el).slideUp(200).promise().done(
  _.bind(function() { this.remove(); }, this
);

Now when we archive and email, we want to remove the dom element by sliding, then we want to tell the email model to archive itself. Here is the archive method:

this.remove().then(this.model.archive);

Pretty straightforward. We call remove (the previous method) then we tell the model to archive itself. This method is bound to the click event on the archive button using Backbone's view event binding methods. When the model archives itself, Backbone events automatically fire, so other Views can listen for "change" and "remove" to update their elements.

EDIT: changed code reflecting Julian's comments.

I just had a tough time getting Rails 3 to play nice with Backbone JS, and it turned out to be a simple problem with a simple solution. Backbone was not sending the csrf authenticity token embedded in the page when it sent create/update/delete requests, and Rails was destroying the session when it detected the invalid request.

Here is all the javascript it took to get Backbone to include the token with all requests:

/* alias away the sync method */
Backbone._sync = Backbone.sync;

/* define a new sync method */
Backbone.sync = function(method, model, success, error) {
  /* only need a token for non-get requests */
  if (method == 'create' || method == 'update' || method == 'delete') {
    /* grab the token from the meta tag rails embeds */
    var auth_options = {};
    auth_options[$("meta[name='csrf-param']").attr('content')] =
                 $("meta[name='csrf-token']").attr('content');
    /* set it as a model attribute without triggering events */
    model.set(auth_options, {silent: true});
  }
  /* proxy the call to the old sync method */
  return Backbone._sync(method, model, success, error);
}

Note that this depends on the meta tags being present, which require you to call the helper "csrf_meta_tag" in your rails view for the page (put it in the head).

Goal: Make integration tests drier by adding a view abstraction layer

Ruby on Rails has a bunch of popular of test frameworks, such as:

• RSpec
• Cucumber
• Test::Unit
• Steak

But one common aspect to all of the frameworks, out of the box, is that they're very procedural. Cucumber is designed so that each scenario has a set of steps. There is a single, global, collection of steps. RSpec is global by nature, there are no test classes, just describe blocks.

There is no doubt in my mind that these frameworks have made testing easier by adding lots of common actions, and allowing you to define your own common actions.

However, there is one thing that I don't see much of in tests: Object-Oriented Patterns. Most of us use the Factory pattern through a variety of gems. Internally, many frameworks use the Visitor pattern to execute the tests. But that's all I've ever seen (disclaimer: I am young, and have much to learn).

Here are some pain points I've felt while writing integration tests in the past:

• Hard to reference objects throughout Cucumber scenarios. Often resulting in global variables used between steps
• Cumbersome to check the view for expected output, often resulting in lots of css selectors
• Brittleness introduced by coding html and css structure into test code that prevents refactoring the view

So, I recently had to write some integration tests from scratch, and I decided to do something different. I decided to implement the Bridge Pattern in my integration tests. I was confident enough in the solution that I decided to just use Test::Unit and Capybara to write my test code.

One of the major goals of this implementation is to make it easy to interact with the UI and objects within it. I think it's time I show some code.

Post Test for a simple blog site

# Given I am on the posts page
visit posts_path
# When I create a new post
click_link 'New Post'
View::Post.create(
  :title => 'View abstraction in integration tests',
  :body => 'We must go deeper'
)
# Then I should see a success message
assert_see 'Successfully created post.'
# When I visit the posts index
visit posts_path
# Then I should see one post
assert_equal 1, View::Post.all.size
# And it should have the correct title
assert_equal 'View abstraction in integration tests',
             View::Post.all.first.title
# And it should have the correct body
assert_equal 'We must go deeper', View::Post.all.first.body

Let's take a look at a few interesting things:

• I'm directly using Capybara's dsl to navigate
• When I create a post, I'm using a View module so that it won't use the ActiveRecord object
• When I create a post, I pass in a hash of the fields I'd like to fill in
• When I check to see if the post is created, I'm using methods on View::Post that return ruby objects, like an array, and that instances of View::Post have methods like "title" and "body"
• There are no css selectors or html, but I do have button test present

OK, hopefully that piqued your interest. Let's look at some of the implementation. First, let's check out the base View module and a barebones implementation of View::Post:

module View
  def self.body
    Nokogiri::HTML(Capybara.current_session.body)
  end

  class Abstract
    # Access capybara dsl in the view helper classes too
    include Capybara
    extend  Capybara

    def initialize(node)
      @id = node['id']
    end
    def self.all
      nodes.map{|node| new(node) }
    end
    private
    def id
      %{##{@id}}
    end
  end
  class Post < View::Abstract
    attr_reader :title
    attr_reader :body
    def initialize(node)
      super
      @title = node.css('.title').first.text.strip
      @body = node.css('.body').first.text.strip
    end

    private
    def self.nodes
      View.body.css('.post')
    end
  end
end

OK what's going on here? Let me step you through it:

• When I call View::Post.all, that calls View::Abstract.all, which iterates over View::Post.nodes and builds instances of View::Post
• View::Post.nodes runs Capybara's current page through Nokogiri, then selects all the HTML nodes with the class "post"
• When a View::Post is initialized, it uses Nokogiri to set attributes on itself, from the view. Like title and body
• View::Abstract always stores an object's dom id as @id so that it can be used internally, which we'll see next.

Now lets take a look at how View::Post.create works:

module View
  class Post
    def self.create(opts = Hash.new(''))
      fill_form opts
      click_button 'Create Post'
    end
    def self.fill_form(opts)
      fill_in 'Title', :with => opts[:title]
      fill_in 'Body', :with => opts[:body]
    end
  end
end

Here we show how the class method uses capybara to take care of filling in the form for us. Now, if we change how our forms are rendered, we can change them in one place. Nice and DRY.

Let's look at one of the biggest pain points for me in cucumber: deleting an object in a list of objects. Why is this a pain point? I usually have to write a custom step like "When I delete the Post 'My Post'", which will use dom_id to find the id of a Post object found in the DB with the title "My Post". I find this really roundabout, because you don't need to look in the database for an object to figure out its dom id. It's right there in the view. Any competent internet user would be able to click on the "Delete" button for the post called "My Post" if you showed them the page in a browser. Here is the test code:

# Given I made two blog posts
2.times do |i|
  visit posts_path
  click_link 'New Post'
  View::Post.create(
    :title => "Post #{i}",
    :body => "Body for #{i}"
  )
end
# When I go to the posts path
visit posts_path
# Then I should see two posts
assert_equal 2, View::Post.all.size
# When I delete Post 0
View::Post.find_by_title('Post 0').delete
# Then I should see one post
assert_equal 1, View::Post.all.size
# And I should not see Post 0
assert_nil View::Post.find_by_title('Post 0')
# And I should see Post 1
refute_nil View::Post.find_by_title('Post 1')

Notice specifically the line where the post is deleted. I grabbed the instance of View::Post corresponding to the title I wanted and called .delete on it. Then I thoroughly check that the correct post was removed. Here is the implementation:

module View
  class Post
    def delete
      within(id) { click_button 'Delete' }
    end
  end
end

Expecting more? In View::Abstract we defined the method "id" which returns the dom id of the object which was stored when we initialized it. I simply told capybara to click "Delete" inside that node's div. This was the "eureka moment" for me. Something that is frustrating and difficult in other styles of testing is just plain simple with this pattern.

There is a lot more than can be done here, and I'm just scratching the surface. If you'd like to try it out for yourself, I've created a Rails project with this environment setup on github: View Abstraction Demo. Here's how to use it:

git clone git://github.com/ngauthier/view-abstraction-demo.git
cd view-abstraction-demo
bundle
rake

Note: you must use ruby 1.9.2. Important files to look at are "test/test_helper.rb" and "test/integration/post_test.rb".

Stemming from a workflow discussion on twitter featuring @bryanl, @eee_c, @pjb3, @stevenhaddox, and @webandy, I decided to share my workflow. Originally, we were talking about Mac Apps (specifically the paid ones), but that turned into "how do you work". Here are my goals for a good workflow:

Goals

1. Easily navigate applications and contexts
2. Minimize distraction
3. Maximize focus
4. Get work done

Easily navigate applications and contexts

I need to be able to quickly get to certain applications in order to maximize productivity. I want to be able to swap to a browser, terminal, editor, or other application in under a second. The mouse won't cut it, I need keyboard shortcuts.

My solution here is Alt-Tab. One of the oldest and most basic ways of switching apps. Alt-Tab is very fast for me because 95% of the time I have 3 windows open on any given workspace (OS X read: spaces). This means that Alt-Tab goes back to the previous window, and Alt-Tab-Tab goes to the alternative window.

Minimize distraction

I layout my workspaces in a 2x2 layout. Here is what I put on each window:

• [1,1] Chrome holding "distracting" sites like gmail, twitter, campfire, pivotal, etc
• [1,2] one Vim, one Terminal, one Chrome with only development related websites open
• [2,1] passive applications. Usually Xvfb and Rhythmbox. I don't go here often
• [2,2] alternative dev context. Same as [1,2] but for a different project. This is only up occasionally. Sometimes I use it for transferring files to remote servers.

I spend 99% of my work day in [1,1] and [1,2].

I disable all notifications. Nothing pops up. Nothing makes noise. Nothing "pulses" in the taskbar. Nothing. My phone is on vibrate and no apps on it make notifications except calls and texts. No one ever needs your attention immediately in gmail or campfire or twitter or pivotal or basecamp. When I am at a solid stopping point in my real work (30m to 2h in between) I go check all my distraction tabs. If the server is really on fire, someone will call my phone.

Maximize focus

This is a combination of the previous two, plus I always maximize my windows so I'm only looking at one thing at a time. No distractions so nothing gets in my face while I'm working. Many people like putting up a terminal next to their editor, but they usually end up alt-tabbing anyways. I prefer larger windows so I can have more vim splits (usually 3x3 on each tab) and more terminal output.

Applications

This last section is in response to our twitter debate about paid mac apps. I'm on linux, so I have no access to any of those apps. Let's start with the apps I spend the most time in:

• Edit code: Vim
• Run tests, servers, and other commands: gnome-terminal
• Web browser: Google Chrome
• File browsing and remote FS management: nautilus w/ gvfs
• Administer databases: mysql or psql console

That is where I spend the majority of my day. There are very few alternatives to the above applications that aren't very similar. Everyone has a browser and a terminal. Editors is an entirely different can of worms, so I won't get into that here. Some people use GUIs for DBs, but I prefer the console. I learned SQL before I did web development, so it's more natural for me. And if it's too hard, I write a test :-).

There are many excellent command line applications at your fingertips that I use through my terminal. Apps like git, grep, find, screen, top, ps, kill, and thousands of others. Learning the command line root of the application is usually more productive than a gui that was built on top of the command line application. The only exception I've found is when I need something shown to me graphically, like a pdf. I like to avoid the mouse, so the terminal is my friend.

Here are a bunch of Mac Apps that a couple of people brought up during our twitter discussion:

• mailplane
• echofon
• divvy
• propane
• alfredapp

I think it's a nice small selection of apps that illustrate the differences in my workflow from many other developers. Mailplane, echofon, and propane are for Gmail, Twitter, and Campfire. I try to ignore those applications as much as possible. Ideally, I want to spend less time in those apps in order to get more done.

Divvy and Alfredapp are all about launching and organizing applications. I have three applications in three windows. Vim manages its own splits and tabs. In my terminal, screen or tabs works. In the browser, I use tabs. Everything is maximized to improve focus.

What it really boils down to, though, is that I don't do a lot of stuff during the work day. I write code. I avoid anything that is not essential to writing code. I want less applications and I like having my life "in the cloud" so I don't have to install a lot of stuff on a new computer. My knee jerk reaction to new applications is not "oooh shiny", it's "I don't need that". Another really nice thing about this workflow is that it's scalable. I've worked from 1024x768 to 2560x1600, and it always makes optimal use of screen real estate. When I swap to my netbook, I don't feel cramped, I just open more tabs.

Join the discussion

Please post comments about the applications you use that I haven't addressed. I'll try to reply to everyone about how I handle different scenarios. Most of the time, my response will be "I try to avoid that because I'm trying to write code here!"

GOAL: Provide a Ruby interface for running JSLint on javascript files using v8.

require 'jslintrb-v8'
puts JSLint.new.check("var x = 5")

Will return the string:

Error at line 1 character 1: Missing "use strict" statement.
   var x = 5
 Error at line 1 character 10: Missing semicolon.
   var x = 5

Also, all of jslint's configuration options are available in the constructor:

JSLint.new(:undef => false, :sub => true)

JSLintRB-v8 on Github
JSLintRB-v8 on Rdoc.info

The problem: You have an ActiveRecord model (or any object, really) and you want to output it to json, but you need some specific methods and maybe some processing of its attributes before you can call .to_json.

Let's pretend we have the following object:

class Widget
  attr_accessor :id
  attr_accessor :name
  attr_accessor :gadgets
end

class Gadget
  attr_accessor :id
  attr_accessor :name
end

And we want this json from a widget:

{
  id : 'widget-47',
  name: 'name of widget',
  children: [
    {
      id : 'gadget-63',
      name : 'name of gadget'
    }
  ]
}

Note that ID has the class name on the front, the name is passed through directly. Also, the sub-objects (Gadget) have their id processed.

First, let's make the Gadget presenter:

class GadgetPresenter
  attr_reader :id
  attr_reader :name
  def initialize(gadget)
    @id = %{gadget-#{gadget.id}}
    @name = gadget.name
  end
end

Rails provides Object extensions that give us a to_json method on every object. By default, this will call all of our attr_readers. So, all we have to do is provide attr_readers for the attributes we want in the json. Now, Gadget#to_json would give us:

{
  id: 'gadget-63',
  name: 'name of gadget'
}

Now the Widget presenter:

class WidgetPresenter
  attr_reader :id
  attr_reader :name
  attr_reader :children
  def initialize(widget)
    @id = %{widget-#{widget.id}}
    @name = widget.name
    @children = widget.gadgets.collect{|g| GadgetPresenter.new(g)}
  end
end

Pretty much the same, except for the children. This lets us call the associate "children" instead of "gadgets". And all we have to do is collect up a bunch of gadget presenters. When .to_json is called on the widget, it calls to_json on the attributes. Since children is an array, it collects .to_json from each entry in the array, which calls the GadgetPresenter's to_json.

I really like this implementation because it's really just an adapter, and it only concerns itself with the data. It is also external to the Widget and Gadget class, allowing for multiple types of presenters easily.


Here is a running example: (requires rails 3) https://gist.github.com/703747

These are instructions for setting up a very bare cucumber stack for testing a rich javascript application.

All code available here: https://github.com/ngauthier/cucumber-webapp-demo


The following stack is used:

• Cucumber
• Capybara
• Selenium
• WEBrick

First, we make our awesome javascript powered webapp:

<!DOCTYPE html>
<html>
  <head>
    <script type='text/javascript' src='jquery-1.4.3.min.js'></script>
    <script type='text/javascript'>
      $(function() {
        $('#special-link').click(function(event) {
          $('#results').html("This is totally awesome");
          event.preventDefault();
        });
      });
    </script>
  </head>
  <body>
    <h1>My Webapp</h1>
    <p>
    <a href='#' id='special-link'>Click on this link to make cool stuff happen</a>
    </p>
    <div id="results"></div>
  </body>
</html>

All we're doing here is showing some text when we click a link. But we're using jquery's events to do it.


Now here is our feature file:

Feature: My Awesome Link
  Scenario: Clicking the awesome link shows awesome text
    Given I am on the home page
    Then  I should see "My Webapp"
    And   I should see "Click on this link to make cool stuff happen"
    And   I should not see "This is totally awesome"
    When  I click "Click on this link to make cool stuff happen"
    Then  I should see "This is totally awesome"

And here are our simple step definitions:

Given /^I am on the home page$/ do
  visit 'index.html'
end

Then /^I should see "([^"]*)"$/ do |content|
  within('body') do
    assert page.has_content?(content)
  end
end

Then /^I should not see "([^"]*)"$/ do |content|
  within('body') do
    refute page.has_content?(content)
  end
end

When /^I click "([^"]*)"$/ do |link_text|
  click_link_or_button(link_text)
end

And here is the cucumber environment file where all the magic happens. See comments for description:

require 'rubygems'
require 'cucumber'
require 'capybara/cucumber'
require 'webrick'

# setup capybara on selenium
Capybara.default_driver = :selenium

# This maps to webrick below
Capybara.app_host = 'http://127.0.0.1:3000'
Capybara.default_selector = :css

# Extend Cucumber's World with minitest assertions
World(MiniTest::Assertions)

# Launch a webrick server in a thread
AfterConfiguration do
  server_thread = Thread.new do
    project_root = File.join(File.dirname(__FILE__), '..', '..')
    WEBrick::HTTPServer.new(
      :Port => 3000,
      # TODO use the real application directory
      # Using the prototype directory for now
      :DocumentRoot => File.join(project_root, 'public'),
      :Logger => WEBrick::Log.new(File.join(project_root, 'cucumber.log')),
      :AccessLog => StringIO.new # to nowhere
    ).start
  end
  # Kill the server when cucumber is done
  at_exit do
    server_thread.exit
  end
end

The idea here is to boot webrick in a thread to serve the public directory, then connect selenium up to it. Very simple and light.

All code available here: https://github.com/ngauthier/cucumber-webapp-demo

It's the canonical ruby metaprogramming example. You have this:

def large_image
  image_base + '-large.png'
end

def medium_image
  image_base + '-medium.png'
end

def small_image
  image_base + '-small.png'
end

And you do some dynamic programming to define the methods with similar content:

%w(large medium small).each do |size|
  class_eval %{
    def #{size}_image
      image_base + '-#{size}.png'
    end
  }
end

I have two problems with this pattern:

1) The dynamic code is far less readable and clear. It might even need a comment! The static code is very easy to read.

2) The dynamic code gives terrible stack traces

(eval):3:in `small_image': undefined local variable or method `image_base' for # (NameError)
  from test.rb:28

Versus the static stack trace:

test.rb:15:in `small_image': undefined local variable or method `image_base' for # (NameError)
  from test.rb:28

Here, test.rb:15 is the line inside "small_image" that calls "image_base".


The argument for metaprogramming is so that there is only one place to change the content. However this is easily accomplished with a helper. In fact I already had that helper in place, image_base. If you find yourself repeating the code *inside* the method, it's worth extracting into a helper.


Metaprogramming is for a dynamic system, not for enumerations. For example, Rails controllers use dynamic programming to allow you to define your own action methods. These methods are called dynamically by the router. This is a huge oversimplification, but the idea is that the Rails authors have no idea what method names could be used, so they can't type them all out. It's a fundamentally different problem.


If you find repetition in coding to be a difficult task, consider investing some time in learning a powerful editor with a regular expression matching and replace function.

So, please repeat yourself!

GET    /people => List people
POST   /people => Create person
PUT    /people => Replace the collection
DELETE /people => Delete the collection

GET    /people/:id => List attribute of a person
PUT    /people/:id => update the attributes of a person
POST   /people/:id => create a new collection under a person
DELETE /people/:id => Delete a person

In rails, we use

index:   GET    /people     => List people
create:  POST   /people     => Create person
show:    GET    /people/:id => List attribute of a person
update:  PUT    /people/:id => update the attributes of a person
destroy: DELETE /people/:id => Delete a person

Now we may also have:

index:   GET    /groups     => List groups
create:  POST   /groups     => Create group
show:    GET    /groups/:id => List attribute of a group
update:  PUT    /groups/:id => update the attributes of a group
destroy: DELETE /groups/:id => Delete a group

Consider a relationship of Many To Many between users and groups.

How do I express the following?

"Add user X to group Y"

First thought may be:

POST /groups/Y/users?user_id=X

But technically, this means "Create a user whose attributes are {user_id => X} under group Y". This is wrong in two ways, the first is that we don't want to create a user inside a group. The second is that the user attributes are wrong, it's {id => X}.

The correct request would be:

POST /groups_users?user_id=X&group_id=Y

This means "Create a new GroupUser linking node whose attributes are {user_id => X, group_id => Y}".


OK now how do I express the following?

"Put user X into a new group, whose attributes are {name => 'My Group'}"

This is *two* requests:

POST /groups?name="My Group" => returns ID Z
POST /groups_users?user_id=X&group_id=Z

However, we can actually combine the requests like this:

POST /users/X/groups?name="My Group"

In a situation where a Group Belongs To a User, this would create a group under the user.

You would get in trouble if Group Belongs To a User and Group Has and Belongs To Many Users. However, in that case, you should be using another name for one of the assets. For example, Group could belong to a Creator, and a User would have a created_groups association. So the routes would actually be different:

POST /users/X/created_groups?name="My Group"

Which would mean create a group, where User X is the creator of that group.


So, how do we handle this with Rails routing and controllers?

resources :groups do
  resources :users, :controller => 'GroupsUser', :only => [:index, :create, :destroy]
end
resources :users do
  resources :groups, :controller => 'UserGroups', :only => [:index, :create, :destroy]
end

Now, for user and group resources, we would use a traditional controller. For the GroupsUser and UserGroups controller, it would be a bit different.

UserGroups controller:

index: return all the groups this user is in
create: create a new group, and add this user to that group
destroy: remove this group from the user's list of groups

Note we don't have:

show: this is redundant with groups/show.
update: this would update the attributes on a membership. If it's just a join there are no attributes, however this may be useful if the join has attributes (for example, role)


The most interesting action here is create:

@user = User.find(params[:id])
@group = Group.new(params[:group])
Group.transaction do
  if @group.save
    if GroupUser.create(params[:group_user].merge{:user => @user, :group => @group})
      # success
    else
      # Could not add user to group
    end
  else
    # Could not create group
  end
end

Note that this controller is getting a bit dangerous because there are three logic paths. Generally, controllers will only have two logic paths: success and failure.

Note also that we are merging the params[:group_user] when creating it. This is because we may want to have attributes on the GroupUser. This would all have to be in the form for posting to this action.


Technically, we are creating a group under a user. While this makes perfect sense in a belongs_to relationship, it is a little mind-bending in a many-to-many situation where the relationship is reciprocal. So, I'll end with a question. Do you think that this "double action" is a violation of REST?