verdict 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e5d867e9231108358536850b04548a9a43594d79
-  data.tar.gz: 272e5fb808e0083732fd5516660812ce92ade4c9
+  metadata.gz: 5ae06081f05919820bf8606d93ea3b673dfaf8a7
+  data.tar.gz: da4b5f7de2203ecb7c5a99d1f3140b7e596dac1d
 SHA512:
-  metadata.gz: 4883a16667083e18a41955708c0624abf6caa0360df42b7a58968b528a4a04cef3aee013733f4e046ce37994b437834a14182429324c454313f3061e68cf6767
-  data.tar.gz: a62aba796b913ca660d039881149edfa5cbda21f240683b9fe66e28441058e4f0ce6e0c49dcd2e7af02f224005824d91c5b72731963cda6f6e3f52871c56402d
+  metadata.gz: d0b692f5c3bd768152e9e09d09ff0ede4eaa01788fd452f762531d8682660a197211b5c3f9e49dc988344d776f7f57c86978d6715a351c4605db9d521ca79dae
+  data.tar.gz: 4ae1d2cd72f869b3b423427791a37fc8316e7d68462f6f051f42631fc208fbc59ee988cdc770974a8efec506f5d5e89f49eb4dd73514232f3951a595c1190c55

data/.travis.yml

@@ -3,12 +3,11 @@ cache: bundler
 before_install: gem update bundler
 script: bundle exec rake
 rvm:
-  - 1.9.3
-  - 2.0.0
-  - 2.1.1
+  - 2.0
+  - 2.1
+  - 2.3.3
   - ruby-head
-  - rbx-2
-  - jruby-19mode
+  - jruby
 matrix:
   allow_failures:
     - rvm: ruby-head

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+## v0.6.0
+**This version has breaking changes**
+
+### Verdict::Experiment
+* replaced following public methods that took a `subject_identifier` with an equivalent method which takes a `subject`
+
+| old method                                                      | new method                               |
+| --------------------------------------------------------------- | ---------------------------------------- |
+| `lookup_assignment_for_identifier(subject_identifier)`          | `lookup(subject)`                        |
+| `assign_manually_by_identifier(subject_identifier, group)`      | `assign_manually(subject, group)`        |
+| `disqualify_manually_by_identifier(subject_identifier)`         | `disqualify_manually(subject)`           |
+| `remove_subject_assignment_by_identifier(subject_identifier)`   | `remove_subject_assignment(subject)`     |
+| `fetch_assignment(subject_identifier)`                          | `lookup(subject)`                        |
+
+* Changed the following methods to take a `subject` instead of `subject_identifier`
+ * `subject_assignment(subject, group, originally_created_at = nil, temporary = false)`
+ * `subject_conversion(subject, goal, created_at = Time.now.utc)`
+
+#### Improved Testability
+`Verdict::Experiment#subject_qualifies?(subject, context = nil)` is now public, so it's easier to test
+the qualification logic for your experiments.
+
+### Verdict::BaseStorage
+* `BaseStorage`'s public methods now take a `subject`, instead of a `subject_identifier`. They fetch the `subject_identifier` using the `Experiment#subject_identifier(subject)` method. Existing storages **will still work normally**.
+* The basic `#get`,`#set`, and `#remove` methods are now protected.
+
+### Verdict::Assignment
+* `#initialize` now takes a `subject` instead of a `subject_identifier`, the new signature is `initialize(experiment, subject, group, originally_created_at, temporary = false)`
+
+### Verdict::Conversion
+* `#initialize` now takes a `subject` instead of a `subject_identifier`, the new signature is `initialize(experiment, subject, goal, created_at = Time.now.utc)`
+
+### Rake Tasks
+* In order to use the included helper Rake Tasks, you must implement `fetch_subject(subject_identifier)` in `Experiment`.
+
+### Unsupported Ruby Versions
+Support has been removed for the following Ruby versions:
+- 1.9.X
+- Rubinius

data/README.md

@@ -76,13 +76,14 @@ You can set up storage for your experiment by calling the `storage` method with
 an object that responds to the following methods:
 
 * `store_assignment(assignment)`
