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.

README