bmabey-database_cleaner 0.1.1

data/README.textile

@@ -0,0 +1,100 @@
+h1. Database Cleaner
+
+Database Cleaner is a set of strategies for cleaning your database in Ruby.
+The original use case was to ensure a clean state during tests.  Each strategy 
+is a small amount of code but is code that is usually needed in any ruby app 
+that is testing with a database.
+
+Right now the only ORM supported is ActiveRecord and it currently has two strategies:
+truncation and transaction.
+
+Support for DataMapper is built-in.  All that needs to be written are the strategies. :)
+
+h2. How to use
+
+<pre>
+  require 'database_cleaner'
+  DatabaseCleaner.strategy = :truncation
+
+  # then, whenever you need to clean the DB
+  DatabaseCleaner.clean
+</pre>
+
+With the :truncation strategy you can also pass in options, for example:
+<pre>
+  DatabaseCleaner.strategy = :truncation, {:only => %[widigets dogs some_other_table]}
+</pre>
+
+<pre>
+  DatabaseCleaner.strategy = :truncation, {:except => %[widigets]}
+</pre>
+
+(I should point out the truncation strategy will never truncate your schema_migrations table.)
+
+
+Some strategies require that you call DatabaseCleaner.start before calling clean 
+(for example the :transaction one needs to know to open up a transaction). So
+you would have:
+
+<pre>
+  require 'database_cleaner'
+  DatabaseCleaner.strategy = :transaction
+  
+  DatabaseCleaner.start # usually this is called in setup of a test
+  dirty_the_db
+  DatabaseCleaner.clean # cleanup of the test
+</pre>
+
+At times you may want to do a single clean with one strategy.  For example, you may want
+to start the process by truncating all the tables, but then use the faster transaction
+strategy the remaining time.  To accomplish this you can say:
+
+<pre>
+  require 'database_cleaner'
+  DatabaseCleaner.clean_with :truncation
+  DatabaseCleaner.strategy = :transaction
+  # then make the DatabaseCleaner.start and DatabaseCleaner.clean calls appropriately
+</pre>
+
+For use in Cucumber please see the section below.
+
+
+
+h2. Why?
+
+One of my motivations for writing this library was to have an easy way to 
+turn on what Rails calls "transactional_fixtures" in my non-rails 
+ActiveRecord projects.  For example, Cucumber ships with a Rails world that
+will wrap each scenario in a transaction.  This is great, but what if you are 
+using ActiveRecord in a non-rails project?  You used to have to copy-and-paste
+the needed code, but with DatabaseCleaner you can now say:
+
+<pre>
+  #env.rb
+  require 'database_cleaner'
+  require 'database_cleaner/cucumber'
+  DatabaseCleaner.strategy = :transaction
+</pre>
+
+Now lets say you are running your features and it requires that another process be 
+involved (i.e. Selenium running against your app's server.)  You can simply change
+your strategy type:
+
+<pre>
+  #env.rb
+  require 'database_cleaner'
+  require 'database_cleaner/cucumber'
+  DatabaseCleaner.strategy = :truncation
+</pre>
+
+You can have the best of both worlds and use the best one for the job:
+<pre>
+  #env.rb
+  require 'database_cleaner'
+  require 'database_cleaner/cucumber'
+  DatabaseCleaner.strategy = (ENV['SELENIUM'] == 'true') ? :truncation : :transaction
+</pre>
+
+h2. COPYRIGHT
+
+Copyright (c) 2009 Ben Mabey. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "database_cleaner"
+    s.summary = %Q{TODO}
+    s.email = "ben@benmabey.com"
+    s.homepage = "http://github.com/bmabey/database_cleaner"
+    s.description = "TODO"
+    s.files = FileList["[A-Z]*.*", "{examples,lib,features,spec}/**/*", "Rakefile", "cucumber.yml"]
+    s.authors = ["Ben Mabey"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'database_cleaner'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.libs << 'lib' << 'spec'
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |t|
+  t.libs << 'lib' << 'spec'
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.rcov = true
+end
+
+begin
+  require 'cucumber/rake/task'
+  Cucumber::Rake::Task.new(:features)
+rescue LoadError
+  puts "Cucumber is not available. In order to run features, you must: sudo gem install cucumber"
+end
+
+task :default => :spec

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 1
+:patch: 1

data/cucumber.yml

@@ -0,0 +1 @@
+default: features

data/examples/features/example.feature

@@ -0,0 +1,11 @@
+Feature: example
+ In order to test DataBase Cleaner
+ Here are some scenarios that rely on the DB being clean!
+
+  Scenario: dirty the db
+    When I create a widget
+    Then I should see 1 widget
+
+  Scenario: assume a clean db
+    When I create a widget
+    Then I should see 1 widget

data/examples/features/step_definitions/example_steps.rb

@@ -0,0 +1,8 @@
+When /^I create a widget$/ do
+  Widget.create!
+end
+
+Then /^I should see 1 widget$/ do
+  Widget.count.should == 1
+end
+

data/examples/features/support/env.rb

@@ -0,0 +1,16 @@
+require 'rubygems'
+require 'spec/expectations'
+
+begin
+  require "#{File.dirname(__FILE__)}/../../lib/#{ENV['ORM']}"
+rescue LoadError
+  raise "I don't have the setup for the '#{ENV['ORM']}' ORM!"
+end
+
+$:.unshift(File.dirname(__FILE__) + '/../../../lib')
+require 'database_cleaner'
+require 'database_cleaner/cucumber'
+
+DatabaseCleaner.strategy = ENV['STRATEGY'].to_sym
+
+

data/examples/lib/activerecord.rb

@@ -0,0 +1,12 @@
+require 'activerecord'
+
+ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :dbfile => ":memory:")
+
+ActiveRecord::Schema.define(:version => 1) do
+  create_table :widgets do |t|
+    t.string :name
+  end
+end
+
+class Widget < ActiveRecord::Base
+end

data/features/cleaning.feature

@@ -0,0 +1,16 @@
+Feature: database cleaning
+  In order to ease example and feature writing
+  As a developer
+  I want to have my database in a clean state
+
+  Scenario Outline: ruby app
+    Given I am using <ORM>
+    And the <Strategy> cleaning strategy
+
+    When I run my scenarios that rely on a clean database
+    Then I should see all green
+
+  Examples:
+    | ORM          | Strategy      |
+    | ActiveRecord | transaction   |
+    | ActiveRecord | truncation    |

data/features/step_definitions/database_cleaner_steps.rb

@@ -0,0 +1,25 @@
+Given /^I am using (ActiveRecord|DataMapper)$/ do |orm|
+  @orm = orm
+end
+
+Given /^the (.+) cleaning strategy$/ do |strategy|
+  @strategy = strategy
+end
+
+When "I run my scenarios that rely on a clean database" do
+  full_dir ||= File.expand_path(File.dirname(__FILE__) + "/../../examples/")
+  Dir.chdir(full_dir) do
+    ENV['ORM'] = @orm.downcase
+    ENV['STRATEGY'] = @strategy
+    @out = `cucumber features`
+    @status = $?.exitstatus
+  end
+end
+
+Then "I should see all green" do
+  unless @status == 0
+    raise "Expected to see all green but we saw FAIL! Output:\n#{@out}"
+  end
+end
+
+

data/features/support/env.rb

@@ -0,0 +1,11 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../../lib')
+require 'database_cleaner'
+
+require 'spec/expectations'
+
+require 'test/unit/assertions'
+
+World do |world|
+  
+  world
+end

data/lib/database_cleaner.rb

@@ -0,0 +1,3 @@
+$LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__))) unless $LOAD_PATH.include?(File.expand_path(File.dirname(__FILE__)))
+require 'database_cleaner/configuration'
+

