Mike Cohn just wrote a nice post justifying what has become the preferred template for stories in BDD:

As a role

I want feature

So that benefit

After a few months of exploring git and hosting RSpec’s git repository at github, we’re happy to announce that github is now RSpec’s official home for Source Code Management.

Tracking will continue to live at the lighthouse.

We will continue to release gems to http://rubyforge.org/projects/rspec, but we will no longer be committing changes to the subversion repository there. For Rails users who are using the rspec plugins for Rails, edge rails now supports git-hosted plugins.

We’ve broken the project up into four separate repositories:

• rspec for the rspec gem/plugin

• rspec-rails for the rspec-rails gem/plugin (formerly rspec_on_rails)

• rspec-tmbundle for the TextMate bundle

• rspec-dev for developers/contributors

See the wikis for each repository for more information about building, installing and contributing to the project.

I’m pleased to announce that Pat Maddox is joining the RSpec Development Team.

As you may already know, Pat has been contributing great patches and actively participating on the rspec-users and rspec-devel mailing lists for quite some time. He has demonstrated a deep understanding of Behaviour Driven Development in general, and specifically as it applies to Rails, which has certainly posed some of the more interesting questions on our mailing lists.

We are all excited to have Pat on board and look forward to his continued contribution.

Here are the slides from my presentation at Emerging Technologies for the Enterprise on Integration Testing with RSpec’s Story Runner.

If you use autotest with rspec or test/unit, you’ve probably had this experience (or one like it):

You want to add some new behaviour to a model object, so you write a spec, watch it fail, make it pass, and then wait until the entire spec suite runs. Even if you’ve got a fast-running suite, this can be painful sometimes.

Wouldn’t it be great if you could limit the scope of what directories autotest observes? Well it turns out that you can! Recent releases of ZenTest include a find_directories attribute on the autotest object. Just add this to your .autotest file:

Autotest.add_hook :initialize do |at|
unless ARGV.empty?
  at.find_directories = ARGV.dup
end
end

and then you can say:

autotest app/models spec/models

and it will only observe those directories. This is nice and flexible, but I find that most of the time I’m wanting pairs like that: app/models and spec/models, or app/views/accounts and spec/views/accounts. In that case, I’d really like to just say:

autotest models

To accomplish that you can do this to the hook instead:

Autotest.add_hook :initialize do |at|
unless ARGV.empty?
  at.find_directories = ["spec/#{ARGV.first}","app/#{ARGV.first}"]
end
end

Want the best of both worlds? Try this:

Autotest.add_hook :initialize do |at|
unless ARGV.empty?
  at.find_directories = ARGV.length == 1 ? ["spec/#{ARGV.first}","app/#{ARGV.first}"] : ARGV.dup
end
end

The only limitation of this is that it’s based on directories, not files. Once in a while, when I’m bootstrapping a new object, I’ll keep the examples and the implementation in the same file until I’ve got things fleshed out a bit the object is ready to play nice with others. In that case, I might like to just point autotest to that one file. I started working on a patch for this for ZenTest, but I’m not sure it’s worth the extra effort. What do you think?

Regardless – happy auto-exemplifying!

I’m going to be presenting at ETEC on RSpec’s Story Runner. This will be more or less the same talk I’m presenting at RailsConf in May, except that it’s in March and on the other coast.

See you in Philly!

ZenTest’s last two releases are not compatible with previous versions of RSpec. This is good news because Autotest now exposes better extension points for subclasses like those that ship with RSpec. Before, RSpec had to monkey patch Autotest to control the mappings of specs to files to run, and the list of files/directories to ignore. Now RSpec gets to use public methods (instead of instance variables) and documented hooks to do it’s work.

In the long run, this will keep things more flexible for both RSpec and ZenTest. In the short run, the catch for you is that you have to use compatible versions of RSpec and ZenTest. They are:

RSpec versionZenTest version

<= 1.1.1 <= 3.7.x

1.1.2 3.8.x

1.1.3 3.9.x

I’m going to be presenting at RailsConf 2008 on RSpec’s Story Runner. I’ll be talking about how I approach writing for the Story Runner and address several related issues including:

• plain text stories vs pure Ruby (when is which appropriate?)

• extending the RailsStory with custom helpers

• testing forms using webrat within the Story Runner

• finding a balance of domain and UI scenarios

• duplication between stories/scenarios and model/view/controller/helper examples

That’s probably already more than I can cover fairly in a 45 minute presentation, but feel free to make other suggestions if you have them.

See you in Portland!

Updated on 27 May, 2008

I’m not in the habit of blogging every change we make to RSpec, but this one may change the way your suite behaves if you have not been following convention.

As of RSpec’s trunk revision 3246 there is a new command line option that lets you control the filename pattern to match. This allows you to restrict files that are loaded when running the spec command in the same way that you can with rake. It also means that helper files that you may depend on are no longer loaded implicitly.

The default is:

<code>"spec/**/*_spec.rb".
</code>

To get rspec to behave as it did before this change, use this:

<code>--pattern "spec/**/*.rb"
</code>

If you prefer naming your spec files “foo_example.rb”, you can do this:

<code>--pattern "spec/**/*_example.rb"
</code>

You can also supply multiple patterns (comma separated):

<code>--pattern "spec/**/*_example.rb, spec/**/*_spec.rb"
</code>

This is a very handy way to avoid loading resource files (helpers, matchers, etc) except when you require them explicitly from other files.

This is currently only in trunk, but will be part of the next release.

The RSpec-1.1.2 release includes changes to keep RSpec compatible with autotest in ZenTest-3.8.0. This new ZenTest release boasts an improved cascading configuration model that works well for subclasses (like those that ship with RSpec) and allows users to override the mappings of specs (or tests) to code as well as the list of files that get ignored by autotest.

To support this, Autotest now loads the following files in the following order:

Autotest
AutotestSubClass
~/.autotest
./.autotest

This allows RSpec (or any other library) to override defaults set in Autotest, and then provides users both generic (~/.autotest) and project specific (./.autotest) control over the mappings and exceptions.

How can you take advantage of this?

When autotest begins to run, it calls its :initialize hook. This hook is exposed by the add_hook method. You can use this to access the mappings and exceptions using the following methods on Autotest:

clear_mappings()
add_mapping(regexp, proc)
remove_mapping(regexp)

clear_exceptions()
add_exception(string)
remove_exception(string)

add_mapping

The add_mapping method adds a key/value pair to a hash that maps regexps to procs. Whenever autotest senses that a file is touched, it looks for the regexp that matches the file name and the runs all the files returned by the associated proc.

Imagine you’re working on a shopping cart app. You have some currency conversion behaviour in a Product model that you’d like to extract to an acts_as_currency plugin, and you want autotest to observe the process. You might add a mapping like this to .autotest:

Autotest.add_hook :initialize do |at|
at.add_mapping(%r%^plugins/acts_as_currency/lib/.*\.rb$%) {
  at.files_matching %r%^spec/models/product_spec\.rb$% +
  at.files_matching %r%^plugins/acts_as_currency/spec/.*_spec\.rb$%
}
end

In this case, a change to any of the files in the plugin’s lib directory would cause all the plugins specs to run, as well as the spec for the Product model.

add_exception

The add_exception method adds paths to a list of paths that Autotest ignores.

I like to run autotest in verbose mode (autotest -v) because it tells me when I change a file that it doesn’t know what to do with. The drawback is that it wants to tell me every time I commit because files in the .svn/.hg/.git directories change. So I’ve got these all listed as exceptions in my ~/.autotest file, along with assorted others:

Autotest.add_hook :initialize do |at|
%w{.svn .hg .git}.each {|exception|at.add_exception(exception)}
end

Note that autotest compiles this list to a Regexp with no anchors, so .hgignore and .gitignore would also get ignored in this case.

Cascading config and granular control

One of the coolest changes in ZenTest-3.8.0 is that autotest loads both ~/.autotest and ./.autotest. So now you can have the hooks you like on every project (like growl notifation) all in one place and still have project specific settings.

This also allows you to set up global mappings/exceptions and modify them at the project level. See Autotest’s RDoc for more info.