vinted-ab 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dbd33f286fd10d67783cfd1faaea45625555ef81
+  data.tar.gz: df941afba5ffb850c9e7f2b6efaef828c54a313a
+SHA512:
+  metadata.gz: 1ab9db9647bd6b49f2aa3cbf85e59673db57dc3a7148ac6f9f5cd4decaf85535676a07d5b77620a59ed1f259b603b4b37bb1269545d7d4cff76f9f68318cd872
+  data.tar.gz: e51da312da7e11e9bdb12d51b69547efa81bc4351ddabc2b1a0006ce9244b9874fe24c0acd9b1bb50103af859aa9bb42ac3475fb24eb12077aa5227d06352355

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2014
+
+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.

data/README.md

@@ -0,0 +1,107 @@
+# ab
+
+## Configuration
+
+For this lib to work, it requires a configuration json, which looks like this:
+
+```json
+{
+    "salt": "534979417dc75a6f6f49146603a5e17e",
+    "bucket_count": 1000,
+    "ab_tests": [
+        {
+            "id": 42,
+            "name": "experiment",
+            "start_at": "2014-05-21T11:06:30+03:00",
+            "end_at": "2014-05-28T11:06:30+03:00",
+            "seed": "aaaa1111",
+            "buckets": [
+                1,
+                2,
+                3,
+                4,
+                5
+            ],
+            "variants": [
+                {
+                    "name": "green_button",
+                    "chance_weight": 1
+                },
+                {
+                    "name": "red_button",
+                    "chance_weight": 2
+                },
+                {
+                    "name": "control",
+                    "chance_weight": 3
+                }
+            ]
+        },
+        {
+            "id": 44,
+            "name": "red_shirts",
+            "start_at": "2014-05-24T11:09:30+03:00",
+            "end_at": "2099-05-24T11:09:30+03:00",
+            "seed": "bbbb4444",
+            "buckets": [
+                4,
+                5,
+                6,
+                7
+            ],
+            "variants": [
+                {
+                    "name": "red_shirt",
+                    "chance_weight": 1
+                },
+                {
+                    "name": "control",
+                    "chance_weight": 1
+                }
+            ]
+        },
+        {
+            "id": 47,
+            "name": "feed",
+            "start_at": "1999-03-31T00:00:00+03:00",
+            "end_at": "2099-03-31T00:00:00+03:00",
+            "seed": "cccc8888",
+            "buckets": "all",
+            "variants": [
+                {
+                    "name": "enabled",
+                    "chance_weight": 1
+                }
+            ]
+        },
+    ]
+}
+```
+
+## Usage
+
+```ruby
+configuration = retrieve_from_svc_abs
+ab = Ab::Experiments.new(configuration, user_id)
+
+# defining callbacks
+Ab::Experiments.before_picking_variant { |experiment| puts 'magic' }
+Ab::Experiments.after_picking_variant { |experiment, variant| puts "#{variant_name}" }
+
+# ab.experiment never returns nil
+# but if you don't belong to any of the buckets, variant will be nil
+case ab.experiment.variant
+when 'red_button'
+  red_button
+when 'green_button'
+  green_button
+else
+  blue_button
+end
+
+# calls #variant underneath
+# #variant caches results, so meta tracking events would not be sent multiple times
+puts 'magic' if ab.experiment.red_button?
+
+render_feed if ab.feed.enabled?
+```

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/ab.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ab/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'vinted-ab'
+  spec.version = Ab::VERSION
+  spec.platform = Gem::Platform::RUBY
+  spec.authors = ['Mindaugas Mozūras', 'Gintaras Sakalauskas']
+  spec.email = ['mindaugas.mozuras@gmail.com', 'gintaras.sakalauskas@gmail.com']
+  spec.homepage = 'https://github.com/vinted/ab'
+  spec.summary = 'AB testing gem used internally by Vinted'
+
+  spec.required_rubygems_version = '>= 1.3.6'
+  spec.license = 'MIT'
+
+  spec.files = `git ls-files`.split($/)
+  spec.test_files = `git ls-files -- {spec}/*`.split("\n")
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'hooks', '~> 0.4.0'
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake', '~> 10.1.0'
+  spec.add_development_dependency 'rspec', '~> 2.14.0'
+end

data/lib/ab.rb

@@ -0,0 +1,7 @@
+require 'hooks'
+require 'ab/version'
+require 'ab/null_experiment'
+require 'ab/variant'
+require 'ab/experiment'
+require 'ab/assigned_experiment'
+require 'ab/experiments'

data/lib/ab/assigned_experiment.rb

@@ -0,0 +1,54 @@
+module Ab
+  class AssignedExperiment
+    include Hooks
+    define_hooks :before_picking_variant, :after_picking_variant
+
+    def initialize(experiment, id)
+      @experiment, @id = experiment, id
+      @experiment.variants.map(&:name).each do |name|
+        define_singleton_method("#{name}?") { name == variant }
+      end
+    end
+
+    def variant
+      @variant ||= begin
+        return unless part_of_experiment?
+        return unless running?
+
+        run_hook :before_picking_variant, @experiment.name
+        picked_variant = @experiment.variants.find { |v| v.accumulated_chance_weight > weight_id }
+
+        result = picked_variant.name if picked_variant
+        run_hook :after_picking_variant, @experiment.name, result
+        result
+      end
+    end
+
+    private
+
+    def part_of_experiment?
+      @experiment.buckets == 'all' || @experiment.buckets.include?(bucket_id)
+    end
+
+    def bucket_id
+      @bucket_id ||= digest(@experiment.salt + @id.to_s) % @experiment.bucket_count
+    end
+
+    def running?
+      now = DateTime.now
+      now.between?(@experiment.start_at, @experiment.end_at)
+    end
+
+    def weight_id
+      @variant_digest ||= digest(@experiment.seed + @id.to_s) % positive_weight_sum
+    end
+
+    def positive_weight_sum
+      @experiment.weight_sum > 0 ? @experiment.weight_sum : 1
+    end
+
+    def digest(string)
+      Digest::SHA256.hexdigest(string).to_i(16)
+    end
+  end
+end

data/lib/ab/experiment.rb

@@ -0,0 +1,36 @@
+module Ab
+  class Experiment < Struct.new(:hash, :salt, :bucket_count)
+    def buckets
+      hash['buckets']
+    end
+
+    def name
+      hash['name']
+    end
+
+    def variants
+      @variants ||= begin
+        accumulated = 0
+        hash['variants'].map do |variant_hash|
+          Variant.new(variant_hash, accumulated += variant_hash['chance_weight'] )
+        end
+      end
+    end
+
+    def seed
+      hash['seed']
+    end
+
+    def start_at
+      @start_at ||= DateTime.parse(hash['start_at'])
+    end
+
+    def end_at
+      @end_at ||= hash['end_at'].nil? ? DateTime.now.next_year : DateTime.parse(hash['end_at'])
+    end
+
+    def weight_sum
+      variants.map(&:chance_weight).inject(:+)
+    end
+  end
+end

data/lib/ab/experiments.rb

@@ -0,0 +1,33 @@
+module Ab
+  class Experiments
+    include Hooks
+    define_hooks :before_picking_variant, :after_picking_variant
+
+    Ab::AssignedExperiment.before_picking_variant do |experiment|
+      Ab::Experiments.run_hook :before_picking_variant, experiment
+    end
+    Ab::AssignedExperiment.after_picking_variant do |experiment, variant|
+      Ab::Experiments.run_hook :after_picking_variant, experiment, variant
+    end
+
+    def initialize(config, id)
+      @assigned_experiments ||= {}
+
+      (config['ab_tests'] || []).each do |experiment|
+        name = experiment['name']
+        define_singleton_method(name) do
+          experiment = Experiment.new(experiment, config['salt'], config['bucket_count'])
+          @assigned_experiments[name] ||= AssignedExperiment.new(experiment, id)
+        end
+      end
+    end
+
+    def method_missing(meth, *args, &block)
+      @null_experiment ||= NullExperiment.new
+    end
+
+    def respond_to?(meth)
+      true
+    end
+  end
+end

data/lib/ab/null_experiment.rb

@@ -0,0 +1,13 @@
+class NullExperiment
+  def variant
+    nil
+  end
+
+  def method_missing(meth, *args, &block)
+    meth.to_s.end_with?('?') ? false : super
+  end
+
+  def respond_to?(meth)
+    meth.to_s.end_with?('?') ? true : super
+  end
+end

data/lib/ab/variant.rb

@@ -0,0 +1,9 @@
+class Variant < Struct.new(:hash, :accumulated_chance_weight)
+  def chance_weight
+    hash['chance_weight']
+  end
+
+  def name
+    hash['name']
+  end
+end

data/lib/ab/version.rb

@@ -0,0 +1,3 @@
+module Ab
+  VERSION = '0.0.1'
+end

data/spec/assigned_experiment_spec.rb