data/lib/database_cleaner/active_record/transaction.rb

@@ -0,0 +1,26 @@
+module DatabaseCleaner::ActiveRecord
+  class Transaction
+
+    def start
+      if ActiveRecord::Base.connection.respond_to?(:increment_open_transactions)
+        ActiveRecord::Base.connection.increment_open_transactions
+      else
+        ActiveRecord::Base.__send__(:increment_open_transactions)
+      end
+
+      ActiveRecord::Base.connection.begin_db_transaction
+    end
+
+
+    def clean
+      ActiveRecord::Base.connection.rollback_db_transaction
+
+      if ActiveRecord::Base.connection.respond_to?(:decrement_open_transactions)
+        ActiveRecord::Base.connection.decrement_open_transactions
+      else
+        ActiveRecord::Base.__send__(:decrement_open_transactions)
+      end
+    end
+  end
+
+end

data/lib/database_cleaner/active_record/truncation.rb

@@ -0,0 +1,63 @@
+
+module ActiveRecord
+  module ConnectionAdapters
+    class MysqlAdapter
+      def truncate_table(table_name)
+        execute("TRUNCATE TABLE #{table_name};")
+      end
+    end
+
+    class SQLite3Adapter
+      def truncate_table(table_name)
+        execute("DELETE FROM #{table_name};")
+      end
+    end
+
+  end
+
+end
+
+
+module DatabaseCleaner::ActiveRecord
+  class Truncation
+
+    def initialize(options={})
+      if !options.empty? && !(options.keys - [:only, :except]).empty?
+        raise ArgumentError, "The only valid options are :only and :except. You specified #{options.keys.join(',')}."
+      end
+      if options.has_key?(:only) && options.has_key?(:except)
+        raise ArgumentError, "You may only specify either :only or :either.  Doing both doesn't really make sense does it?" 
+      end
+
+      @only = options[:only]
+      @tables_to_exclude = (options[:except] || []) << 'schema_migrations'
+    end
+
+    def start
+      # no-op
+    end
+
+
+    def clean
+      connection.disable_referential_integrity do
+        tables_to_truncate.each do |table_name|
+          connection.truncate_table table_name
+        end
+      end
+  end
+
+  private
+
+    def tables_to_truncate
+      (@only || connection.tables) - @tables_to_exclude
+    end
+
+    def connection
+      ::ActiveRecord::Base.connection
+    end
+
+  end
+
+end
+
+

