cheat --execute

on August 01, 2008 @ 03:21 PM

I hate having to continuously lookup the steps to install things every few weeks. The cheat gem works for most things to find installation instructions relatively quickly, but sometimes I just want to install something, not necessarily have to search through lines of example usage to find the installation instructions. Enter two new options for the cheat gem: dash x and dash dash execute. It’s simple. For example:

1
2
3
4
5
6
7
8
9
10

cd /some/dummy/rails/project
cheat install_rspec_rails -x

  # This is to install the latest rspec/rspec-rails into 
  # a rails project. 
  script/plugin install git://github.com/dchelimsky/rspec.git
  script/plugin install git://github.com/dchelimsky/rspec-rails.git
  script/generate rspec

Would you like to execute the above sheet? (Y/N)

I’ve sent defunkt a pull request on github, I hope it includes the change. Until then, the change is only on my fork: http://github.com/zdennis/cheat/tree/master

To install do the following:

1
2
3
4

git clone git://github.com/zdennis/cheat.git
cd cheat
rake package
sudo gem install pkg/cheat-1.2.2.gem

Enjoy,

Rails Ticket #11491

on April 01, 2008 @ 12:46 AM

If you have a few minutes, please review and comment on Rails ticket #11491.

http://dev.rubyonrails.org/ticket/11491

In short, it adds the ability for “render :partial => some_collection” to render the correct partial based on each element in some_collection. Currently Rails uses the first element to determine what to render for every element in the collection.

Thanks in advance,

Trying RSpec's Rubyesque Stories

on March 05, 2008 @ 12:35 AM

Today my pair and I wrote some stories using the rubyesque RSpec story style along with a corresponding step file. It went better then expected. We ended up a story like:

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
27
28
29

# in stories/expenses/a_user_creating_a_misc_expense_story.rb
Story "User creating misc. expense", %|
  As a user 
  I want be able to submit an expense reimbursement request for a misc. expense
  so that I can be reimbursed for business expenditures|,
  :steps_for => :expense,
  :type => RailsStory do
 
  Scenario "creating a misc. expense unsuccessfully" do
    Given "a user at a new expense reimbursement page"
    # ....
  end
  
  Scenario "creating a misc. expense successfully" do
    Given "a user at a new expense reimbursement page"
    # ...
  end
end


# in stories/steps/expense.rb
steps_for :expense do
  Given "a user at a new expense reimbursement page" do
    go_to_root
    click_new_expense_reimbursement_link
  end

  # ...
end

test/unit story runner

on November 14, 2007 @ 01:53 AM

As you may know rspec has integrated RBehave into itself. In the rspec world it’s more recently been called Story Runner.

Some background links:

• Introducing RBehave
• User stories with RSpec’s Story Runner
• Story Runner in Plain English
• Plain Text Stories: Part III

Story Runner itself hasn’t officially been released and while it has been becoming more polished myself and a colleague (Drew Colthorp) wanted higher level acceptance tests in my ruby projects (including rails).

Story Runner also has two implementations (or at least APIs). The latest is the plain text Story Runner. This requires that for every story you have at least two files. One that is plain text for the customer to write and one that is a “matcher” file developers write. Information on this can be found here

The older version of Story Runner uses the original RBehave style syntax. Lots of blocks and lots of argument passing. There is also a bug in this implementation regarding sharing blocks given to story parts. But enough about rspec, this post is on a lighter weight and simpler Story Runner.

So here’s to a working and testing implementation of a Story Runner in test/unit.

test/unit Story Runner

To start, an example:

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
27
28
29
30
31

class EventCreationTest < ActionController::IntegrationTest
  fixtures :all

  Story "As a user I should be able to create an event so that others can RSVP and attend."
  
  Scenario "Creating an event unsuccessfully with insufficient input" do
    Given :a_user_at_the_create_an_event_page
    When :they_submit_the_create_an_event_form_with_insufficient_input
    Then :they_will_see_an_error_explanation
    And :they_will_see_the_create_an_event_page
  end 

   #
   # HELPERS
   #
   def a_user_at_the_create_an_event_page
       # ....
   end

   def submit_the_create_an_event_form_with_insufficient_input
       # ...
   end

   def see_an_error_explanation
       # ...
   end

   def see_the_create_an_event_page
      # ...
   end
end

Some important things to note on the structure:

• the Story takes a description of the story. It does NOT take a block.
• multiple Story’s can be defined in a file although I prefer organizing them in separate files
• all Scenario’s which follow a Story will belong to that Story.
• the Scenario takes a description of the particular scenario or acceptance test for a story. It does take a block.
• inside of a Scenario you describe the story parts. These are Given, When, Then, and And.

