scientist 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 768eab788fd168ba799412e106ec5b386a15c6f020cf6590873245262049481f
-  data.tar.gz: 2dffdf57ed21e9684024cc09920721faf1525d129c4b985957e04b657451942b
+  metadata.gz: b2c73b090777600d31576b815584cba175ba2061ef223b5ec6775038b03828ee
+  data.tar.gz: 0336cebef463c2c7b92246d7124a395f7351a75452071595ec3c7edac63050f8
 SHA512:
-  metadata.gz: 871dbc71c6795365321f2b4265c6c121a11a11dd6a440b3779eb93c4a30737419f573005d100fa8920bcdfa5f77730acf0906f19aaac58d0a4be42c0703f6228
-  data.tar.gz: 52471d998257836b26e3b61a181426e3bab90a12eeaa73999e115edb95116f3730a0547588293ca26676b021eb977bda10cb1c07fcaf5d70d95c36abc0c65742
+  metadata.gz: e97b6ba1d1f6a07d518b8d86b1b60dbfc0a978e3ef77e95490f733e290fcdef7a42c73728b7f17657a379706bfbfb5ff2d8dbc24334fdb0f7847069c46c5629f
+  data.tar.gz: 3c2b414b032e96eebf4fe476078dc170384efaf67622a32f24db44a52b1dec1c0c4da2706151d06a9dbd3e30da1655ad06d4add6db0af25dd9d85f540014452a

data/.travis.yml

@@ -3,11 +3,10 @@ language: ruby
 cache: bundler
 script: script/test
 rvm:
-  - 2.1.10
-  - 2.2.9
-  - 2.3.7
-  - 2.4.4
-  - 2.5.1
+  - 2.3.8
+  - 2.4.5
+  - 2.5.3
+  - 2.6.1
 before_install: gem install bundler
 addons:
  apt:

data/README.md

@@ -206,6 +206,8 @@ class MyExperiment
 end
 ```
 
+Note that the `#clean` method will discard the previous cleaner block if you call it again.  If for some reason you need to access the currently configured cleaner block, `Scientist::Experiment#cleaner` will return the block without further ado.  _(This probably won't come up in normal usage, but comes in handy if you're writing, say, a custom experiment runner that provides default cleaners.)_
+
 ### Ignoring mismatches
 
 During the early stages of an experiment, it's possible that some of your code will always generate a mismatch for reasons you know and understand but haven't yet fixed. Instead of these known cases always showing up as mismatches in your metrics or analysis, you can tell an experiment whether or not to ignore a mismatch using the `ignore` method. You may include more than one block if needed:
