Merge branch 'add-observation-diff' into main

Author: geeksam

README.md

@@ -302,6 +302,15 @@ LabTech.summarize_errors "spiffy-search"
 Note that the `summarize_errors` method also takes an optional `:limit` keyword
 argument.
 
+### Storing Diffs
+
+If you're working with complex data, you might not want to recompute the diffs
+from console.  As such, LabTech adds a `.diff` method to the experiment.  If
+you call this with a block, that block will be passed the control and candidate
+for each candidate, and its result will be stored on the `LabTech::Observation`
+record.  (See the "diff-generating behavior" spec in
+`spec/models/lab_tech/experiment_spec.rb` for examples.)
+
 ### A Note About Experimental Design
 
 Scientist supports experiments with more than one candidate at a time, and

app/models/lab_tech/experiment.rb

@@ -71,6 +71,10 @@ def compare_mismatches(limit: nil, width: 100, io: $stdout, &block)
       end
     end
 
+    def diff(&block)
+      @diff_with = block
+    end
+
     def disable
       update_attribute :percent_enabled, 0
     end
@@ -92,7 +96,7 @@ def name=(value) ; write_attribute :name, value ; end
 
     def publish(scientist_result)
       return if Rails.env.test? && !LabTech.publish_results_in_test_mode?
-      LabTech::Result.record_a_science( self, scientist_result )
+      LabTech::Result.record_a_science( self, scientist_result, diff_with: @diff_with )
     end
 
     # I don't encourage the willy-nilly destruction of experimental results...

app/models/lab_tech/result.rb

@@ -22,9 +22,9 @@ class Result < ApplicationRecord
 
     ##### CLASS METHODS #####
 
-    def self.record_a_science( experiment, scientist_result )
+    def self.record_a_science( experiment, scientist_result, **kwargs )
       self.create!(experiment: experiment) do |result|
-        result.record_a_science scientist_result
+        result.record_a_science scientist_result, **kwargs
       end
     end
 
@@ -50,7 +50,7 @@ def compare_observations(io: $stdout, &block)
       return nil
     end
 
-    def record_a_science(scientist_result)
+    def record_a_science(scientist_result, diff_with: nil)
       unless scientist_result.kind_of?( Scientist::Result )
         raise ArgumentError, "expected a Scientist::Result but got #{scientist_result.class}"
       end
@@ -59,7 +59,8 @@ def record_a_science(scientist_result)
 
       record_observation scientist_result.control
       scientist_result.candidates.each do |candidate|
-        record_observation candidate
+        diff = diff_with&.call(scientist_result.control, candidate)
+        record_observation candidate, diff: diff
       end
 
       record_simple_stats scientist_result
@@ -93,8 +94,9 @@ def increment_experiment_counters
       end
     end
 
-    def record_observation(scientist_observation)
+    def record_observation(scientist_observation, attrs = {})
       self.observations.build do |observation|
+        observation.assign_attributes attrs if attrs.present?
         observation.record_a_science scientist_observation
       end
     end

db/migrate/20210205225332_add_observation_diff.rb

@@ -0,0 +1,6 @@
+class AddObservationDiff < ActiveRecord::Migration[5.1]
+  def change
+    # Give us a place to put diffs generated by, e.g., check_please
+    add_column "lab_tech_observations", "diff", :text
+  end
+end

spec/dummy/db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema.define(version: 2019_08_15_192130) do
+ActiveRecord::Schema.define(version: 20210205225332) do
 
   create_table "lab_tech_experiments", force: :cascade do |t|
     t.string "name"
@@ -31,6 +31,7 @@
     t.text "exception_message"
     t.text "exception_backtrace"
     t.datetime "created_at"
+    t.text "diff"
     t.index ["result_id"], name: "index_lab_tech_observations_by_result_id"
   end
 

spec/models/lab_tech/experiment_spec.rb

@@ -49,7 +49,9 @@ def wtf
       end
 
       it "records the results when the experiment is run" do
-        expect( LabTech::Result ).to receive( :record_a_science ).with( experiment, instance_of(Scientist::Result) )
+        expect( LabTech::Result ).to \
+          receive( :record_a_science ) \
+          .with( experiment, instance_of(Scientist::Result), anything )
 
         LabTech.science "wibble" do |e|
           e.use { :wibble }
@@ -90,6 +92,36 @@ def wtf
         end
       end
 
+      describe "diff-generating behavior" do
+        let(:result) { experiment.results.first }
+
+        specify "if a #diff block IS provided, it is used" do
+          LabTech.science "wibble" do |e|
+            e.use { :control }
+            e.try { :candidate }
+
+            e.diff { |control, candidate| "this is a diff" }
+          end
+
+          result = experiment.results.first
+          expect( result ).to be_kind_of( LabTech::Result )
+
+          expect( result.control          .diff ).to be_blank # because it's the reference against which candidates are diffed
+          expect( result.candidates.first .diff ).to eq( "this is a diff" )
+        end
+
+        specify "if a #diff block IS NOT provided, nothing untoward occurs" do
+          LabTech.science "wibble" do |e|
+            e.use { :control }
+            e.try { :candidate }
+          end
+
+          result = experiment.results.first
+          expect( result.control          .diff ).to be_blank # because it's the reference against which candidates are diffed
+          expect( result.candidates.first .diff ).to be_blank # because no block was provided
+        end
+      end
+
       describe "result counts" do
         specify "when results are equivalent" do
           LabTech.science "wibble" do |e|