Some important things to note on the story part descriptions:

• Each story part can take a string or symbol description
• helper method calls are generated off from the story part description

Helper method calls are generated by taking the full story part description and then removing the leading word until a helper method is found. If there are no helper methods found then an exception is raised.

Some important things to note on the goals of this implementation:

• in theory customers write acceptance tests
• in practice developers translate customer desires into acceptance tests
• ideally the acceptance tests should be high level enough that a customer can read/write them
• since developers will most likely write these acceptance tests this implementation should allow for developer shortcuts
• this should just work on a test/unit project, projects updating to this shouldn’t have to convert or make changes up front to existing code

script/plugin install

script/plugin install \
  http://continuous.rubyforge.org/svn/tags/test_unit_story_runner-0.1.0

Final Thoughts

Before I forget you can do argument passing as well on story parts:

1
2
3
4
5

Scenario "a user successfully making a guess in the game" do
  Given :a_user_at_the_game
  When :they_make_a_guess_of, 20_000
  Then :they_will_win_a_car
end

This feature is there, but I would advocate only using it when it helps the readability of your tests.

This is a stable (tested) experiment. It’s a thin wrapper around the test/unit framework and it works with any Test::Unit::TestCase. The price to pay for higher level acceptance tests is now next to nothing so give it a shot.

This is the creation of a trip to Madison, WI where Drew and I had a chance to discuss and vent about the state of acceptance tests in Rails projects specifically. A few days later we had this implementation, and about a month later you’ve got this post…

Suggestions and feedbacks are warmly welcomed.

Happy rubying!

rspec_on_rails render_and_receive_matcher

on November 14, 2007 @ 12:10 AM

Earlier today my pair and I saw a repetitious pattern in our view specs when we were using helpers. It looked similar to the following:

1
2
3
4
5

 it "displays foo" do
    template.should_receive(:bar).with(@foo).and_return(%|<p id='bar'></p>|)
    render_it
    response.should have_tag("p#bar")
 end

The repetition was in the three lines:

• setup a simple should receive and return
• make the call to render
• verify the response had the returned element

Tonight I spent some time spiking a way to cure this repetition. I’m a bigger fan of verbosity in specs over DRYness, but I think my exploration gives us something good. The above example now looks like:

1
2
3
4
5

 it "displays foo" do
    during_render do
      template.should receive_and_render(:bar).with(@foo)
    end
 end

The receive_and_render method sets up a should_receive expectation on the template. For completeness there is also a stub_and_render method. As you might guess this method sets up a stub! on the template.

This doesn’t just work on the template object. It works on any object, but you should probably only use it on objects that show up in the view.

script/plugin install

script/plugin install \    
  http://continuous.rubyforge.org/svn/trunk/rspec/matchers/rspec_on_rails_render_and_receive

Final Thoughts

This in an experiment. As I am learning more about the spirit of rspec and it’s organization there are a few things I want to change with this. Right now this is implemented as a matcher which doesn’t feel quite right, but time will tell. So in the meantime… Happy rubying!

Plain Text Story Running

on October 23, 2007 @ 09:16 PM

David Chelimsky announced yesterday the first implementation of Plain Text Stories.

http://blog.davidchelimsky.net/articles/2007/10/22/plain-text-stories-on-rails

More on this to come…

Story Runner - constructive ideas

on October 16, 2007 @ 08:38 PM

Yesterday I ranted on some criticisms that I have of RSpec’s Story Runner. This post will try to follow up the criticisms which an implementation I like.

The code we started with yesterday is:

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

Story "View Home Page", %{
  As a user I want to view my home page
  So that I can get a birds eye view of the system
}, :type => RailsStory do

  Scenario "Latest published article" do
    Given "an author named", "Zach" do |name|
       @user = User.create! :name => name
    end
   
    When "he visits the home page", "/" do |path|
       get path
    end

    Then "he should see the latest article published front and center" do
       # ... do something to see the article shows as expeted
    end
  end

end

Here is a version of this that I like, and is implemented in test/unit story runner (which has yet to make its public debut):

1
2
3
4
5
6
7

Story "As a user I want to view my home page so that I can get a birds eye view of the system"

Scenario "Latest published article" do
  Given "an author"
  When "he visits the home page"
  Then "he will see the latest article published front and center"
end

Story Description

It gets rid of the unnecessary description and :type parameters. It leaves only the story itself.

Story Do/End Blocks

It removes them. They are not needed. They provide unnecessary grouping which hurts readability for the customer.

Scenario Do/End Blocks

These are kept. These are the one area where I feel making a visual grouping is important for the customer and the developer. All Scenario’s will be attached to the Story declaration which precedes it.

Argument Passing

