ActiveSpec - Ruby Specifications Library
ActiveSpec is a Ruby implementation of the Specification pattern. It was born out of the desire to implement more complicated validations than the built-in Ruby On Rails validations macros allow and can be used with both Rails and non-Rails applications.
Installation
ActiveSpec can currently be downloaded from Subversion. The repository URL is:
http://opensource.agileevolved.com/svn/root/activespec/trunk
It will be released as a gem shortly.
Overview
ActiveSpec is comprised of four main components:
1. A set of low-level Specification classes
Many of these are designed to work with one or more attributes of a given object and are mostly modelled on the existing set of Ruby On Rails validation macros. There is also a CompositeSpecification class for working with more than one specification at one time. It is also very easy (and actively encouraged) to create your own low-level Specification classes. See ActiveSpec::Specifications for more information.
2. ActiveSpec::Base class
This can be sub-classed to create specifications in a more declarative manner. Here is a small example:
class UserSpecification < ActiveSpec::Base
requires_presence_of :username, :password
requires_confirmation_of :password
end
The main interface for any specification is a satisfied_by?
method. The low-level specification classes (including CompositeSpecification) define satisfied_by?
as an instance method and the ActiveSpec::Base specifications define it as a class method (it is not necessary to instantiate ActiveSpec::Base specifications).
3. High-level specification DSL
ActiveSpec provides a high level DSL for creating specifications, that builds on top of ActiveSpec::Base. An alternative way of creating the above UserSpecification using the specification DSL would be:
specification :user do
requires_presence_of :username, :password
requires_confirmation_of :password
end
This will automatically create a UserSpecification class with the given specifications. See ActiveSpec::Context for more information.
4. ActiveSpec::Satisfies module
The Satisfies module can be included into your own classes to provide functionality for working with specifications. This will allow you to directly associate specifications with your classes in a style similar to using Rails’ validates_* macros.
class User
include ActiveSpec::Satisifies
must_satisfy :user_specification
end
user = User.new
user.satisfies_specs?
For more information, see ActiveSpec::Satisfies.
Also included with the library is a helper function for pre-loading specification classes in a given directory. See ActiveSpec#preload_specifications.
Rails integration
You can use ActiveSpec in your Rails app with your ActiveRecord model classes by adding the following lines to your environment.rb file:
require 'active_spec'
ActiveRecord::Base.send(:include, ActiveSpec::Satisfies)
You will currently have to deal with the loading of your specification files yourself and you might find the preload_specifications method handy for this. There are plans to make integration with a Rails app even easier with an ActiveSpec Rails plugin in the near future.
Future plans
One of the main features that ActiveSpec is missing that Rails’ validations module provides is error message functionality. This will eventually be added to ActiveSpec, possibly with integration into the ActiveRecord::Errors class.
Comments and feedback
Please send any comments to contact [AT] lukeredpath [DOT] co [DOT] uk. Please report any bugs on the Agile Evolved Open Source Trac at opensource.agileevolved.com.
Credits
Copyright © Luke Redpath 2006. Released under the MIT license.