data/lib/database_cleaner/configuration.rb

@@ -0,0 +1,94 @@
+module DatabaseCleaner
+ 
+  class NoStrategySetError < StandardError;   end
+  class NoORMDetected < StandardError;   end
+  class UnknownStrategySpecified < ArgumentError;   end
+
+  module ActiveRecord
+    def self.available_strategies
+      %w[truncation transaction]
+    end
+  end
+
+  module DataMapper
+    def self.available_strategies
+      %w[]
+    end
+  end
+
+  class << self
+
+    def create_strategy(*args)
+      strategy, *strategy_args = args
+      orm_strategy(strategy).new(*strategy_args)
+    end
+
+    def clean_with(*args)
+      strategy = create_strategy(*args)
+      strategy.clean
+      strategy
+    end
+
+    def strategy=(args)
+      strategy, *strategy_args = args
+       if strategy.is_a?(Symbol)
+          @strategy = create_strategy(*args)
+       elsif strategy_args.empty?
+         @strategy = strategy
+       else
+         raise ArgumentError, "You must provide a strategy object, or a symbol for a know strategy along with initialization params."
+       end
+    end
+
+    def orm=(orm_string)
+      @orm = orm_string
+    end
+
+    def start
+      strategy.start
+    end
+
+    def clean
+      strategy.clean
+    end
+
+    private
+
+    def strategy
+      return @strategy if @strategy
+      raise NoStrategySetError, "Please set a strategy with DatabaseCleaner.strategy=."
+    end
+
+    def orm_strategy(strategy)
+      require "database_cleaner/#{orm}/#{strategy}"
+      orm_module.const_get(strategy.to_s.capitalize)
+    rescue LoadError => e
+      raise UnknownStrategySpecified, "The '#{strategy}' strategy does not exist for the #{orm} ORM!  Available strategies: #{orm_module.available_strategies.join(', ')}"
+    end
+
+
+    def orm
+      @orm ||=begin
+                 if defined? ::ActiveRecord
+                  'active_record'
+                elsif defined? ::DataMapper
+                  'data_mapper'
+                else
+                  raise NoORMDetected, "No known ORM was detected!  Is ActiveRecord or DataMapper loaded?"
+                end
+              end
+    end
+
+
+    def orm_module
+      case orm
+      when 'active_record'
+        DatabaseCleaner::ActiveRecord
+      when 'data_mapper'
+        DatabaseCleaner::DataMapper
+      end
+    end
+
+  end
+
+end

data/lib/database_cleaner/cucumber.rb

@@ -0,0 +1,8 @@
+
+Before do
+  DatabaseCleaner.start
+end
+
+After do
+  DatabaseCleaner.clean
+end

data/lib/database_cleaner/data_mapper/transaction.rb

@@ -0,0 +1,6 @@
+module DatabaseCleaner::DataMapper
+  class Transaction
+
+  end
+
+end

data/spec/database_cleaner/active_record/truncation_spec.rb

@@ -0,0 +1,66 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+require 'database_cleaner/active_record/truncation'
+require 'active_record'
+module ActiveRecord
+  module ConnectionAdapters
+    [MysqlAdapter, SQLite3Adapter].each do |adapter|
+      describe adapter, "#truncate_table" do
+        it "should truncate the table"
+      end
+    end
+  end
+end
+
+module DatabaseCleaner
+  module ActiveRecord
+    
+    describe Truncation do
+      before(:each) do
+        @connection = mock('connection')
+        @connection.stub!(:disable_referential_integrity).and_yield
+        ::ActiveRecord::Base.stub!(:connection).and_return(@connection)
+      end
+
+      it "should truncate all tables except for schema_migrations" do
+        @connection.stub!(:tables).and_return(%w[schema_migrations widgets dogs])
+
+        @connection.should_receive(:truncate_table).with('widgets')
+        @connection.should_receive(:truncate_table).with('dogs')
+        @connection.should_not_receive(:truncate_table).with('schema_migrations')
+
+        Truncation.new.clean
+      end
+
+      it "should only truncate the tables specified in the :only option when provided" do
+        @connection.stub!(:tables).and_return(%w[schema_migrations widgets dogs])
+
+        @connection.should_receive(:truncate_table).with('widgets')
+        @connection.should_not_receive(:truncate_table).with('dogs')
+
+        Truncation.new(:only => ['widgets']).clean
+      end
+
+      it "should not truncate the tables specified in the :except option" do
+        @connection.stub!(:tables).and_return(%w[schema_migrations widgets dogs])
+
+        @connection.should_receive(:truncate_table).with('dogs')
+        @connection.should_not_receive(:truncate_table).with('widgets')
+
+        Truncation.new(:except => ['widgets']).clean
+      end
+
+      it "should raise an error when :only and :except options are used" do
+        running { 
+          Truncation.new(:except => ['widgets'], :only => ['widgets'])
+        }.should raise_error(ArgumentError)
+      end
+
+      it "should raise an error when invalid options are provided" do
+        running { Truncation.new(:foo => 'bar') }.should raise_error(ArgumentError)
+      end
+
+
+    end
+
+  end
+end

data/spec/database_cleaner/configuration_spec.rb

@@ -0,0 +1,101 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require 'database_cleaner/active_record/transaction'
+require 'database_cleaner/data_mapper/transaction'
+
+describe DatabaseCleaner do
+
+  # These examples muck around with the constants for autodetection so we need to clean up....
+  before(:all) do
+    TempAR = ActiveRecord unless defined?(TempAR)
+    # need to add one for each ORM that we load in the spec helper...
+  end
+  after(:all) do
+    Object.send(:remove_const, 'ActiveRecord') if defined?(::ActiveRecord) #want to make sure we have the real one...
+    ActiveRecord = TempAR
+  end
+
+  before(:each) do
+    DatabaseCleaner::ActiveRecord::Transaction.stub!(:new).and_return(@strategy = mock('strategy'))
+    Object.const_set('ActiveRecord', "just mocking out the constant here...") unless defined?(::ActiveRecord)
+    DatabaseCleaner.strategy = nil
+    DatabaseCleaner.orm = nil
+  end
+
+  describe ".create_strategy" do
+    it "should initialize and return the appropirate strategy" do
+      DatabaseCleaner::ActiveRecord::Transaction.should_receive(:new).with('options' => 'hash')
+      result = DatabaseCleaner.create_strategy(:transaction, {'options' => 'hash'})
+
+      result.should == @strategy
+    end
+  end
+
+  describe ".clean_with" do
+    it "should initialize the appropirate strategy and clean with it" do
+      DatabaseCleaner::ActiveRecord::Transaction.should_receive(:new).with('options' => 'hash')
+      @strategy.should_receive(:clean)
+
+      DatabaseCleaner.clean_with(:transaction, 'options' => 'hash')
+    end
+  end
+
+  describe ".strategy=" do
+    it "should initialize the appropirate strategy based on the ORM adapter detected" do
+      DatabaseCleaner::ActiveRecord::Transaction.should_receive(:new).with('options' => 'hash')
+      DatabaseCleaner.strategy = :transaction, {'options' => 'hash'}
+
+      Object.send(:remove_const, 'ActiveRecord')
+      Object.const_set('DataMapper', "just mocking out the constant here...")
+      DatabaseCleaner.orm = nil
+
+      DatabaseCleaner::DataMapper::Transaction.should_receive(:new).with(no_args)
+      DatabaseCleaner.strategy = :transaction
+    end
+
+    it "should raise an error when no ORM is detected" do
+      Object.send(:remove_const, 'ActiveRecord') if defined?(::ActiveRecord)
+      Object.send(:remove_const, 'DataMapper') if defined?(::DataMapper)
+
+      running { DatabaseCleaner.strategy = :transaction }.should raise_error(DatabaseCleaner::NoORMDetected)
+    end
+
+    it "should use the strategy version of the ORM specified with #orm=" do
+      DatabaseCleaner.orm = 'data_mapper'
+      DatabaseCleaner::DataMapper::Transaction.should_receive(:new)
+
+      DatabaseCleaner.strategy = :transaction
+    end
+
+    it "should raise an error when multiple args is passed in and the first is not a symbol" do
+      running { DatabaseCleaner.strategy=Object.new, {:foo => 'bar'} }.should raise_error(ArgumentError)
+    end
+
+    it "should raise an error when the specified strategy is not found" do
+      running { DatabaseCleaner.strategy = :foo }.should raise_error(DatabaseCleaner::UnknownStrategySpecified)
+    end
+
+    it "should allow any object to be set as the strategy" do
+      mock_strategy = mock('strategy')
+      running { DatabaseCleaner.strategy = mock_strategy }.should_not raise_error
+    end
+
+  end
+
+
+    %w[start clean].each do |strategy_method|
+      describe ".#{strategy_method}" do
+        it "should be delgated to the strategy set with strategy=" do
+          DatabaseCleaner.strategy = :transaction
+
+          @strategy.should_receive(strategy_method)
+
+          DatabaseCleaner.send(strategy_method)
+        end
+
+        it "should raise en error when no strategy has been set" do
+          running { DatabaseCleaner.send(strategy_method) }.should raise_error(DatabaseCleaner::NoStrategySetError)
+        end
+      end
+    end
+
+end

data/spec/spec.opts

@@ -0,0 +1,6 @@
+--colour
+--format nested
+--loadby
+mtime
+--reverse
+--backtrace

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+require 'rubygems'
+require 'spec'
+require 'activerecord'
+
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require 'database_cleaner'
+
+Spec::Runner.configure do |config|
+  
+end
+
+alias running lambda

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification 
+name: bmabey-database_cleaner
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Ben Mabey
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-04 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: TODO
+email: ben@benmabey.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.textile
+- VERSION.yml
+- examples/features
+- examples/features/example.feature
+- examples/features/step_definitions
+- examples/features/step_definitions/example_steps.rb
+- examples/features/support
+- examples/features/support/env.rb
+- examples/lib
+- examples/lib/activerecord.rb
+- lib/database_cleaner
+- lib/database_cleaner/active_record
+- lib/database_cleaner/active_record/transaction.rb
+- lib/database_cleaner/active_record/truncation.rb
+- lib/database_cleaner/configuration.rb
+- lib/database_cleaner/cucumber.rb
+- lib/database_cleaner/data_mapper
+- lib/database_cleaner/data_mapper/transaction.rb
+- lib/database_cleaner.rb
+- features/cleaning.feature
+- features/step_definitions
+- features/step_definitions/database_cleaner_steps.rb
+- features/support
+- features/support/env.rb
+- spec/database_cleaner
+- spec/database_cleaner/active_record
+- spec/database_cleaner/active_record/truncation_spec.rb
+- spec/database_cleaner/configuration_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- Rakefile
+- cucumber.yml
+has_rdoc: true
+homepage: http://github.com/bmabey/database_cleaner
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: TODO
+test_files: []
+