I removed the arguments from the original example. They weren’t providing value to my tests. I do believe argument passing is valuable but it must be in a way that adds value to the test. For example in a game I am ok with the 500_000 below:

1
2
3
4
5

Scenario "Becoming the top scorer" do
  Given "a player"
  When "he makes a guess of", 500_000
  Then "he will see himself as the number one scorer"
end

It seems that a lot of cases where arbitrary arguments are passed can be updated to make their descriptions more meaningful. It can do this by describing what is under test based on what may influence the test. Typically a user’s name doesn’t do this. So rather then:

Given "a user named Zach"

I’d rather see why “Zach” is special. Maybe he’s an admin:

Given "an administrator"

The Process

I haven’t explained yet how test/unit story runner is implemented so bare with me. When you add a new Story or Scenario it looks like the example posted above.

When you change or update an existing Story or Scenario it still looks like the example posted above. There is no embedded code, or horrendous blocks following every declaration (just the Scenario one!).

Reusable Code

Here’s where a high level overview of test/unit story runner comes to fruition. It takes a story part’s (Given/When/Then/And) description and turns that into a helper method using a simple mapping process.

• take the description and downcase it
• strip out all punctuation
• then replace spaces with underscores
• look for the method name
• if it exists, execute it, otherwise strip the first word and repeat

So every story description maps to a method. And these methods can be included at the bottom of your story file or in a shared helper file (or both!).

Here’s a few example mappings:

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

Given "an administrator" # => an_administrator
When "he clicks the big button" # => clicks_the_big_button
Then "he will see a picture"  # => see_a_picture
And "he will see another button!" # => see_another_button

def an_administrator
  # ...
end

def clicks_the_big_button
  # ...
end

def see_a_picture
  # ...
end

def see_another_button
  # ...
end

What I like about this is that it is easy for developers to map a description to a method, and it separates the implementation of a Story from it’s definition. This allows the customers to work consistently to add and updates Story’s, as well as the same for developers.

Final Thoughts

One thing that lacks right now in the test/unit story runner is a way to mark Story’s as pending. I think this can be accomplished though by capitalizing the Story, Scenario or any of the story parts.

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

Story "Logging in"

SCENARIO "User with good credentials" do
  # this whole scenario is pending regardless of whats in it
  Given "..."
  When "..."
end

Scenario "User with bad credentials" do
  # this whole scenario is executed
end


STORY "Logging out" # marks the whole story as pending 

Scenario "logged in user" do
  # this will be marked as pending because of the story it belongs to
end

There has been recent discussion on the RSpec mailing list about this:

• http://rubyforge.org/pipermail/rspec-users/2007-October/003690.html
• http://rubyforge.org/pipermail/rspec-users/2007-October/003704.html

It seems that everyone is in agreement that the holy grail is a pure plain text file. There are drawbacks with this though that are currently being evaluated.

Pat Maddox has came up with a nice alternative to my above suggestion called SpecMatcher’s. It looks promising to the users of rspec though that Story Runner will turn into something truly beneficial to developers and customers alike.

Story Runner - constructive criticism

on October 15, 2007 @ 08:56 AM

If you keep up with RSpec development you’ll know that RBehave has been integrated into RSpec and is known as the “Story” Runner. This is a unfolding of current thoughts and criticism, I apologize for any lack of explanation, but I need to do a quick braindump.

I love the concept of Story Runner, but I do not like it’s current syntax. Below are the criticism’s for why. First though the code example I’ll use to discuss the Story syntax.

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

Story "View Home Page", %{
  As a user I want to view my home page
  So that I can get a birds eye view of the system
}, :type => RailsStory do

  Scenario "Latest published article" do
    Given "an author named", "Zach" do |name|
       @user = User.create! :name => name
    end
   
    When "he visits the home page", "/" do |path|
       get path
    end

    Then "he should see the latest article published front and center" do
       # ... do something to see the article shows as expeted
    end
  end

end

Story Description

The story description is hideous. It requires a description, and then the story description, and then a type flag (at least for Rails projects). The Story itself should contain it’s actual story description. The pseudo description set in the first parameter and the :type flag should be able to be dropped. Right now these two things do not add value, but decrease customer readability.

Story Do/End Blocks

Everything is organized with do/end blocks. While I love the closure capabilities of ruby I am not a big fan of overusing blocks in Story files themselves. I would much rather drop the do/end blocks unless they provide needed clarity.

I’d like to remove the do/end block on Story because it the definition of the file format should read.. “All Scenarios belong to the preceding Story declaration”. Which to me is still just as readable.

Scenario Do/End Blocks

These should stay put. To me these are essential for providing clarity amongst your acceptance tests which scenario they are pertaining to.

