dat-science 1.1.0 → 1.2.0

data/README.md

@@ -85,6 +85,19 @@ After creating a subclass, tell `Dat::Science` to instantiate it any time the
 Dat::Science.experiment = MyApp::Experiment
 ```
 
+### Controlling comparison
+
+By default the results of the `candidate` and `control` blocks are compared
+with `==`. Use `comparator` to do something more fancy:
+
+```ruby
+science "loose-comparison" do |e|
+  e.control    { "vmg" }
+  e.candidate  { "VMG" }
+  e.comparator { |a, b| a.downcase == b.downcase }
+end
+```
+
 ### Ramping up experiments
 
 By default the `candidate` block of an experiment will run 100% of the time.
@@ -173,9 +186,32 @@ end
 `context` takes a Symbol-keyed Hash of additional information to publish and
 merges it with the default payload.
 
+#### Keeping it clean
+
+Sometimes the things you're comparing can be huge, and there's no good way
+to do science against something simpler. Use a `cleaner` to publish a
+simple version of a big nasty object graph:
+
+```ruby
+science "huge-results" do |e|
+  e.control   { OldAndBusted.huge_results_for query }
+  e.candidate { NewHotness.huge_results_for query }
+  e.cleaner   { |result| result.count }
+end
+```
+
+The results of the `control` and `candidate` blocks will be run through the
+`cleaner` You could get the same behavior by calling `count` in the blocks,
+but the `cleaner` makes it easier to keep things in sync. The original
+`control` result is still returned.
+
 ## Hacking on science
 
 Be on a Unixy box. Make sure a modern Bundler is available. `script/test` runs
 the unit tests. All development dependencies will be installed automatically if
 they're not available. Dat science happens primarily on Ruby 1.9.3 and 1.8.7,
 but science should be universal.
+
+## Maintainers
+
+[@jbarnette](https://github.com/jbarnette) and [@rick](https://github.com/rick)

data/dat-science.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |gem|
   gem.name          = "dat-science"
-  gem.version       = "1.1.0"
+  gem.version       = "1.2.0"
   gem.authors       = ["John Barnette", "Rick Bradley"]
   gem.email         = ["jbarnette@github.com"]
   gem.description   = "Gradually test, measure, and track refactored code."

data/lib/dat/science/experiment.rb

@@ -13,6 +13,8 @@ module Dat
       # optional `block` if it's provided.
       def initialize(name, &block)
         @candidate  = nil
+        @cleaner    = lambda { |r| r }
+        @comparator = lambda { |a, b| a == b }
         @context    = { :experiment => name }
         @control    = nil
         @name       = name
@@ -27,6 +29,38 @@ module Dat
         @candidate
       end
 
+      # Internal: Run the cleaner on a value.
+      def clean(value)
+        cleaner.call value
+      end
+
+      # Public: Declare a cleaner `block` to scrub the result before it's
+      # published. `block` is called twice, once with the result of
+      # the control behavior and once with the result of the candidate.
+      # Exceptions during cleaning are treated as if they were raised
+      # in a candidate or control behavior block: They're reported as part
+      # of the result.
+      #
+      # Returns `block`.
+      def cleaner(&block)
+        @cleaner = block if block
+        @cleaner
+      end
+
+      # Internal: Run the comparator on two values.
+      def compare(a, b)
+        comparator.call a, b
+      end
+
+      # Public: Declare a comparator `block`. Results are compared with
+      # `==` by default.
+      #
+      # Returns `block`.
+      def comparator(&block)
+        @comparator = block if block
+        @comparator
+      end
+
       # Public: Add a Hash of `payload` data to be included when events are
       # published or returns the current context if `payload` is `nil`.
       def context(payload = nil)
@@ -107,7 +141,7 @@ module Dat
         end
 
         duration = (Time.now - start) * 1000
-        Science::Result.new value, duration, raised
+        Science::Result.new self, value, duration, raised
       end
 
 

data/lib/dat/science/result.rb

@@ -5,18 +5,20 @@ module Dat
     class Result
       attr_reader :duration
       attr_reader :exception
+      attr_reader :experiment
       attr_reader :value
 
-      def initialize(value, duration, exception)
-        @duration  = duration
-        @exception = exception
-        @value     = value
+      def initialize(experiment, value, duration, exception)
+        @duration   = duration
+        @exception  = exception
+        @experiment = experiment
+        @value      = value
       end
 
       def ==(other)
         return false unless other.is_a? Dat::Science::Result
 
-        values_are_equal = other.value == value
+        values_are_equal = experiment.compare(other.value, value)
         both_raised      = other.raised? && raised?
         neither_raised   = !other.raised? && !raised?
 
@@ -33,7 +35,11 @@ module Dat
       end
 
       def payload
-        { :duration => duration, :exception => exception, :value => value }
+        {
+          :duration  => duration,
+          :exception => exception,
+          :value     => experiment.clean(value)
+        }
       end
 
       def raised?

data/test/dat_science_experiment_test.rb

@@ -36,6 +36,41 @@ class DatScienceExperimentTest < MiniTest::Unit::TestCase
     assert_same b, e.candidate
   end
 
+  def test_cleaner
+    e = Experiment.new "foo"
+    e.control   { "bar" }
+    e.candidate { "baz" }
+    e.cleaner   { |value| value.upcase }
+
+    e.run
+
+    event, payload = Experiment.published.first
+
+    assert_equal "BAR", payload[:control][:value]
+    assert_equal "BAZ", payload[:candidate][:value]
+  end
+
+  def test_cleaner_still_returns_unclean_result
+    e = Experiment.new "foo"
+    e.control   { "bar" }
+    e.candidate { "baz" }
+    e.cleaner   { |v| v.upcase }
+
+    assert_equal "bar", e.run
+  end
+
+  def test_comparator
+    e = Experiment.new "foo"
+    e.control { "bar" }
+    e.candidate { "bar" }
+    e.comparator { |a, b| false }
+
+    e.run
+
+    event, payload = Experiment.published.first
+    assert_equal :mismatch, event
+  end
+
   def test_context_default
     e = Experiment.new "foo"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dat-science
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-26 00:00:00.000000000 Z
+date: 2013-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest