paper_trail 1.4.3 → 1.4.4

data/README.md

@@ -14,7 +14,8 @@ PaperTrail lets you track changes to your models' data.  It's good for auditing
 * Automatically records who was responsible if your controller has a `current_user` method.
 * Allows you to set who is responsible at model-level (useful for migrations).
 * Allows you to store arbitrary metadata with each version (useful for filtering versions).
-* Can be turned off/on (useful for migrations).
+* Can be turned off/on per class (useful for migrations).
+* Can be turned off/on globally (useful for testing).
 * No configuration necessary.
 * Stores everything in a single database table (generates migration for you).
 * Thoroughly tested.
@@ -171,11 +172,9 @@ Why would you do this?  In this example, `author_id` is an attribute of `Article
 
 ## Turning PaperTrail Off/On
 
-Sometimes you don't want to store changes.  Perhaps you are only interested in changes made
-by your users and don't need to store changes you make yourself in, say, a migration.
+Sometimes you don't want to store changes.  Perhaps you are only interested in changes made by your users and don't need to store changes you make yourself in, say, a migration -- or when testing your application.
 
-If you are about change some widgets and you don't want a paper trail of your changes, you can
-turn PaperTrail off like this:
+If you are about change some widgets and you don't want a paper trail of your changes, you can turn PaperTrail off like this:
 
     >> Widget.paper_trail_off
 
@@ -183,6 +182,38 @@ And on again like this:
 
     >> Widget.paper_trail_on
 
+You can also disable PaperTrail for all models:
+
+    >> PaperTrail.enabled = false
+
+For example, you might want to disable PaperTrail in your Rails application's test environment to speed up your tests.  This will do it:
+
+    # in config/environments/test.rb
+    config.after_initialize do
+      PaperTrail.enabled = false
+    end
+
+If you disable PaperTrail in your test environment but want to enable it for specific tests, you can add a helper like this to your test helper:
+
+    # in test/test_helper.rb
+    def with_versioning
+      was_enabled = PaperTrail.enabled?
+      PaperTrail.enabled = true
+      begin
+        yield
+      ensure
+        PaperTrail.enabled = was_enabled
+      end
+    end
+
+And then use it in your tests like this:
+
+    test "something that needs versioning" do
+      with_versioning do
+        # your test
+      end
+    end
+
 
 ## Installation
 

data/VERSION

@@ -1 +1 @@
-1.4.3
+1.4.4

data/lib/paper_trail.rb

@@ -1,4 +1,5 @@
 require 'yaml'
+require 'paper_trail/config'
 require 'paper_trail/has_paper_trail'
 require 'paper_trail/version'
 
@@ -8,6 +9,23 @@ module PaperTrail
     base.before_filter :set_whodunnit
   end
 
+  # Returns PaperTrail's configuration object.
+  def self.config
+    @@config ||= PaperTrail::Config.instance
+  end
+
+  # Switches PaperTrail on or off.
+  def self.enabled=(value)
+    PaperTrail.config.enabled = value
+  end
+
+  # Returns `true` if PaperTrail is on, `false` otherwise.
+  # PaperTrail is enabled by default.
+  def self.enabled?
+    !!PaperTrail.config.enabled
+  end
+
+  # Returns who is reponsible for any changes that occur.
   def self.whodunnit
     Thread.current[:whodunnit]
   end

data/lib/paper_trail/config.rb

@@ -0,0 +1,11 @@
+module PaperTrail
+  class Config
+    include Singleton
+    attr_accessor :enabled
+ 
+    def initialize
+      # Indicates whether PaperTrail is on or off.
+      @enabled = true
+    end
+  end
+end

data/lib/paper_trail/has_paper_trail.rb

@@ -20,6 +20,8 @@ module PaperTrail
       cattr_accessor :meta
       self.meta = options[:meta] || {}
 
+      # Indicates whether or not PaperTrail is active for this class.
+      # This is independent of whether PaperTrail is globally enabled or disabled.
       cattr_accessor :paper_trail_active
       self.paper_trail_active = true
 
@@ -30,10 +32,12 @@ module PaperTrail
       after_destroy :record_destroy
     end
 
+    # Switches PaperTrail off for this class.
     def paper_trail_off
       self.paper_trail_active = false
     end
 
+    # Switches PaperTrail on for this class.
     def paper_trail_on
       self.paper_trail_active = true
     end
@@ -42,13 +46,13 @@ module PaperTrail
 
   module InstanceMethods
     def record_create
-      if self.class.paper_trail_active
+      if switched_on?
         versions.create merge_metadata(:event => 'create', :whodunnit => PaperTrail.whodunnit)
       end
     end
 
     def record_update
-      if changed_and_we_care? and self.class.paper_trail_active
+      if switched_on? && changed_and_we_care?
         versions.build merge_metadata(:event     => 'update',
                                       :object    => object_to_string(previous_version),
                                       :whodunnit => PaperTrail.whodunnit)
@@ -56,7 +60,7 @@ module PaperTrail
     end
 
     def record_destroy
-      if self.class.paper_trail_active
+      if switched_on?
         versions.create merge_metadata(:event     => 'destroy',
                                        :object    => object_to_string(previous_version),
                                        :whodunnit => PaperTrail.whodunnit)
@@ -100,6 +104,12 @@ module PaperTrail
     def changed_and_we_care?
       changed? and !(changed - self.class.ignore).empty?
     end
+
+    # Returns `true` if PaperTrail is globally enabled and active for this class,
+    # `false` otherwise.
+    def switched_on?
+      PaperTrail.enabled? && self.class.paper_trail_active
+    end
   end
 
 end

data/paper_trail.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{paper_trail}
-  s.version = "1.4.3"
+  s.version = "1.4.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andy Stewart"]
@@ -26,6 +26,7 @@ Gem::Specification.new do |s|
      "init.rb",
      "install.rb",
      "lib/paper_trail.rb",
+     "lib/paper_trail/config.rb",
      "lib/paper_trail/has_paper_trail.rb",
      "lib/paper_trail/version.rb",
      "paper_trail.gemspec",

data/test/paper_trail_model_test.rb

@@ -214,9 +214,7 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
     end
 
     should 'handle datetimes' do
-      # Is there a better way to test equality of two datetimes?
-      format = '%a, %d %b %Y %H:%M:%S %z' # :rfc822
-      assert_equal @date_time.utc.strftime(format), @previous.a_datetime.utc.strftime(format)
+      assert_equal @date_time.to_time.utc, @previous.a_datetime.to_time.utc
     end
 
     should 'handle times' do
@@ -245,15 +243,14 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
       end
 
       should 'restore all forward-compatible attributes' do
-        format = '%a, %d %b %Y %H:%M:%S %z' # :rfc822
-        assert_equal    'Warble',                        @last.reify.name
-        assert_equal    'The quick brown fox',           @last.reify.a_text
-        assert_equal    42,                              @last.reify.an_integer
-        assert_in_delta 153.01,                          @last.reify.a_float,   0.001
-        assert_in_delta 2.71828,                         @last.reify.a_decimal, 0.00001
-        assert_equal    @date_time.utc.strftime(format), @last.reify.a_datetime.utc.strftime(format)
-        assert_equal    @time,                           @last.reify.a_time
-        assert_equal    @date,                           @last.reify.a_date
+        assert_equal    'Warble',               @last.reify.name
+        assert_equal    'The quick brown fox',  @last.reify.a_text
+        assert_equal    42,                     @last.reify.an_integer
+        assert_in_delta 153.01,                 @last.reify.a_float,   0.001
+        assert_in_delta 2.71828,                @last.reify.a_decimal, 0.00001
+        assert_equal    @date_time.to_time.utc, @last.reify.a_datetime.to_time.utc
+        assert_equal    @time,                  @last.reify.a_time
+        assert_equal    @date,                  @last.reify.a_date
         assert          @last.reify.a_boolean
       end
     end
@@ -263,6 +260,23 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
   context 'A record' do
     setup { @widget = Widget.create :name => 'Zaphod' }
 
+    context 'with PaperTrail globally disabled' do
+      setup do
+        PaperTrail.enabled = false
+        @count = @widget.versions.length
+      end
+
+      teardown { PaperTrail.enabled = true }
+
+      context 'when updated' do
+        setup { @widget.update_attributes :name => 'Beeblebrox' }
+
+        should 'not add to its trail' do
+          assert_equal @count, @widget.versions.length
+        end
+      end
+    end
+
     context 'with its paper trail turned off' do
       setup do
         Widget.paper_trail_off
@@ -486,4 +500,5 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
     end
   end
 
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: paper_trail
 version: !ruby/object:Gem::Version 
-  version: 1.4.3
+  version: 1.4.4
 platform: ruby
 authors: 
 - Andy Stewart
@@ -33,6 +33,7 @@ files:
 - init.rb
 - install.rb
 - lib/paper_trail.rb
+- lib/paper_trail/config.rb
 - lib/paper_trail/has_paper_trail.rb
 - lib/paper_trail/version.rb
 - paper_trail.gemspec