Scenario and Step

If you’re not familiar with multiline tables in cucumber, take a look at the wiki entry. We were specifying a list of attributes on one of our models that we wanted to have access to in our step. First, here is an example scenario outline.

1
2
3
4
5
6
7

Scenario: Finding a specific dog
  Given an existing microchipped dog named "George"
  When I search for a dog with the following attributes:
    | name   | microchipped |
    | George | true         |
  Then I find "1" dog
  And that dog should be named "George"

Our step was taking the multiline table attributes and using them in an ActiveRecord find, like this.

1
2
3
4
5

/^I search for a dog with the following attributes:$/ do |table|
  table.hashes.each do |attributes|
    @dog = Dog.find(:first, :conditions => attributes)
  end
end

In our example we are looking for two attributes a string called “name” and a boolean called “microchipped”. However, this find will always fail, even if your ‘Given an existing microchipped dog named “George”‘ step explicitly sets up the correct object in the beginning of the test.

The Fix

We found that if we changed our scenario to look like this, everything worked fine.

1
2
3
4
5
6
7

Scenario: Finding a specific dog
  Given an existing microchipped dog named "George"
  When I search for a dog with the following attributes:
    | name   | microchipped |
    | George | 1            |
  Then I find "1" dog
  And that dog should be named "George"

See the change? We changed “true” for microchipped to “1″. Typically when you’re working with rails you can pass true in the conditions of an ActiveRecord find and Rails will convert that to the correct SQL string for you. However, because cucumber passes each argument in the multiline table rows as strings, Rails never has the chance to covert that true for you.

In the first, failing, example you end up with something like this for your SQL:

SELECT * FROM dogs WHERE name = "George" AND microchipped = "true" LIMIT 1;

In the second, passing, example you end up with something like this:

SELECT * FROM dogs WHERE name = "George" AND microchipped = "1" LIMIT 1;

Here are the slides from my presentation: 852k PDF

Prerequisites

I’m assuming you’ve got the following installed:

• ruby
• ruby gems 1.3.1
• Apple development tools
• git
• rails >= 2.3.2
• You’ve added github to your gem sources (gem sources -a http://gems.github.com)
  
  

RSpec & RSpec-Rails

First let’s grab the rspec¹ and rspec-rails² gems.

sudo gem install rspec

sudo gem install rspec-rails

Cucumber

Next we’ll install the cucumber³ gem

sudo gem install cucumber

Webrat

Webrat⁴ is used by cucumber to simulate a browser for your integration tests. Webrat will also install nokogiri⁵.

sudo gem install webrat

RCov

I thought RCov⁶ would get installed with RSpec, but it wasn’t for me. You might not need to do this, but just to make sure…

sudo gem install rcov

Autotest

Autotest⁷ comes from ZenTest⁸ and allows you to have a kick ass workflow where you are constantly running relevant tests and less-constantly automatically running your entire test suite.

sudo gem install ZenTest

Optionally, Thoughtbot’s Factory Girl

Factory girl⁹ is a really helpful fixture replacement (and more) gem to use in conjunction with cucumber, checkout their much better explanation

sudo gem install thoughtbot-factory_girl --source http://gems.github.com

Optionally, Carlos Brando’s Autotest Notification

While autotest normally runs in a terminal window, it can be setup to hook into applications like growl or snarl. The Autotest Notification⁹ gem helps make this setup a lot easier.

You will need growl installed and configured for this step the installation instructions on this gems github page are very easy to follow.

sudo gem install carlosbrando-autotest-notification --source=http://gems.github.com

Next you need to turn autotest notifications “on”

an-install

A Sample Rails App

Let’s create a sample rails app for the rest of this guide.

rails sample-app

Configuring Environment Variables

Autotest relies on some environment variables to run all of your features and specs correctly. If autotest “hangs” after you try to run it, or it just never seems to be watching your specs or features, this will most likely solve your problem.

Open the test.rb environment definition file in sample-app/config/environments/test.rb and add the following.

1
2

ENV['AUTOFEATURE'] = "true"
ENV['RSPEC'] = "true"

These lines will test autotest to run, and look for changes to, your specs (rather than test unit tests) and your cucumber features.

Update

If you don’t want to add these environment variables to every rails project you’ve got on your machine, you can also choose to set them as environment variables in your .bash_profile or .bashrc (or whatever shell you’re using) files.

export AUTOFEATURE=true
export RSPEC=true

Unpacking Gems

Next let’s freeze (unpack) some gems that we’ll be using in our app. I’ve run into problems trying to use the system gems with cucumber, rspec and webrat, especially when I have multiple versions of any of them installed. Unpacking them into my rails app solves this problem for me.

mkdir sample-app/vendor/gems
cd sample-app/vendor/gems
sudo gem unpack rails
sudo gem unpack rspec
sudo gem unpack rspec-rails
sudo gem unpack cucumber

Because webrat (and nokogiri) are native gems, that is, they are built locally on your machine based on its architecture, we won’t unpack those.

config.gem support
The current accepted practice, when using rails 2.3, and as suggested by the rspec guy(s) is to use rails’ config.gem functionality.

Open sample-app/config/environments/test.rb and add the following lines:

config.gem "rspec", :lib => false, :version => ">= 1.2.0" 
config.gem "rspec-rails", :lib => false, :version => ">= 1.2.0" 
config.gem "cucumber", :lib => false, :version => ">= 0.2.3"
config.gem "thoughtbot-factory_girl", :lib    => "factory_girl", :source => "http://gems.github.com"
config.gem "webrat", :lib => false, :version => ">= 0.4.3"
config.gem "nokogiri", :lib => false, :version => ">= 1.2.3"

Your version numbers may be different, but these are all current at the time of writing.

Boot Strapping RSpec and Cucumber

Before you can get very far with rspec or cucumber you need to run the bootstrapping scripts to give yourself the default files and directories.

# From inside your rails app sample-app/
script/generate rspec
script/generate cucumber

Factories
Depending on where you’re going to use your factories the most, you might want to save your file in either spec/ or features/. I chose the latter. Only complete this step if you plan to use the FactoryGirl gem.

touch sample-app/features/factories.rb

Getting Accurate RCov Data

By default RCov is setup to only use your specs when calculating code coverage. If you’re using Cucumber and RSpec, you’ll obviously want to include both types of tests to calculate your project’s true code coverage.

I picked up this rcov rake task from my co-worker Jay McGavren it does all of the heavy lifting for you, we’ll just need to make a couple of changes.

Drop this file into sample-app/lib/tasks/rcov.rake and use it by calling rake rcov:all from your terminal.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

require 'cucumber/rake/task' #I have to add this
require 'spec/rake/spectask'
 
namespace :rcov do
  Cucumber::Rake::Task.new(:cucumber) do |t|    
    t.rcov = true
    t.rcov_opts = %w{--rails --exclude osx\/objc,gems\/,spec\/,features\/ --aggregate coverage.data}
    t.rcov_opts << %[-o "coverage"]
  end
 
  Spec::Rake::SpecTask.new(:rspec) do |t|
    t.spec_opts = ['--options', "\"#{RAILS_ROOT}/spec/spec.opts\""]
    t.spec_files = FileList['spec/**/*_spec.rb']
    t.rcov = true
    t.rcov_opts = lambda do
      IO.readlines("#{RAILS_ROOT}/spec/rcov.opts").map {|l| l.chomp.split " "}.flatten
    end
  end
 
  desc "Run both specs and features to generate aggregated coverage"
  task :all do |t|
    rm "coverage.data" if File.exist?("coverage.data")
    Rake::Task["rcov:cucumber"].invoke
    Rake::Task["rcov:rspec"].invoke
  end
end

The important part here is on line 7, we want rcov to exclude our features directory. We obviously don’t need or want rcov telling us that our feature files are not “covered”. To solve this problem we’ve simply excluded the features directory from rcov’s processing.

We also need to slightly modify sample-app/spec/rcov.opts to get the full rspec + cucumber coverage data.

Your rcov.opts should look like this:

--exclude "spec/*,gems/*,features/*" 
--rails
--aggregate "coverage.data"

We again want to ignore our cucumber features and we also want to tell rcov to aggregate data in a file called coverage.data. This is used in the above rake task.

Write Some Specs and Features!

Act like you know what you’re doing and write some models, controllers whatever. Add some specs and features too.

Autotest Workflow

Open a terminal and make your way to your sample rails app and fire up autotest. You might see something like the following, depending on how many specs and features you’ve got.

$> autotest
loading autotest/cucumber_rails_rspec
opts 
...
 
Finished in 0.06276 seconds
 
3 examples, 0 failures
================================================================================
 
/System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/bin/ruby /Library/Ruby/Gems/1.8/gems/cucumber-0.2.3/bin/cucumber --format progress --format rerun --out /var/folders/Aq/Aqp06i3dFnqse+tQgQA+1++++TI/-Tmp-/autotest-cucumber.75956.0 features
.................
 
4 scenarios
17 passed steps
/System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/bin/ruby /Library/Ruby/Gems/1.8/gems/rspec-1.2.2/bin/spec --autospec spec/models/intern_spec.rb -O spec/spec.opts 
...
 
Finished in 0.062995 seconds
 
3 examples, 0 failures
================================================================================
 
/System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/bin/ruby /Library/Ruby/Gems/1.8/gems/cucumber-0.2.3/bin/cucumber --format progress --format rerun --out /var/folders/Aq/Aqp06i3dFnqse+tQgQA+1++++TI/-Tmp-/autotest-cucumber.75956.1 features
.................
 
4 scenarios
17 passed steps

The REALLY important stuff

1. make sure you’ve got “ENV['AUTOFEATURE'] = true” in your test.rb otherwise autotest won’t run your features automatically
2. make sure you’ve got “ENV['RSPEC'] = true” in your bash profile or else autotest won’t run your specs automatically
3. make sure you’ve got “–aggregate = ‘coverage.data’” in your spec/rcov.opts file if you’re going to use the above rake task and hope to get combined rcov coverage data between rspec and cucumber
4. make sure you’re excluding the features directory from rcov where required or else you’ll end up with misleading rcov data.

Gem Versions

Here’s a list of the current gems and their versions that I used in preparing this guide.

*** LOCAL GEMS ***
 
actionmailer (2.3.2, 1.3.6, 1.3.3)
actionpack (2.3.2, 1.13.6, 1.13.3)
actionwebservice (1.2.6, 1.2.3)
activerecord (2.3.2, 1.15.6, 1.15.3)
activeresource (2.3.2)
activesupport (2.3.2, 1.4.4, 1.4.2)
acts_as_ferret (0.4.1)
addressable (2.0.2)
builder (2.1.2)
capistrano (2.0.0)
carlosbrando-autotest-notification (1.9.1)
cgi_multipart_eof_fix (2.5.0, 2.2)
cucumber (0.2.3)
daemons (1.0.9, 1.0.7)
data_objects (0.9.11)
diff-lcs (1.1.2)
dnssd (0.6.0)
extlib (0.9.11)
fastthread (1.0.1, 1.0)
fcgi (0.8.7)
ferret (0.11.4)
gem_plugin (0.2.3, 0.2.2)
highline (1.2.9)
hpricot (0.6)
libxml-ruby (0.3.8.4)
mongrel (1.1.4, 1.0.1)
mysql (2.7)
needle (1.3.0)
net-sftp (1.1.0)
net-ssh (1.1.2)
nokogiri (1.2.3)
polyglot (0.2.5)
rack (0.9.1)
rails (2.3.2, 1.2.6, 1.2.3)
rake (0.8.4, 0.7.3)
rcov (0.8.1.2.0)
RedCloth (3.0.4)
rspec (1.2.2)
rspec-rails (1.2.2)
ruby-openid (1.1.4)
ruby-yadis (0.3.4)
rubynode (0.1.3)
sources (0.0.1)
sqlite3-ruby (1.2.1)
term-ansicolor (1.0.3)
termios (0.9.4)
textmate (0.9.2)
thor (0.9.9)
thoughtbot-factory_girl (1.2.0)
treetop (1.2.5)
webrat (0.4.3)
ZenTest (4.0.0)

El Fin

Hopefully this guide was useful or had that one little step that you needed to get everything working. I’m sure this will all be out of date in the coming weeks, but I’ll try to keep it as up-to-date as possible. If you see any errors, or can better explain some of the missing pieces, please post a comment. Thanks!

¹ http://github.com/dchelimsky/rspec/tree/master

² http://github.com/dchelimsky/rspec-rails/tree/master

³ http://github.com/aslakhellesoy/cucumber/tree/master

⁴ http://wiki.github.com/brynary/webrat

⁵ http://github.com/tenderlove/nokogiri/tree/master

⁶ http://rubyforge.org/projects/rcov/

⁷ http://www.zenspider.com/ZSS/Products/ZenTest/#rsn

⁸ http://www.zenspider.com/ZSS/Products/ZenTest/

⁹ http://github.com/thoughtbot/factory_girl/tree/master

¹⁰ http://github.com/carlosbrando/autotest-notification/tree/master

The FAIL Monster Is Your Worst Best Friend

When you first meet him you’re trying to figure out what this asshole is doing hanging out right after you really screwed up. You realize that he’s no good, but as time goes on, you start enjoying his company. He loves showing up because he knows there will be excuses aplenty.

Here are some situations when you might see him:

• You’ve messed up and can’t take responsibility
• The project is off track and it’s not at all your fault
• If only < outside agent > would have completed < task > on time
• You start using Fat Bastard’s circular logic to explain away your problems
• “I don’t have < resource > to do < what is right >
• You don’t write tests
  
  

Put the FAIL Monster on a Diet

Here is a quick guide to help you trim down your personal FAIL Monster:

1. Quit making so many goddamned excuses!
   
   

Stop making excuses for your lack of understanding, your irresponsibility, your lack of prospects and your shit attitude. Take the time to push yourself, learn a new skill, read a book, meet people, take a leadership role, achieve greatness and succeed.

You can make excuses for everything, the only thing they’re good for is feeding your own FAILURE.

What I Love

Project Boards - Nearly real-time visual feedback on the status of your project. Everyone on the team can assess your project at a glance and you can avoid long status meetings with middle management. Greatly increases accountability.

Stand-up Meetings - Quick, informative useful meetings that don’t waste people’s time. Social group pressure keeps people who like the sound of their own voice from talking for 30 minutes.

Daily Client Interaction - No need for ego-maniac project managers. Developers discuss issues with clients each day so that they can deliver the best software with the most value as quickly as possible. Challenges or roadblocks can be brought up almost immediately helping to prevent wasted time on either side of the equation.

User Stories - “Replacements for a conversation” as I always hear around the office. Replaces the need to confusing spec documents and misguided feature requests. These provide a way to ensure that neither the client’s money or developer’s time are being wasted.

Acceptance Criteria - It’s not easy getting quality acceptance criteria from your clients, but man is it worth it. Helps to make sure that what’s “done is done” and there are no disputes towards the end of the project about what is or is not completed.

Short Iterations - Allows the developer to focus on a set of the most important tasks for a short period of time. The client receives frequent demonstrations of the completed work and changes in course can be made very quickly. What was important 4 months ago during the original planning session might not be important this week.

Waterfall Development: DO NOT WANT!

Looking back on my last job where waterfall development was the norm, I can’t imagine how I got anything done. When I really think about it, I wonder how much software I wrote that was “right” the first time around.

Just as a quick list, here are some of the things I’ve grown to hate:

• Project manager dominated client interaction
• Long useless meetings
• Finger pointing and blaming and lack of accountability
• Waiting a few weeks to find out that your implementation is incorrect
• No way to tell what was actually “done”
• Wasteful spec documents
  
  

This Won’t Work For My Business

There are probably a lot of development shops that are humming along using long standing processes based on a waterfall model. A lot of people probably think that they don’t need to change because “if it ain’t broke, don’t fix it”. If you’re not doing agile your shit is broke!

A lot of managers probably think that this system won’t work with their employees. I can see this being the case if any of the following apply:

• You don’t trust your employees
• Your employees are morons (or you think they are)
• You think you need to operate like the status quo
• You can’t give up your control on the process
• Your clients suck
  
  

Agile Works at Integrum

Derek Neighbors has taken the time to produce a couple of videos outlining how agile is put into action at Integrum:

• Integrum Agile Workspace
• Integrum Project Board
  
  

Whatever the reason, agile works, like actually works, at Integrum. Is it the culture? The people? The atmosphere? The expectations? The clients? I can’t quite put my finger on it, but I can guarantee it’s not coincidental.

Below we have an example model, spec and shared example group. Our Dog model has its own set of functionality, but as a mammal it should still have some aspects of being a mammal. We’ve got some specs in a shared example group that we use for testing all of our mammal models to make sure things don’t get too out of whack in the universe.

Our Example Model

1
2
3
4
5
6
7
8
9
10
11
12
13

class Dog
 
  attr_accessor :name, :mammal
 
  def initialize
    self.mammal = true
  end
 
  def greet
    "Hi, I'm #{self.name}, woof woof!"
  end
 
end

Our Example Spec

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

describe Dog do
 
  before(:each) do
    @animal = Dog.new
    @animal.name = "Bruno"
  end
 
  it_should_behave_like "a mammal"
 
  describe "Greet" do
    it "should respond with its name and a greeting" do
      @animal.greet.should == "Hi, I'm Bruno, woof woof!"
    end
  end
 
end

Our Shared Spec

1
2
3
4
5

describe "a mammal", :shared => true do
  it "should really be a mammal" do
    @animal.mammal.should be_true
  end
end

A Typical before(:each)

Typically, when you’ve got a describe block, you might use before(:each) to setup some scenario that is used for each spec in that describe block, pretty normal RSpec stuff. We’re using it above in our example spec to create a new Dog object and set that dog’s name.

Using before(:each) in a shared spec

What if you wanted to use a before(:each) in your shared spec? Expanding on our example above we can do something like this.

1
2
3
4
5
6
7
8

describe "a mammal", :shared => true do
  before(:each) do
    @animal.stub!(:has_body_hair?).and_return(true)
  end
  it "should really be a mammal" do
    @animal.mammal.should be_true
  end
end

Based on typical RSpec behavior, one would think that the stubbing of the has_by_hair? method on the instance of an animal, would only apply to the specs inside of the describe block of the shared example group. However, by specifying in the Dog spec that a dog “should behave like” a mammal, and thus using the shared spec, that stub will apply to all subsequent “it should” blocks in your model spec.

What if, for example, we had the following in our Dog spec.

  describe "Mutate into Lizard Dog" do
   # dog.mutate will remove body hair and make the dog cold blooded
    it "should mutate into a new species" do
      @animal.mutate
      @animal.has_body_hair?.should be_false
    end
  end

If we include this in our Dog spec, below the inclusion of the shared example spec, our test will fail. We’ve already stubbed out the has_body_hair? method as part of our shared example group, when we call it down here in this completely separate describe block, RSpec is just using the stub we setup previously.

It might be a design problem if…

Now while I’m considering this a gotcha, it may be that this is expected behavior, I couldn’t find anything specifically when researching this “bug” originally. It is also possible that stubbing behavior in shared example groups is frowned upon, and I’m just “doing it wrong”.

Ultimately, I tried using patterns that made sense to me and seemed to be in line with how RSpec works in general. A stubbed method inside the before(:each) of a describe block is usually only applicable to the specs and nested describes contained within. When I realized that this is not the case with shared example groups, it seemed like a gotcha.

1. SSH Into your GoDaddy VPS
2. Copy the file located at /var/qmail/control/smtproutes to /var/qmail/control/smtproutes.old
3. Open the file located at /var/qmail/control/smtproutes
4. Delete its contents

I believe this will only work if you’re not using GoDaddy to host any of your e-mail and you only want your VPS and PLESK (running Qmail) to be responsible for hosting your e-mail.

More information and the original fix can be found here: http://www.datapencil.com/horde.htm

How to Earn a Gold Card

When I was in elementary school they had an ongoing school-wide program where students could earn “Gold Cards” and be recognized in the monthly assemblies. To earn a Gold Card, one had to be doing something benefiting others, without being asked. It could be something as simple as going out of your way to pickup some trash.

To be sure, a lot of students went around doing very insignificant, but still beneficial, activities all day in hopes of being seen by a teacher. The real takeaway however was the idea that the best type of deed is done where no one is watching. This is a difficult concept for a 4th grader, but the life lesson is outstanding.

Focus on the People

We talk a lot at Integrum about our process, our engineering principles, our goals, plans and expectations. But for every project board, velocity graph, client stand-up and piece of acceptance criteria, there is an underlying foundation of high quality people working together to achieve a common goal. Finding trustworthy, forgiving, understanding, motivating, helpful, challenging and comforting people to work with removes so many of the problems that these project management tools aim to solve.

When people live their lives being accountable to themselves and those around them, when they strive to do what’s right, even when it’s hard, and when they go above and beyond without the expectation of being praised, they can achieve great things.

As a relative newcomer to Ruby, I’m still in the process of learning to identify code smells, poor design and needless complexity. I’m sold on the “readable code is better” idea so I try to keep that in mind as I’m implementing some piece of functionality. Over at Integrum, where I work, we pair on everything each day, save for the occasional sick day. Today I was working alone and was reviewing some code that my pair and I had wrote about a week earlier. It was complex, and I feel that we made a compromise with the idea that the “ugly” working code was good enough for what we needed at the time, but it was ugly enough that I remembered to revisit it.

Flog Builds Confidence

When I really started looking at the code my intuition told me that it needed to be re-factored. I knew that it could be improved, but I suppose I’ve been in the pair mindset so heavily since I’ve been here that I did not immediately jump in and fix things. However, when I ran Flog and saw the comparatively high scores for two complex methods I had been investigating, I had that supportive “yea I agree” feeling that I usually get from pairing. Flog helped push me over the threshold, from “maybe I should change this” to “this should be changed”.

This isn’t to say that I wouldn’t have changed it without Flog, but it gave me that extra confidence in knowing that I was on the right track. The direct benefit was that the code is now more readable and easier to test. Indirectly I’ve added another point to my mental Ruby experience score and will be more inclined to follow my intuition in the future.

Packages Needed on Ubuntu

I’ve tried the following on Ubuntu Intrepid Ibex 8.10 but I would imagine that it works on other recent versions as well.

First let’s search for available texlive related packages

$> apt-cache search ^texlive
texlive - TeX Live: A decent selection of the TeX Live packages
texlive-base - TeX Live: Essential programs and files
texlive-base-bin - TeX Live: Essential binaries
texlive-base-bin-doc - TeX Live: Documentation files for texlive-base-bin
texlive-bibtex-extra - TeX Live: Extra BibTeX styles
texlive-common - TeX Live: Base component
... snip...
texlive-plain-extra - TeX Live: Plain TeX supplementary packages
texlive-science - TeX Live: Typesetting for natural and computer sciences

You’ll notice that there are a lot of packages available. Now, you could go through and probably piece together the exact set of packages you need, or you could just do this…

$> apt-get install texlive-full

This will install everything, docs, languages, fonts, advanced math typesetting, you’ll even be able to generate PDFs in Mongolian. All of the packages together are about 1.1GB, and it takes a long time to download/build, but avoiding the apt-get hassle is worth it.

RTex Gem for Rails Support

If you’re planning on using a LaTeX template to generate a PDF in your rails app, you’ll need to make use of the RTeX gem. Once you’ve got the RTeX gem installed, create the view for your ActiveRecord model.

In this example application, we have an invoice model. We want an employee to be able to view the LaTeX generated invoice by accessing something like http://localhost:3000/invoices/1.pdf

Our controller is pretty straightforward.

1
2
3
4
5

class InvoiceController < ActionController::Base
  def show
    @invoice = Invoice.find(params[:id])
  end
end

Next we need to create a view that will store the LaTeX markup that creates our PDF.

$> touch app/views/invoices/show.pdf.rtex

Once you’ve pulled your hair out writing the LaTeX markup required to get the invoice PDF looking the way you want, save the LaTeX to the show file you’ve just created in app/views/invoices/show.pdf.rtex

Drink a Beer

You should now be able to access your pretty LaTeX formatted PDF invoice @ http://localhost:3000/invoices/1.pdf