@@ -0,0 +1,89 @@
+require 'spec_helper'
+
+module Ab
+  describe AssignedExperiment do
+    let(:assigned_experiment) { AssignedExperiment.new(experiment, id) }
+    let(:experiment) { Experiment.new(hash, 'e131bfcfcab06c65d633d0266c7e62a4918', 1000) }
+    let(:hash) {
+      {
+        'name' => name,
+        'start_at' => start_at,
+        'end_at' => end_at,
+        'buckets' => buckets,
+        'seed' => seed,
+        'variants' => variants
+      }
+    }
+    let(:id) { 1 }
+    let(:name) { 'feed' }
+    let(:start_at) { DateTime.now.prev_year.to_s }
+    let(:end_at) { DateTime.now.next_year.to_s }
+    let(:seed) { 'cccc8888' }
+    let(:buckets) { 'all' }
+    let(:thousand_variants) { 1.upto(1000).map { |i| AssignedExperiment.new(experiment, i).variant } }
+
+    describe '#variant' do
+      subject { assigned_experiment.variant }
+
+      context 'single variant' do
+        let(:variants) { [{ 'name' => 'enabled', 'chance_weight' => chance_weight }] }
+
+        context 'that is turned off' do
+          let(:chance_weight) { 0 }
+          it { should be_nil }
+        end
+
+        context 'that is turned on with 1' do
+          let(:chance_weight) { 1 }
+          it { should == 'enabled' }
+        end
+
+        context 'that is turned on with 111' do
+          let(:chance_weight) { 111 }
+          it { should == 'enabled' }
+        end
+      end
+
+      context 'single variant with buckets' do
+        let(:buckets) { (1..100) }
+        let(:variants) { [{ 'name' => 'enabled', 'chance_weight' => 1 }] }
+
+        specify 'half the ids fall under one, other under other' do
+          enabled = thousand_variants.select { |variant| variant == 'enabled' }
+          enabled.count.should be_within(20).of(100)
+        end
+      end
+
+      context 'experiment that has not started yet' do
+        let(:start_at) { DateTime.now.next_year.to_s }
+        let(:buckets) { [1, 2, 3] }
+        let(:variants) { [{ 'name' => 'enabled', 'chance_weight' => 1 }] }
+        it { should be_nil }
+      end
+
+      context 'experiment that has already ended' do
+        let(:end_at) { DateTime.now.prev_year.to_s }
+        let(:buckets) { [1, 2, 3] }
+        let(:variants) { [{ 'name' => 'enabled', 'chance_weight' => 1 }] }
+        it { should be_nil }
+      end
+
+      context 'two variants' do
+        let(:name) { 'button' }
+        let(:variants) {
+          [
+            { 'name' => 'red', 'chance_weight' => 1 },
+            { 'name' => 'blue', 'chance_weight' => 1 }
+          ]
+        }
+
+        specify 'half the ids fall under one, other under other' do
+          reds = thousand_variants.select { |variant| variant == 'red' }
+          blues = thousand_variants.select { |variant| variant == 'blue' }
+          reds.count.should be_within(20).of(500)
+          blues.count.should be_within(20).of(500)
+        end
+      end
+    end
+  end
+end

data/spec/experiments_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+
+module Ab
+  describe Experiments do
+    describe '.new' do
+      subject { Experiments.new(config, id) }
+      let(:id) { 1 }
+
+      context 'empty config' do
+        let(:config) { {} }
+
+        specify 'has no public methods' do
+          (subject.public_methods(false) - [:method_missing, :respond_to?]).count.should == 0
+        end
+
+        specify 'does not raise if method is not existant' do
+          expect{ subject.bla_bla_bla }.to_not raise_error
+        end
+      end
+
+      context 'single experiment with single variant' do
+        let(:config) {
+          {
+            'salt' => 'anything',
+            'bucket_count' => 1000,
+            'ab_tests' => [{
+              'name' => 'feed',
+              'variants' => [{ 'name' => 'enabled', 'chance_weight' => 1 }]
+            }]
+          }
+        }
+        its(:feed) { should be_kind_of AssignedExperiment }
+      end
+    end
+  end
+end

data/spec/null_experiment_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+module Ab
+  describe NullExperiment do
+    subject { NullExperiment.new }
+
+    specify 'does not raise for method ending in question mark' do
+      expect{ subject.bla? }.to_not raise_error
+    end
+
+    specify 'raises for method not ending in question mark' do
+      expect{ subject.bla }.to raise_error
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'rspec'
+require 'ab'
+
+RSpec.configure do |config|
+  config.color_enabled = true
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: vinted-ab
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Mindaugas Mozūras
+- Gintaras Sakalauskas
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hooks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 10.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 10.1.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.14.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.14.0
+description: 
+email:
+- mindaugas.mozuras@gmail.com
+- gintaras.sakalauskas@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- ab.gemspec
+- lib/ab.rb
+- lib/ab/assigned_experiment.rb
+- lib/ab/experiment.rb
+- lib/ab/experiments.rb
+- lib/ab/null_experiment.rb
+- lib/ab/variant.rb
+- lib/ab/version.rb
+- spec/assigned_experiment_spec.rb
+- spec/experiments_spec.rb
+- spec/null_experiment_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/vinted/ab
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: AB testing gem used internally by Vinted
+test_files: []