Skip to content
This repository

An ActiveRecord null database adapter for greater speed and isolation in unit tests.

This branch is 0 commits ahead and 0 commits behind master

Merge pull request #54 from amorphid/master

Fix dead link in README.md
latest commit 352dbc4907
Bram de Vries blaet authored
Octocat-spinner-32 gemfiles Test against AR 4.1.beta February 17, 2014
Octocat-spinner-32 lib Extracted classes into their own files February 03, 2014
Octocat-spinner-32 spec Needs a more specific rescue, of course February 03, 2014
Octocat-spinner-32 .gitignore Updated .gitignore January 27, 2014
Octocat-spinner-32 .travis.yml Test against AR 4.1.beta February 17, 2014
Octocat-spinner-32 Appraisals Test against AR 4.1.beta February 17, 2014
Octocat-spinner-32 CHANGES.md Updated changelog February 17, 2014
Octocat-spinner-32 Gemfile Removed iconv dependency February 17, 2014
Octocat-spinner-32 LICENSE initial commit February 17, 2008
Octocat-spinner-32 README.rdoc Fix dead link in README.md February 23, 2014
Octocat-spinner-32 Rakefile Added MIT license to gemspec January 30, 2014
Octocat-spinner-32 VERSION Version bump to 0.3.1 February 17, 2014
Octocat-spinner-32 activerecord-nulldb-adapter.gemspec Regenerate gemspec for version 0.3.1 February 17, 2014
README.rdoc

Gem
Version Build
Status

The NullDB Connection Adapter Plugin

What

NullDB is the Null Object pattern as applied to ActiveRecord database adapters. It is a database backend that translates database interactions into no-ops. Using NullDB enables you to test your model business logic - including after_save hooks - without ever touching a real database.

Compatibility

Ruby

Currently supported Ruby versions: MRI 1.9.3, 2.0.0, 2.1.0

Experimental support provided for: JRuby, Rubinius (both in 1.9 mode)

ActiveRecord

Any version of ActiveRecord since 2.0, including ActiveRecord 4.0

It is tested against AR 2.3, 3.0, 3.1, 3.2 and 4.0.

Installation

gem install activerecord-nulldb-adapter

How

Once installed, NullDB can be used much like any other ActiveRecord database adapter:

ActiveRecord::Base.establish_connection :adapter => :nulldb

NullDB needs to know where you keep your schema file in order to reflect table metadata. By default it looks in RAILS_ROOT/db/schema.rb. You can override that by setting the schema option:

ActiveRecord::Base.establish_connection :adapter => :nulldb,
                                        :schema  => 'foo/myschema.rb'

NullDB comes with RSpec integration. To replace the database with NullDB in all of your specs, put the following in your spec/spec_helper:

require 'nulldb_rspec'
include NullDB::RSpec::NullifiedDatabase

Or if you just want to use NullDB in a specific spec context, you can include the same module inside a context:

require 'nulldb_rspec'

describe Employee, "with access to the database" do
  fixtures :employees
  # ...
end

describe Employee, "with NullDB" do
  include NullDB::RSpec::NullifiedDatabase
  # ...
end

If you want to have NullDB enabled by default but disabled for particular contexts then (see this post)

NullDB::Rspec provides some custom matcher support for verifying expectations about interactions with the database:

describe Employee do
  include NullDB::RSpec::NullifiedDatabase

  it "should cause an insert statement to be executed" do
    Employee.create!
    Employee.connection.should have_executed(:insert)
  end
end

UnitRecord-style verification that no database calls have been made at all can be achieved by using the special :anything symbol:

describe "stuff that shouldn't touch the database" do
  after :each do
    Employee.connection.should_not have_executed(:anything)
  end
  # ...
end

You can also experiment with putting NullDB in your database.yml:

unit_test:
  adapter: nulldb

However, due to the way Rails hard-codes specific database adapters into its standard Rake tasks, you may find that this generates unexpected and difficult-to-debug behavior. Workarounds for this are under development.

Why

There are a number of advantages to writing unit tests that never touch the database. The biggest is probably speed of execution - unit tests must be fast for test-driven development to be practical. Another is separation of concerns: unit tests should be exercising only the business logic contained in your models, not ActiveRecord. For more on why testing-sans-database is a good idea, see: www.dcmanges.com/blog/rails-unit-record-test-without-the-database.

NullDB is one way to separate your unit tests from the database. It was inspired by the ARBS and UnitRecord libraries. It differs from them in that rather than modifying parts of ActiveRecord, it implements the same [semi-]well-documented public interface that the other standard database adapters, like MySQL and SQLServer, implement. This has enabled it to evolve to support new ActiveRecord versions relatively easily.

One concrete advantage of this null-object pattern design is that it is possible with NullDB to test after_save hooks. With NullDB, you can call #save and all of the usual callbacks will be called - but nothing will be saved.

Limitations

  • It is not an in-memory database. Finds will not work. Neither will reload, currently. Test fixtures won't work either, for obvious reasons.

  • It has only the most rudimentery schema/migration support. Complex migrations will probably break it.

  • Lots of other things probably don't work. Patches welcome!

Who

NullDB was originally written by Avdi Grimm <avdi@avdi.org>. It is currently maintained by Bram de Vries.

Where

License

See the LICENSE file for licensing information.

Something went wrong with that request. Please try again.