@@ -491,6 +493,22 @@ science "various-ways", run: "first-way" do |e|
 end
 ```
 
+#### Providing fake timing data
+
+If you're writing tests that depend on specific timing values, you can provide canned durations using the `fabricate_durations_for_testing_purposes` method, and Scientist will report these in `Scientist::Observation#duration` instead of the actual execution times.
+
+```ruby
+science "absolutely-nothing-suspicious-happening-here" do |e|
+  e.use { ... } # "control"
+  e.try { ... } # "candidate"
+  e.fabricate_durations_for_testing_purposes( "control" => 1.0, "candidate" => 0.5 )
+end
+```
+
+`fabricate_durations_for_testing_purposes` takes a Hash of duration values, keyed by behavior names.  (By default, Scientist uses `"control"` and `"candidate"`, but if you override these as shown in [Trying more than one thing](#trying-more-than-one-thing) or [No control, just candidates](#no-control-just-candidates), use matching names here.)  If a name is not provided, the actual execution time will be reported instead.
+
+_Like `Scientist::Experiment#cleaner`, this probably won't come up in normal usage.  It's here to make it easier to test code that extends Scientist._
+
 ### Without including Scientist
 
 If you need to use Scientist in a place where you aren't able to include the Scientist module, you can call `Scientist.run`:
@@ -504,12 +522,12 @@ end
 
 ## Hacking
 
-Be on a Unixy box. Make sure a modern Bundler is available. `script/test` runs the unit tests. All development dependencies are installed automatically. Scientist requires Ruby 2.1 or newer.
+Be on a Unixy box. Make sure a modern Bundler is available. `script/test` runs the unit tests. All development dependencies are installed automatically. Scientist requires Ruby 2.3 or newer.
 
 ## Alternatives
 
 - [daylerees/scientist](https://github.com/daylerees/scientist) (PHP)
-- [github/scientist.net](https://github.com/github/scientist.net) (.NET)
+- [scientistproject/scientist.net](https://github.com/scientistproject/Scientist.net) (.NET)
 - [joealcorn/laboratory](https://github.com/joealcorn/laboratory) (Python)
 - [rawls238/Scientist4J](https://github.com/rawls238/Scientist4J) (Java)
 - [tomiaijo/scientist](https://github.com/tomiaijo/scientist) (C++)
@@ -523,6 +541,7 @@ Be on a Unixy box. Make sure a modern Bundler is available. `script/test` runs t
 - [calavera/go-scientist](https://github.com/calavera/go-scientist) (Go)
 - [jelmersnoeck/experiment](https://github.com/jelmersnoeck/experiment) (Go)
 - [spoptchev/scientist](https://github.com/spoptchev/scientist) (Kotlin / Java)
+- [junkpiano/scientist](https://github.com/junkpiano/scientist) (Swift)
 
 
 ## Maintainers

data/doc/changelog.md

@@ -1,5 +1,12 @@
 # Changes
 
+## v1.3.0 (2 April 2019)
+
+- New: Drop support for ruby <2.3
+- Fix: Build new strings instead of modifying frozen ones
+- New: Add an accessor for the configured clean block
+- New: Add a hook to use fabricated durations instead of actual timing data.
+
 ## v1.2.0 (5 July 2018)
 
 - New: Use monotonic clock for duration calculations

data/lib/scientist/experiment.rb

@@ -41,10 +41,10 @@ module Scientist::Experiment
     def format_observation(observation)
       observation.name + ":\n" +
       if observation.raised?
-        observation.exception.inspect.prepend("  ") + "\n" +
-          observation.exception.backtrace.map { |line| line.prepend("    ") }.join("\n")
+        lines = observation.exception.backtrace.map { |line| "    #{line}" }.join("\n")
+        "  #{observation.exception.inspect}" + "\n" + lines
       else
-        observation.cleaned_value.inspect.prepend("  ")
+        "  #{observation.cleaned_value.inspect}"
       end
     end
   end
@@ -96,6 +96,13 @@ module Scientist::Experiment
     @_scientist_cleaner = block
   end
 
+  # Accessor for the clean block, if one is available.
+  #
+  # Returns the configured block, or nil.
+  def cleaner
+    @_scientist_cleaner
+  end
+
   # Internal: Clean a value with the configured clean block, or return the value
   # if no clean block is configured.
   #
@@ -213,7 +220,8 @@ module Scientist::Experiment
 
     behaviors.keys.shuffle.each do |key|
       block = behaviors[key]
-      observations << Scientist::Observation.new(key, self, &block)
+      fabricated_duration = @_scientist_fabricated_durations && @_scientist_fabricated_durations[key]
+      observations << Scientist::Observation.new(key, self, fabricated_duration: fabricated_duration, &block)
     end
 
     control = observations.detect { |o| o.name == name }
@@ -290,4 +298,10 @@ module Scientist::Experiment
       !!raise_on_mismatches
     end
   end
+
+  # Provide predefined durations to use instead of actual timing data.
+  # This is here solely as a convenience for developers of libraries that extend Scientist.
+  def fabricate_durations_for_testing_purposes(fabricated_durations = {})
+    @_scientist_fabricated_durations = fabricated_durations
+  end
 end

data/lib/scientist/observation.rb

@@ -23,19 +23,20 @@ class Scientist::Observation
   # The Float seconds elapsed.
   attr_reader :duration
 
-  def initialize(name, experiment, &block)
+  def initialize(name, experiment, fabricated_duration: nil, &block)
     @name       = name
     @experiment = experiment
     @now        = Time.now
 
-    starting = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_second)
+    starting = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_second) unless fabricated_duration
     begin
       @value = block.call
     rescue *RESCUES => e
       @exception = e
     end
 
-    @duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_second) - starting
+    @duration = fabricated_duration ||
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_second) - starting
 
     freeze
   end

data/lib/scientist/version.rb

@@ -1,3 +1,3 @@
 module Scientist
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/scientist.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |gem|
   gem.homepage      = "https://github.com/github/scientist"
   gem.license       = "MIT"
 
-  gem.required_ruby_version = '>= 2.1'
+  gem.required_ruby_version = '>= 2.3'
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = []

data/script/release

@@ -33,7 +33,6 @@ git fetch -t origin
 }
 
 # Tag it and bag it.
-echo TAG $tag
 
-gem push scientist-*.gem && git tag "$tag" # &&
-  # git push origin master && git push origin "$tag"
+gem push scientist-*.gem && git tag "$tag" &&
+  git push origin master && git push origin "$tag"

data/script/test

@@ -4,7 +4,7 @@
 set -e
 
 cd $(dirname "$0")/..
-  script/bootstrap && ruby -I lib \
+  script/bootstrap && bundle exec ruby -I lib \
     -e 'require "bundler/setup"' \
     -e 'require "coveralls"; Coveralls.wear!{ add_filter ".bundle" }' \
     -e 'require "minitest/autorun"' \

data/test/scientist/experiment_test.rb

@@ -239,6 +239,13 @@ describe Scientist::Experiment do
     assert_equal 10, @ex.clean_value(10)
   end
 
+  it "provides the clean block when asked for it, in case subclasses wish to override and provide defaults" do
+    assert_nil @ex.cleaner
+    cleaner = ->(value) { value.upcase }
+    @ex.clean(&cleaner)
+    assert_equal cleaner, @ex.cleaner
+  end
+
   it "calls the configured clean block with a value when configured" do
     @ex.clean do |value|
       value.upcase
@@ -559,4 +566,32 @@ candidate:
       refute before, "before_run should not have run"
     end
   end
+
+  describe "testing hooks for extending code" do
+    it "allows a user to provide fabricated durations for testing purposes" do
+      @ex.use { true }
+      @ex.try { true }
+      @ex.fabricate_durations_for_testing_purposes( "control" => 0.5, "candidate" => 1.0 )
+
+      @ex.run
+
+      cont = @ex.published_result.control
+      cand = @ex.published_result.candidates.first
+      assert_in_delta 0.5, cont.duration, 0.01
+      assert_in_delta 1.0, cand.duration, 0.01
+    end
+
+    it "returns actual durations if fabricated ones are omitted for some blocks" do
+      @ex.use { true }
+      @ex.try { sleep 0.1; true }
+      @ex.fabricate_durations_for_testing_purposes( "control" => 0.5 )
+
+      @ex.run
+
+      cont = @ex.published_result.control
+      cand = @ex.published_result.candidates.first
+      assert_in_delta 0.5, cont.duration, 0.01
+      assert_in_delta 0.1, cand.duration, 0.01
+    end
+  end
 end

data/test/scientist_test.rb

@@ -56,27 +56,29 @@ describe Scientist do
     obj = Object.new
     obj.extend(Scientist)
 
-    result = obj.science "test", run: "first-way" do |e|
-      experiment = e
+    behaviors_executed = []
 
-      e.try("first-way") { true }
-      e.try("second-way") { true }
+    result = obj.science "test", run: "first-way" do |e|
+      e.try("first-way") { behaviors_executed << "first-way" ; true }
+      e.try("second-way") { behaviors_executed << "second-way" ; true }
     end
 
     assert_equal true, result
+    assert_equal [ "first-way" ], behaviors_executed
   end
 
   it "runs control when there is a nil named test" do
     obj = Object.new
     obj.extend(Scientist)
 
-    result = obj.science "test", nil do |e|
-      experiment = e
+    behaviors_executed = []
 
-      e.use { true }
-      e.try("second-way") { true }
+    result = obj.science "test", nil do |e|
+      e.use { behaviors_executed << "control" ; true }
+      e.try("second-way") { behaviors_executed << "second-way" ; true }
     end
 
     assert_equal true, result
+    assert_equal [ "control" ], behaviors_executed
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scientist
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - GitHub Open Source
@@ -12,7 +12,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-07-05 00:00:00.000000000 Z
+date: 2019-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -88,15 +88,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.1'
+      version: '2.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Carefully test, measure, and track refactored code.