-* `retrieve_assignment(experiment, subject_identifier)`
-* `remove_assignment(experiment, subject_identifier)`
+* `retrieve_assignment(experiment, subject)`
+* `remove_assignment(experiment, subject)`
 * `retrieve_start_timestamp(experiment)`
 * `store_start_timestamp(experiment, timestamp)`
 
-Regarding the method signatures above, `experiment` is the Experiment instance, `subject_identifier` is a string that uniquely identifies the subject, and `assignment` is a `Verdict::Assignment` instance.
+Regarding the method signatures above, `experiment` is the Experiment instance, `subject` is the Subject instance, and `assignment` is a `Verdict::Assignment` instance.
 
+The `subject` instance will be identified internally by its `subject_identifier`
 By default it will use `subject.id.to_s` as `subject_identifier`, but you can change that by overriding `def subject_identifier(subject)` on the experiment.
 
 Storage providers simply store subject assignments and require quick lookups of subject identifiers. They allow for complex (high CPU) assignments, and for assignments that might not always put the same subject in the same group by storing the assignment for later use.

data/lib/verdict/assignment.rb

@@ -1,19 +1,15 @@
 class Verdict::Assignment
-  attr_reader :experiment, :subject_identifier, :group, :created_at
+  attr_reader :experiment, :subject, :group, :created_at
 
-  def initialize(experiment, subject_identifier, group, originally_created_at, temporary = false)
+  def initialize(experiment, subject, group, originally_created_at, temporary = false)
     @experiment         = experiment
-    @subject_identifier = subject_identifier
+    @subject            = subject
     @group              = group
     @first              = originally_created_at.nil? || experiment.manual_assignment_timestamps?
     @created_at         = originally_created_at || Time.now.utc
     @temporary          = temporary
   end
 
-  def subject
-    @subject ||= experiment.fetch_subject(subject_identifier)
-  end
-
   def qualified?
     !group.nil?
   end
@@ -27,20 +23,24 @@ class Verdict::Assignment
   end
 
   def returning
-    self.class.new(@experiment, @subject_identifier, @group, @created_at)
+    self.class.new(@experiment, @subject, @group, @created_at)
   end
 
   def returning?
     @first.nil?
   end
 
+  def subject_identifier
+    experiment.retrieve_subject_identifier(subject)
+  end
+
   def handle
     qualified? ? group.handle : nil
   end
 
   def to_sym
     qualified? ? group.to_sym : nil
