acts_as_audited 1.0.1

data/lib/acts_as_audited.rb

@@ -0,0 +1,265 @@
+# Copyright (c) 2006 Brandon Keepers
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+module CollectiveIdea #:nodoc:
+  module Acts #:nodoc:
+    # Specify this act if you want changes to your model to be saved in an
+    # audit table.  This assumes there is an audits table ready.
+    #
+    #   class User < ActiveRecord::Base
+    #     acts_as_audited
+    #   end
+    #
+    # See <tt>CollectiveIdea::Acts::Audited::ClassMethods#acts_as_audited</tt>
+    # for configuration options
+    module Audited #:nodoc:
+      CALLBACKS = [:audit_create, :audit_update, :audit_destroy]
+
+      def self.included(base) # :nodoc:
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        # == Configuration options
+        #
+        #
+        # * +only+ - Only audit the given attributes
+        # * +except+ - Excludes fields from being saved in the audit log.
+        #   By default, acts_as_audited will audit all but these fields:
+        #
+        #     [self.primary_key, inheritance_column, 'lock_version', 'created_at', 'updated_at']
+        #   You can add to those by passing one or an array of fields to skip.
+        #
+        #     class User < ActiveRecord::Base
+        #       acts_as_audited :except => :password
+        #     end
+        # * +protect+ - If your model uses +attr_protected+, set this to false to prevent Rails from
+        #   raising an error.  If you declare +attr_accessibe+ before calling +acts_as_audited+, it
+        #   will automatically default to false.  You only need to explicitly set this if you are
+        #   calling +attr_accessible+ after.
+        #
+        #     class User < ActiveRecord::Base
+        #       acts_as_audited :protect => false
+        #       attr_accessible :name
+        #     end
+        #
+        def acts_as_audited(options = {})
+          # don't allow multiple calls
+          return if self.included_modules.include?(CollectiveIdea::Acts::Audited::InstanceMethods)
+
+          options = {:protect => accessible_attributes.nil?}.merge(options)
+
+          class_inheritable_reader :non_audited_columns
+          class_inheritable_reader :auditing_enabled
+
+          if options[:only]
+            except = self.column_names - options[:only].flatten.map(&:to_s)
+          else
+            except = [self.primary_key, inheritance_column, 'lock_version', 'created_at', 'updated_at']
+            except |= Array(options[:except]).collect(&:to_s) if options[:except]
+          end
+          write_inheritable_attribute :non_audited_columns, except
+
+          has_many :audits, :as => :auditable, :order => "#{Audit.quoted_table_name}.version"
+          attr_protected :audit_ids if options[:protect]
+          Audit.audited_class_names << self.to_s
+
+          after_create :audit_create_callback
+          before_update :audit_update_callback
+          after_destroy :audit_destroy_callback
+
+          attr_accessor :version
+
+          extend CollectiveIdea::Acts::Audited::SingletonMethods
+          include CollectiveIdea::Acts::Audited::InstanceMethods
+
+          write_inheritable_attribute :auditing_enabled, true
+        end
+      end
+
+      module InstanceMethods
+
+        # Temporarily turns off auditing while saving.
+        def save_without_auditing
+          without_auditing { save }
+        end
+
+        # Executes the block with the auditing callbacks disabled.
+        #
+        #   @foo.without_auditing do
+        #     @foo.save
+        #   end
+        #
+        def without_auditing(&block)
+          self.class.without_auditing(&block)
+        end
+
+        # Gets an array of the revisions available
+        #
+        #   user.revisions.each do |revision|
+        #     user.name
+        #     user.version
+        #   end
+        #
+        def revisions(from_version = 1)
+          audits = self.audits.find(:all, :conditions => ['version >= ?', from_version])
+          return [] if audits.empty?
+          revision = self.audits.find_by_version(from_version).revision
+          Audit.reconstruct_attributes(audits) {|attrs| revision.revision_with(attrs) }
+        end
+
+        # Get a specific revision specified by the version number, or +:previous+
+        def revision(version)
+          revision_with Audit.reconstruct_attributes(audits_to(version))
+        end
+
+        def revision_at(date_or_time)
+          audits = self.audits.find(:all, :conditions => ["created_at <= ?", date_or_time])
+          revision_with Audit.reconstruct_attributes(audits) unless audits.empty?
+        end
+
+        def audited_attributes
+          attributes.except(*non_audited_columns)
+        end
+
+      protected
+
+        def revision_with(attributes)
+          returning self.dup do |revision|
+            revision.send :instance_variable_set, '@attributes', self.attributes_before_type_cast
+            Audit.assign_revision_attributes(revision, attributes)
+
+            # Remove any association proxies so that they will be recreated
+            # and reference the correct object for this revision. The only way
+            # to determine if an instance variable is a proxy object is to
+            # see if it responds to certain methods, as it forwards almost
+            # everything to its target.
+            for ivar in revision.instance_variables
+              proxy = revision.instance_variable_get ivar
+              if !proxy.nil? and proxy.respond_to? :proxy_respond_to?
+                revision.instance_variable_set ivar, nil
+              end
+            end
+          end
+        end
+
+      private
+
+        def audited_changes
+          changed_attributes.except(*non_audited_columns).inject({}) do |changes,(attr, old_value)|
+            changes[attr] = [old_value, self[attr]]
+            changes
+          end
+        end
+
+        def audits_to(version = nil)
+          if version == :previous
+            version = if self.version
+              self.version - 1
+            else
+              previous = audits.find(:first, :offset => 1,
+                :order => "#{Audit.quoted_table_name}.version DESC")
+              previous ? previous.version : 1
+            end
+          end
+          audits.find(:all, :conditions => ['version <= ?', version])
+        end
+
+        def audit_create(user = nil)
+          write_audit(:action => 'create', :changes => audited_attributes, :user => user)
+        end
+
+        def audit_update(user = nil)
+          unless (changes = audited_changes).empty?
+            write_audit(:action => 'update', :changes => changes, :user => user)
+          end
+        end
+
+        def audit_destroy(user = nil)
+          write_audit(:action => 'destroy', :user => user, :changes => audited_attributes)
+        end
+
+        def write_audit(attrs)
+          self.audits.create attrs if auditing_enabled
+        end
+
+        CALLBACKS.each do |attr_name|
+          alias_method "#{attr_name}_callback".to_sym, attr_name
+        end
+
+        def empty_callback #:nodoc:
+        end
+
+      end # InstanceMethods
+
+      module SingletonMethods
+        # Returns an array of columns that are audited.  See non_audited_columns
+        def audited_columns
+          self.columns.select { |c| !non_audited_columns.include?(c.name) }
+        end
+
+        # Executes the block with auditing disabled.
+        #
+        #   Foo.without_auditing do
+        #     @foo.save
+        #   end
+        #
+        def without_auditing(&block)
+          auditing_was_enabled = auditing_enabled
+          disable_auditing
+          returning(block.call) { enable_auditing if auditing_was_enabled }
+        end
+
+        def disable_auditing
+          write_inheritable_attribute :auditing_enabled, false
+        end
+
+        def enable_auditing
+          write_inheritable_attribute :auditing_enabled, true
+        end
+
+        def disable_auditing_callbacks
+          class_eval do
+            CALLBACKS.each do |attr_name|
+              alias_method "#{attr_name}_callback", :empty_callback
+            end
+          end
+        end
+
+        def enable_auditing_callbacks
+          class_eval do
+            CALLBACKS.each do |attr_name|
+              alias_method "#{attr_name}_callback".to_sym, attr_name
+            end
+          end
+        end
+
+        # All audit operations during the block are recorded as being
+        # made by +user+. This is not model specific, the method is a
+        # convenience wrapper around #Audit.as_user.
+        def audit_as( user, &block )
+          Audit.as_user( user, &block )
+        end
+
+      end
+    end
+  end
+end