Story Part Do/End Blocks

Story part (Given, When, Then, And) do/end blocks need to go away completely. They allow for developers to embed code directly into the high level story, which immediately reduces the readability from both a customer and developer perspective.

It has been mentioned that you can use editors code folding techniques to hide the code, but as pointed out on the rspec mailing list I don’t want my customer to have to use a code editor to read the acceptance tests.

Argument Passing

After every story part in the above example you have the ability to pass in arguments to the do/end block. When this adds value it makes sense to do this, but when it is a trivial piece of information it doesn’t seem to add any value. Instead it detracts readability.

It detracts readability by creating new tokens a customer has to visually parse, both in the argument list for the story part and also the argument list for the do/end block. It also makes data that may not be important seem important because they are singled out as their own arguments.

Argument passing should be used to add value to the story part with something that helps identify a behavior that is going to happen that your test is going to depend on. Usually this is not the user’s name or the root path (”/”) of a site, although in some cases it may be.

The Process Is Flawed

The ideal process is having a customer write and own the stories and the acceptance tests. As these change the customer should be responsible for updating them. The developers should be responsible for implementing them.

Given the above format once you add embedded code to a Story part you immediately reduce the readability from a customer’s perspective to own and maintain that Story and it’s acceptance tests should it change in the future. Also if a customer changes a Story should he/she be responsible for deleting the developers implementation of last acceptance test?

So the process is flawed. We shouldn’t have a format which doesn’t provide consistency to both the developer and the customer. So we need to tweak the Story format to enable a format which is consistent at both creation and change/update time of a Story and/or it’s acceptance tests.

Reusable Code

Embedding code inside a Story part renders it non-reusable. So to combat this you create a helper method and call from within the Story part’s do/end block. So now you have a nice clean description and with a do/end block wrapping a helper method, like below:

1
2
3
4

Given "a user logged into the system", "Joe" do |name|
  @user = User.create! name
  login_as @user
end

I see this and I want to refactor this. Clearly the description well named. I should be able to rely on a similarly well named helper method to handle creating or finding a user and logging that user in. If I do this then why do I need a do/end block (besides the fact of RSpec using it to trigger a pending Story)?

It seems so far that you don’t need a do/end block. It doesn’t add value. It takes away value.

Mike Clark's - How Would You Test This

on September 18, 2007 @ 02:13 AM

Below is my rspec answer to Mike Clark’s recent post How Would You Test This which challenges people to post their own solution to how you’d test his MenuitemsController.

One thing Mike doesn’t mention about the frustration that people have with testing controllers is testing that testing controllers requires you to test your view associated with it (unless you are only redirecting).

There are ways around testing views, but most install a custom hack or installing a third party plugin or framework like rspec, Test::Rails or view_test.

Since Mike didn’t include any views in his original post I haven’t provided any tests for them in this post.

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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

require File.dirname(__FILE__) + '/../spec_helper'

def do_post(attributes)
  post :create, :menu_item => attributes
end

describe MenuItemsController, 'Creating a new menu item (success)' do

  before do
    attributes = {'name' => "Enchilada", 'price' => 4.99}
    @menu_item = mock_model(MenuItem)
    MenuItem.should_receive(:new).with(attributes).once.and_return(@menu_item)
    @menu_item.should_receive(:save).with().once.and_return(true)

    do_post attributes
  end
  
  it 'redirects to index' do
    response.should redirect_to(menu_items_url)
  end
  
  it 'assigns @menu_item' do
    assigns[:menu_item].should be(@menu_item)
  end
  
  it 'sets the flash notice' do
    flash[:notice].should_not be(nil)    
  end
end

describe MenuItemsController, 'Creating a new menu item (failure)' do

  before do
    attributes = {'name' => "Enchilada", 'price' => 4.99}
    @menu_item = mock_model(MenuItem)
    MenuItem.should_receive(:new).with(attributes).once.and_return(@menu_item)
    @menu_item.should_receive(:save).with().once.and_return(false)

    do_post attributes
  end

  it 'renders new template on failed save' do
    response.should be_success
    response.should render_template('new')
  end
  
  it "assigns @menu_item" do
    assigns[:menu_item].should be(@menu_item)
  end

  it "not set the flash notice" do
    flash[:notice].should be(nil)      
  end
  
end

rspec's mocking framework is staying put

on September 05, 2007 @ 02:02 AM

On the rspec-users mailing list there’s been talk recently of removing the built-in mocking framework. The idea was that it offered nothing that the existing mocking frameworks like Mocha, Flexmock or Hardmock didn’t already offer.

The other day David Chelimsky announced in this post that it will be keeping rspec’s mocking framework for the foreseeable future.