-  end  
+  end
 
   def as_json(options = {})
     {

data/lib/verdict/conversion.rb

@@ -1,20 +1,20 @@
 class Verdict::Conversion
 
-  attr_reader :experiment, :subject_identifier, :goal, :created_at
+  attr_reader :experiment, :subject, :goal, :created_at
 
-  def initialize(experiment, subject_identifier, goal, created_at = Time.now.utc)
+  def initialize(experiment, subject, goal, created_at = Time.now.utc)
     @experiment = experiment
-    @subject_identifier = subject_identifier
+    @subject = subject
     @goal = goal
     @created_at = created_at
   end
 
-  def subject
-    experiment.fetch_subject(subject_identifier)
+  def subject_identifier
+    experiment.retrieve_subject_identifier(subject)
   end
 
   def assignment
-    experiment.fetch_assignment(subject_identifier)
+    experiment.lookup(subject)
   end
 
   def as_json(options = {})

data/lib/verdict/experiment.rb

@@ -93,17 +93,17 @@ class Verdict::Experiment
     segmenter.groups.keys
   end
 
-  def subject_assignment(subject_identifier, group, originally_created_at = nil, temporary = false)
-    Verdict::Assignment.new(self, subject_identifier, group, originally_created_at, temporary)
+  def subject_assignment(subject, group, originally_created_at = nil, temporary = false)
+    Verdict::Assignment.new(self, subject, group, originally_created_at, temporary)
   end
 
-  def subject_conversion(subject_identifier, goal, created_at = Time.now.utc)
-    Verdict::Conversion.new(self, subject_identifier, goal, created_at)
+  def subject_conversion(subject, goal, created_at = Time.now.utc)
+    Verdict::Conversion.new(self, subject, goal, created_at)
   end
 
   def convert(subject, goal)
     identifier = retrieve_subject_identifier(subject)
-    conversion = subject_conversion(identifier, goal)
+    conversion = subject_conversion(subject, goal)
     event_logger.log_conversion(conversion)
     segmenter.conversion_feedback(identifier, subject, conversion)
     conversion
@@ -121,22 +121,17 @@ class Verdict::Experiment
 
     store_assignment(assignment)
   rescue Verdict::StorageError
-    subject_assignment(identifier, nil, nil)
+    nil_assignment(subject)
   rescue Verdict::EmptySubjectIdentifier
     if disqualify_empty_identifier?
-      subject_assignment(identifier, nil, nil)
+      nil_assignment(subject)
     else
       raise
     end
   end
 
   def assign_manually(subject, group)
-    identifier = retrieve_subject_identifier(subject)
-    assign_manually_by_identifier(identifier, group)
-  end
-
-  def assign_manually_by_identifier(subject_identifier, group)
-    assignment = subject_assignment(subject_identifier, group)
+    assignment = subject_assignment(subject, group)
     if !assignment.qualified? && !store_unqualified?
       raise Verdict::Error, "Unqualified subject assignments are not stored for this experiment, so manual disqualification is impossible. Consider setting :store_unqualified to true for this experiment."
     end
@@ -149,10 +144,6 @@ class Verdict::Experiment
     assign_manually(subject, nil)
   end
 
-  def disqualify_manually_by_identifier(subject_identifier)
-    assign_manually_by_identifier(subject_identifier, nil)
-  end    
-
   def store_assignment(assignment)
     @storage.store_assignment(assignment) if should_store_assignment?(assignment)
     event_logger.log_assignment(assignment)
@@ -160,11 +151,7 @@ class Verdict::Experiment
   end
 
   def remove_subject_assignment(subject)
-    remove_subject_assignment_by_identifier(retrieve_subject_identifier(subject))
-  end
-
-  def remove_subject_assignment_by_identifier(subject_identifier)
-    @storage.remove_assignment(self, subject_identifier)
+    @storage.remove_assignment(self, subject)
   end
 
   def switch(subject, context = nil)
@@ -172,11 +159,7 @@ class Verdict::Experiment
   end
 
   def lookup(subject)
-    lookup_assignment_for_identifier(retrieve_subject_identifier(subject))
-  end
-
-  def lookup_assignment_for_identifier(subject_identifier)
-    fetch_assignment(subject_identifier)
+    @storage.retrieve_assignment(self, subject)
   end
 
   def retrieve_subject_identifier(subject)
@@ -212,17 +195,18 @@ class Verdict::Experiment
   end
 
   def fetch_subject(subject_identifier)
-    raise NotImplementedError, "Fetching subjects based in identifier is not implemented for eperiment @{handle.inspect}."
-  end
-
-  def fetch_assignment(subject_identifier)
-    @storage.retrieve_assignment(self, subject_identifier)
+    raise NotImplementedError, "Fetching subjects based in identifier is not implemented for experiment @{handle.inspect}."
   end
 
   def disqualify_empty_identifier?
     @disqualify_empty_identifier
   end
 
+  def subject_qualifies?(subject, context = nil)
+    ensure_experiment_has_started
+    everybody_qualifies? || @qualifier.call(subject, context)
+  end
+
   protected
 
   def default_options
@@ -234,24 +218,24 @@ class Verdict::Experiment
   end
 
   def assignment_with_unqualified_persistence(subject_identifier, subject, context)
-    previous_assignment = fetch_assignment(subject_identifier)
+    previous_assignment = lookup(subject)
     return previous_assignment unless previous_assignment.nil?
     if subject_qualifies?(subject, context)
       group = segmenter.assign(subject_identifier, subject, context)
-      subject_assignment(subject_identifier, group, nil, group.nil?)
+      subject_assignment(subject, group, nil, group.nil?)
     else
-      subject_assignment(subject_identifier, nil, nil)
+      nil_assignment(subject)
     end
   end
 
   def assignment_without_unqualified_persistence(subject_identifier, subject, context)
     if subject_qualifies?(subject, context)
-      previous_assignment = fetch_assignment(subject_identifier)
+      previous_assignment = lookup(subject)
       return previous_assignment unless previous_assignment.nil?
       group = segmenter.assign(subject_identifier, subject, context)
-      subject_assignment(subject_identifier, group, nil, group.nil?)
+      subject_assignment(subject, group, nil, group.nil?)
     else
-      subject_assignment(subject_identifier, nil, nil)
+      nil_assignment(subject)
     end
   end
 
@@ -259,11 +243,6 @@ class Verdict::Experiment
     subject.respond_to?(:id) ? subject.id : subject.to_s
   end
 
-  def subject_qualifies?(subject, context = nil)
-    ensure_experiment_has_started
-    everybody_qualifies? || @qualifier.call(subject, context)
-  end
-
   def set_start_timestamp
     @storage.store_start_timestamp(self, started_now = Time.now.utc)
     started_now
@@ -274,4 +253,8 @@ class Verdict::Experiment
   rescue Verdict::StorageError
     @started_at ||= Time.now.utc
   end
+
+  def nil_assignment(subject)
+    subject_assignment(subject, nil, nil)
+  end
 end

data/lib/verdict/storage/base_storage.rb

@@ -15,11 +15,12 @@ module Verdict
       # Should do a fast lookup of an assignment of the subject for the given experiment.
       # - Should return nil if not found in store
       # - Should return an Assignment instance otherwise.
-      def retrieve_assignment(experiment, subject_identifier)
+      def retrieve_assignment(experiment, subject)
+        subject_identifier = experiment.retrieve_subject_identifier(subject)
         if value = get(experiment.handle.to_s, "assignment_#{subject_identifier}")
           hash = JSON.parse(value)
           experiment.subject_assignment(
-            subject_identifier,
+            subject,
             experiment.group(hash['group']),
             Time.xmlschema(hash['created_at'])
           )
@@ -27,7 +28,8 @@ module Verdict
       end
 
       # Should remove the subject from storage, so it will be reassigned later.
-      def remove_assignment(experiment, subject_identifier)
+      def remove_assignment(experiment, subject)
+        subject_identifier = experiment.retrieve_subject_identifier(subject)
         remove(experiment.handle.to_s, "assignment_#{subject_identifier}")
       end
 
@@ -43,7 +45,7 @@ module Verdict
         set(experiment.handle.to_s, 'started_at', timestamp.utc.strftime('%FT%TZ'))
       end
 
-
+      protected
       # Retrieves a key in a given scope from storage.
       # - The scope and key are both provided as string.
       # - Should return a string value if the key is found in the scope, nil otherwise.

data/lib/verdict/tasks.rake

@@ -27,6 +27,10 @@ module Verdict
     def self.subject_identifier
       Verdict::Rake.require_env('subject')
     end
+
+    def self.subject
+      experiment.fetch_subject(subject_identifier)
+    end
   end
 end
 
@@ -46,8 +50,9 @@ namespace :verdict do
   task :lookup_assignment => 'environment' do
     experiment         = Verdict::Rake.experiment
     subject_identifier = Verdict::Rake.subject_identifier
+    subject            = Verdict::Rake.subject
 
-    assignment = experiment.lookup_assignment_for_identifier(subject_identifier)
+    assignment = experiment.lookup(subject)
     if assignment.nil?
       Verdict::Rake.stdout.puts "Subject `#{subject_identifier}` is not assigned to experiment `#{experiment.handle}` yet."
     elsif assignment.qualified?
@@ -62,8 +67,9 @@ namespace :verdict do
     experiment         = Verdict::Rake.experiment
     group              = Verdict::Rake.group
     subject_identifier = Verdict::Rake.subject_identifier
+    subject            = Verdict::Rake.subject
 
-    experiment.assign_manually_by_identifier(Verdict::Rake.require_env('subject'), group)
+    experiment.assign_manually(subject, group)
     Verdict::Rake.stdout.puts "Subject `#{subject_identifier}` has been assigned to group `#{group.handle}` of experiment `#{experiment.handle}`."
   end
 
@@ -71,8 +77,9 @@ namespace :verdict do
   task :disqualify_manually => 'environment' do
     experiment         = Verdict::Rake.experiment
     subject_identifier = Verdict::Rake.subject_identifier
+    subject            = Verdict::Rake.subject
 
-    experiment.disqualify_manually_by_identifier(subject_identifier)
+    experiment.disqualify_manually(subject)
     Verdict::Rake.stdout.puts "Subject `#{subject_identifier}` has been disqualified from experiment `#{experiment.handle}`."
   end
 
@@ -80,8 +87,9 @@ namespace :verdict do
   task :remove_assignment => 'environment' do
     experiment         = Verdict::Rake.experiment
     subject_identifier = Verdict::Rake.subject_identifier
+    subject            = Verdict::Rake.subject
 
-    experiment.remove_subject_assignment_by_identifier(subject_identifier)
+    experiment.remove_subject_assignment(subject)
     Verdict::Rake.stdout.puts "Removed assignment of subject with identifier `#{subject_identifier}`."
     Verdict::Rake.stdout.puts "The subject will be reasigned when it encounters the experiment `#{experiment.handle}` again."
   end

data/lib/verdict/version.rb

@@ -1,3 +1,3 @@
 module Verdict
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/test/assignment_test.rb

@@ -28,13 +28,12 @@ class AssignmentTest < Minitest::Test
     assert_kind_of Time, assignment.created_at
   end
 
-  def test_subject_lookup
-    assignment = Verdict::Assignment.new(@experiment, 'test_subject_id', nil, Time.now.utc)
-    assert_raises(NotImplementedError) { assignment.subject }
+  def test_subject_identifier_lookup
+    klass = Struct.new(:id)
+    subject = klass.new(123)
 
-    @experiment.expects(:fetch_subject).with('test_subject_id').returns(subject = mock('subject'))
-    assignment = Verdict::Assignment.new(@experiment, 'test_subject_id', nil, Time.now.utc)
-    assert_equal subject, assignment.subject
+    assignment = Verdict::Assignment.new(@experiment, subject, nil, Time.now.utc)
+    assert_equal '123', assignment.subject_identifier
   end
 
   def test_triple_equals

data/test/conversion_test.rb

@@ -9,13 +9,12 @@ class ConversionTest < Minitest::Test
     end
   end
 
-  def test_subject_lookup
-    conversion = Verdict::Conversion.new(@experiment, 'test_subject_id', :test_goal)
-    assert_raises(NotImplementedError) { conversion.subject }
+  def test_subject_identifier_lookup
+    klass = Struct.new(:id)
+    subject = klass.new(123)
 
-    @experiment.expects(:fetch_subject).with('test_subject_id').returns(subject = mock('subject'))
-    conversion = Verdict::Conversion.new(@experiment, 'test_subject_id', :test_goal)
-    assert_equal subject, conversion.subject
+    conversion = Verdict::Conversion.new(@experiment, subject, :test_goal)
+    assert_equal '123', conversion.subject_identifier
   end
 
   def test_assignment_lookup

data/test/rake_tasks_test.rb

@@ -3,12 +3,19 @@ require 'stringio'
 
 class RakeTasksTest < Minitest::Test
 
+  TestSubjectClass = Struct.new(:id)
+  class TestExperiment < Verdict::Experiment
+    def fetch_subject(subject_identifier)
+      TestSubjectClass.new(subject_identifier.to_i)
+    end
+  end
+
   def setup
     require 'rake' unless defined?(Rake)
     Rake::Task.define_task(:environment) 
     Rake.application.rake_require('verdict/tasks')
-    
-    @experiment = Verdict::Experiment.define(:rake, store_unqualified: true) do
+
+    @experiment = TestExperiment.define(:rake, store_unqualified: true) do
       groups do
         group :a, 50
         group :b, 50

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: verdict
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Shopify
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-01 00:00:00.000000000 Z
+date: 2017-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -90,6 +90,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE
 - README.md
@@ -154,7 +155,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.3
+rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
 summary: A library to centrally define experiments for your application, and collect