data/rails/init.rb

@@ -0,0 +1,9 @@
+require 'acts_as_audited/audit'
+require 'acts_as_audited'
+
+ActiveRecord::Base.send :include, CollectiveIdea::Acts::Audited
+
+if defined?(ActionController) and defined?(ActionController::Base)
+  require 'acts_as_audited/audit_sweeper'
+  ActionController::Base.send :include, CollectiveIdea::ActionController::Audited
+end

data/test/acts_as_audited_test.rb

@@ -0,0 +1,365 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+module CollectiveIdea
+  module Acts
+    class AuditedTest < Test::Unit::TestCase
+      should "include instance methods" do
+        User.new.should be_kind_of(CollectiveIdea::Acts::Audited::InstanceMethods)
+      end
+
+      should "extend singleton methods" do
+        User.should be_kind_of(CollectiveIdea::Acts::Audited::SingletonMethods)
+      end
+
+      ['created_at', 'updated_at', 'lock_version', 'id', 'password'].each do |column|
+        should "not audit #{column}" do
+          User.non_audited_columns.should include(column)
+        end
+      end
+
+      should "not save non-audited columns" do
+        create_user.audits.first.changes.keys.any?{|col| ['created_at', 'updated_at', 'password'].include? col}.should be(false)
+      end
+
+      context "on create" do
+        setup { @user = create_user }
+
+        should_change 'Audit.count', :by => 1
+
+        should 'create associated audit' do
+          @user.audits.count.should == 1
+        end
+
+        should "set the action to 'create'" do
+          @user.audits.first.action.should == 'create'
+        end
+
+        should "store all the audited attributes" do
+          @user.audits.first.changes.should == @user.audited_attributes
+        end
+      end
+
+      context "on update" do
+        setup do
+          @user = create_user(:name => 'Brandon')
+        end
+
+        should "save an audit" do
+          lambda { @user.update_attribute(:name, "Someone") }.should change { @user.audits.count }.by(1)
+          lambda { @user.update_attribute(:name, "Someone else") }.should change { @user.audits.count }.by(1)
+        end
+
+        should "not save an audit if the record is not changed" do
+          lambda { @user.save! }.should_not change { Audit.count }
+        end
+
+        should "set the action to 'update'" do
+          @user.update_attributes :name => 'Changed'
+          @user.audits.last.action.should == 'update'
+        end
+
+        should "store the changed attributes" do
+          @user.update_attributes :name => 'Changed'
+          @user.audits.last.changes.should == {'name' => ['Brandon', 'Changed']}
+        end
+
+        # Dirty tracking in Rails 2.0-2.2 had issues with type casting
+        if ActiveRecord::VERSION::STRING >= '2.3'
+          should "not save an audit if the value doesn't change after type casting" do
+            @user.update_attributes! :logins => 0, :activated => true
+            lambda { @user.update_attribute :logins, '0' }.should_not change { Audit.count }
+            lambda { @user.update_attribute :activated, 1 }.should_not change { Audit.count }
+            lambda { @user.update_attribute :activated, '1' }.should_not change { Audit.count }
+          end
+        end
+
+      end
+
+      context "on destroy" do
+        setup do
+          @user = create_user
+        end
+
+        should "save an audit" do
+          lambda { @user.destroy }.should change { Audit.count }.by(1)
+          @user.audits.size.should == 2
+        end
+
+        should "set the action to 'destroy'" do
+          @user.destroy
+          @user.audits.last.action.should == 'destroy'
+        end
+
+        should "store all of the audited attributes" do
+          @user.destroy
+          @user.audits.last.changes.should == @user.audited_attributes
+        end
+
+        should "be able to reconstruct destroyed record without history" do
+          @user.audits.delete_all
+          @user.destroy
+          revision = @user.audits.first.revision
+          revision.name.should == @user.name
+        end
+      end
+
+      context "dirty tracking" do
+        setup do
+          @user = create_user
+        end
+
+        should "not be changed when the record is saved" do
+          u = User.new(:name => 'Brandon')
+          u.changed?.should be(true)
+          u.save
+          u.changed?.should be(false)
+        end
+
+        should "be changed when an attribute has been changed" do
+          @user.name = "Bobby"
+          @user.changed?.should be(true)
+          @user.name_changed?.should be(true)
+          @user.username_changed?.should be(false)
+        end
+
+        # Dirty tracking in Rails 2.0-2.2 had issues with type casting
+        if ActiveRecord::VERSION::STRING >= '2.3'
+          should "not be changed if the value doesn't change after type casting" do
+            @user.update_attributes! :logins => 0, :activated => true
+            @user.logins = '0'
+            @user.changed?.should be(false)
+          end
+        end
+
+      end
+
+      context "revisions" do
+        setup do
+          @user = create_versions
+        end
+
+        should "be an Array of Users" do
+          @user.revisions.should be_kind_of(Array)
+          @user.revisions.each {|version| version.should be_kind_of(User) }
+        end
+
+        should "have one revision for a new record" do
+          create_user.revisions.size.should == 1
+        end
+
+        should "have one revision for each audit" do
+          @user.revisions.size.should == @user.audits.size
+        end
+
+        should "set the attributes for each revision" do
+          u = User.create(:name => 'Brandon', :username => 'brandon')
+          u.update_attributes :name => 'Foobar'
+          u.update_attributes :name => 'Awesome', :username => 'keepers'
+
+          u.revisions.size.should == 3
+
+          u.revisions[0].name.should == 'Brandon'
+          u.revisions[0].username.should == 'brandon'
+
+          u.revisions[1].name.should == 'Foobar'
+          u.revisions[1].username.should == 'brandon'
+
+          u.revisions[2].name.should == 'Awesome'
+          u.revisions[2].username.should == 'keepers'
+        end
+
+        should "access to only recent revisions" do
+          u = User.create(:name => 'Brandon', :username => 'brandon')
+          u.update_attributes :name => 'Foobar'
+          u.update_attributes :name => 'Awesome', :username => 'keepers'
+
+          u.revisions(2).size.should == 2
+
+          u.revisions(2)[0].name.should == 'Foobar'
+          u.revisions(2)[0].username.should == 'brandon'
+
+          u.revisions(2)[1].name.should == 'Awesome'
+          u.revisions(2)[1].username.should == 'keepers'
+        end
+
+        should "be empty if no audits exist" do
+          @user.audits.delete_all
+          @user.revisions.empty?.should be(true)
+        end
+
+        should "ignore attributes that have been deleted" do
+          @user.audits.last.update_attributes :changes => {:old_attribute => 'old value'}
+          lambda { @user.revisions }.should_not raise_error
+        end
+
+      end
+
+      context "revision" do
+        setup do
+          @user = create_versions(5)
+        end
+
+        should "maintain identity" do
+          @user.revision(1).should == @user
+        end
+
+        should "find the given revision" do
+          revision = @user.revision(3)
+          revision.should be_kind_of(User)
+          revision.version.should == 3
+          revision.name.should == 'Foobar 3'
+        end
+
+        should "find the previous revision with :previous" do
+          revision = @user.revision(:previous)
+          revision.version.should == 4
+          revision.should == @user.revision(4)
+        end
+
+        should "be able to get the previous revision repeatedly" do
+          previous = @user.revision(:previous)
+          previous.version.should == 4
+          previous.revision(:previous).version.should == 3
+        end
+        
+        should "be able to set protected attributes" do
+          u = User.create(:name => 'Brandon')
+          u.update_attribute :logins, 1
+          u.update_attribute :logins, 2
+
+          u.revision(3).logins.should == 2
+          u.revision(2).logins.should == 1
+          u.revision(1).logins.should == 0
+        end
+        
+        should "set attributes directly" do
+          u = User.create(:name => '<Joe>')
+          u.revision(1).name.should == '&lt;Joe&gt;'
+        end
+
+        should "set the attributes for each revision" do
+          u = User.create(:name => 'Brandon', :username => 'brandon')
+          u.update_attributes :name => 'Foobar'
+          u.update_attributes :name => 'Awesome', :username => 'keepers'
+
+          u.revision(3).name.should == 'Awesome'
+          u.revision(3).username.should == 'keepers'
+
+          u.revision(2).name.should == 'Foobar'
+          u.revision(2).username.should == 'brandon'
+
+          u.revision(1).name.should == 'Brandon'
+          u.revision(1).username.should == 'brandon'
+        end
+
+        should "not raise an error when no previous audits exist" do
+          @user.audits.destroy_all
+          lambda{ @user.revision(:previous) }.should_not raise_error
+        end
+
+        should "mark revision's attributes as changed" do
+          @user.revision(1).name_changed?.should be(true)
+        end
+
+        should "record new audit when saving revision" do
+          lambda { @user.revision(1).save! }.should change { @user.audits.count }.by(1)
+        end
+
+      end
+
+      context "revision_at" do
+        should "find the latest revision before the given time" do
+          u = create_user
+          Audit.update(u.audits.first.id, :created_at => 1.hour.ago)
+          u.update_attributes :name => 'updated'
+          u.revision_at(2.minutes.ago).version.should == 1
+        end
+
+        should "be nil if given a time before audits" do
+          create_user.revision_at(1.week.ago).should be(nil)
+        end
+
+      end
+
+      context "without auditing" do
+
+        should "not save an audit when calling #save_without_auditing" do
+          lambda {
+            u = User.new(:name => 'Brandon')
+            u.save_without_auditing.should be(true)
+          }.should_not change { Audit.count }
+        end
+
+        should "not save an audit inside of the #without_auditing block" do
+          lambda do
+            User.without_auditing { User.create(:name => 'Brandon') }
+          end.should_not change { Audit.count }
+        end
+
+        should "not save an audit when callbacks are disabled" do
+          begin
+            User.disable_auditing_callbacks
+            lambda { create_user }.should_not change { Audit.count }
+          ensure
+            User.enable_auditing_callbacks
+          end
+        end
+      end
+
+      context "attr_protected and attr_accessible" do
+        class UnprotectedUser < ActiveRecord::Base
+          set_table_name :users
+          acts_as_audited :protect => false
+          attr_accessible :name, :username, :password
+        end
+        should "not raise error when attr_accessible is set and protected is false" do
+          lambda{
+            UnprotectedUser.new(:name => 'NO FAIL!')
+          }.should_not raise_error(RuntimeError)
+        end
+
+        class AccessibleUser < ActiveRecord::Base
+          set_table_name :users
+          attr_accessible :name, :username, :password # declare attr_accessible before calling aaa
+          acts_as_audited
+        end
+        should "not raise an error when attr_accessible is declared before acts_as_audited" do
+          lambda{
+            AccessibleUser.new(:name => 'NO FAIL!')
+          }.should_not raise_error
+        end
+      end
+
+      context "audit as" do
+        setup do
+          @user = User.create :name => 'Testing'
+        end
+
+        should "record user objects" do
+          Company.audit_as( @user ) do
+            company = Company.create :name => 'The auditors'
+            company.name = 'The Auditors'
+            company.save
+
+            company.audits.each do |audit|
+              audit.user.should == @user
+            end
+          end
+        end
+
+        should "record usernames" do
+          Company.audit_as( @user.name ) do
+            company = Company.create :name => 'The auditors'
+            company.name = 'The Auditors, Inc'
+            company.save
+
+            company.audits.each do |audit|
+              audit.username.should == @user.name
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

data/test/audit_sweeper_test.rb

@@ -0,0 +1,29 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+class AuditsController < ActionController::Base
+  audit Company
+  
+  def audit
+    @company = Company.create
+    render :nothing => true
+  end
+  
+private
+  attr_accessor :current_user
+end
+AuditsController.view_paths = [File.dirname(__FILE__)]
+ActionController::Routing::Routes.draw {|m| m.connect ':controller/:action/:id' }
+
+class AuditsControllerTest < ActionController::TestCase
+
+  should "call acts as audited on non audited models" do
+    Company.should be_kind_of(CollectiveIdea::Acts::Audited::SingletonMethods)
+  end
+  
+  should "audit user" do
+    user = @controller.send(:current_user=, create_user)
+    lambda { post :audit }.should change { Audit.count }
+    assigns(:company).audits.last.user.should == user
+  end
+  
+end