once-ler 0.0.1

data/README.md

@@ -0,0 +1,105 @@
+# once-ler
+
+once-ler supercharges your `let`s and `before`s with the performance
+of `before(:all)`. You get the performance of fixtures without all the
+headaches.
+
+## Setup
+
+Add it to your Gemfile
+
+```ruby
+gem "once-ler"
+```
+
+And then in spec_helper.rb (or wherever):
+
+```ruby
+RSpec.configure do |config|
+  config.include Onceler::BasicHelpers
+end
+```
+
+## Basic usage
+
+### before(:once) { ... }
+
+Change a slow `before` to `before(:once)` to speed it up.
+
+### let_once(...) { ... }
+
+Change a slow `let` (or `let!`) to `let_once` to speed it up.
+
+## Ambitious usage
+
+If you're feeling bold, you can automatically speed up all
+`let`s/`before(:each)`s in an example group:
+
+```ruby
+describe "something" do
+  onceler!
+  let(:foo) { ... }    # behaves like let_once
+  before { ... }       # behaves like before(:once)
+  before(:all) { ... } # no change here though
+end
+```
+
+Or even more ambitiously, apply it to all your specs:
+
+```ruby
+RSpec.configure do |c|
+  c.onceler!
+end
+```
+
+## How does it work?
+
+Any `before(:once)`/`let_once` blocks will run just once for the current
+context/describe block, before any of its examples run. Any side effects
+(ivars) and return values will be recorded, and will then be reapplied
+before each spec in the block runs. Once-ler uses nested transactions
+(savepoints) to ensure that specs don't mess with each other's database
+rows.
+
+This can give you a dramatic speedup, since you can minimize the number
+of activerecord callbacks/inserts/updates.
+
+## Caveats
+
+* Your once'd blocks should have no side effects other than database
+  statements, return values, and instance variables.
+* Your return values and instance variables need to be able to handle a
+  Marshal.dump/load round trip.
+* Your once'd blocks' behavior should not depend on side effects of other
+  non-once'd blocks. For example:
+  * a `before(:once)` block should not reference instance variables set by a
+    `before` (but the inverse is fine).
+  * a `let_once` block should not call non-once'd `let`s or `subject`s.
+* Because all `let_once`s will be recorded and replayed (even if not used
+  in a particular example), you should ensure they don't conflict with
+  each other (e.g. unique constraint violations, or one `let_once`
+  mutating the return value of another).
+* Some effort is made to preserve object identity, but just for instance
+  variables and return values, e.g.:
+
+  ```ruby
+    let_once(:user) { User.new }
+    let_once(:users) { [user] }
+
+    before(:once) do
+      @joe = user
+      @also_joe = @joe
+      @joe_ish = [@joe]
+    end
+
+    # within an example:
+    # user == @joe             => true
+    # user.equal? @joe         => true # yay
+    # user == @also_joe        => true
+    # user.equal? @also_joe    => true # yay
+    # user == users[0]         => true
+    # user.equal? users[0]     => false # d'oh
+    # user == @joe_ish[0]      => true
+    # user.equal? @joe_ish[0]  => false # d'oh
+  ```
+

data/lib/once-ler.rb

@@ -0,0 +1 @@
+require 'onceler'

data/lib/onceler.rb

@@ -0,0 +1,5 @@
+require "rspec"
+require "onceler/basic_helpers"
+require "onceler/configuration"
+require "onceler/extensions/active_record"
+

data/lib/onceler/ambitious_helpers.rb

@@ -0,0 +1,39 @@
+module Onceler
+  module AmbitiousHelpers
+    def before_once?(type)
+      super || type == :each || type.nil?
+    end
+
+    def let(name, &block)
+      let_once(name, &block)
+    end
+
+    # TODO NamedSubjectPreventSuper
+    def subject(name = nil, &block)
+      subject_once(name, &block)
+    end
+
+    # remove auto-before'ing of ! methods, since we memoize our own way
+    def let!(name, &block)
+      let(name, &block)
+    end
+
+    def subject!(name = nil, &block)
+      subject(name, &block)
+    end
+
+    # make sure we have access to subsequently added methods when
+    # recording (not just `lets'). note that this really only works
+    # for truly functional methods with no external dependencies. e.g.
+    # methods that add stubs or set instance variables will not work
+    # while recording
+    def method_added(method_name)
+      return if method_name == @current_let_once
+      onceler = onceler(:create)
+      proxy = onceler.helper_proxy ||= new
+      onceler.helper_methods[method_name] ||= Proc.new do |*args|
+        proxy.send method_name, *args
+      end
+    end
+  end
+end

data/lib/onceler/around_all.rb

@@ -0,0 +1,32 @@
+# adapted from https://gist.github.com/myronmarston/2005175
+require 'delegate'
+require 'fiber'
+
+module Onceler
+  module AroundAll
+    class FiberAwareGroup < SimpleDelegator
+      def run_examples
+        Fiber.yield
+      end
+
+      def to_proc
+        proc { run_examples }
+      end
+    end
+
+    def around_all(&block)
+      fibers = []
+      prepend_before(:all) do |group|
+        fiber = Fiber.new(&block)
+        fibers << fiber
+        fiber.resume(FiberAwareGroup.new(group))
+      end
+
+      after(:all) do |group|
+        fiber = fibers.pop
+        fiber.resume if fiber.alive?
+      end
+    end
+  end
+end
+

data/lib/onceler/basic_helpers.rb

@@ -0,0 +1,90 @@
+require "onceler/ambitious_helpers"
+require "onceler/around_all"
+require "onceler/recorder"
+
+module Onceler
+  module BasicHelpers
+    def onceler
+      self.class.onceler
+    end
+
+    def self.included(mod)
+      mod.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      include AroundAll
+
+      def let_once(name, &block)
+        raise "#let or #subject called without a block" if block.nil?
+        onceler(:create)[name] = block
+        @current_let_once = name
+        define_method(name) { onceler[name] }
+      end
+
+      def subject_once(name = nil, &block)
+        name ||= :subject
+        let_once(name, &block)
+        alias_method :subject, name if name != :subject
+      end
+
+      def before_once(&block)
+        onceler(:create) << block
+      end
+
+      def before_once?(type)
+        type == :once
+      end
+
+      def before(*args, &block)
+        if before_once?(args.first)
+          before_once(&block)
+        else
+          super(*args, &block)
+        end
+      end
+
+      def onceler(create_own = false)
+        if create_own
+          @onceler ||= create_onceler!
+        else
+          @onceler || parent_onceler
+        end
+      end
+
+      def create_onceler!
+        add_onceler_hooks!
+        Recorder.new(parent_onceler)
+      end
+
+      private
+
+      def parent_onceler
+        return unless superclass.respond_to?(:onceler)
+        superclass.onceler
+      end
+
+      def add_onceler_hooks!
+        around_all do |group|
+          # TODO: configurable transaction fu (say, if you have multiple
+          # conns)
+          ActiveRecord::Base.transaction(requires_new: true) do
+            group.onceler.record!
+            group.run_examples
+            raise ActiveRecord::Rollback
+          end
+        end
+        # only the outer-most group needs to do this
+        unless parent_onceler
+          register_hook :append, :before, :each do
+            onceler.replay_into!(self)
+          end
+        end
+      end
+
+      def onceler!
+        extend AmbitiousHelpers
+      end
+    end
+  end
+end

data/lib/onceler/blank_tape.rb

@@ -0,0 +1,55 @@
+module Onceler
+  class BlankTape
+    def initialize(modules)
+      modules.each { |mod| extend mod }
+      @__retvals = {}
+      @__retvals_recorded = {} # we might override an inherited one, so we need to differentiate
+    end
+
+    def __prepare_recording(recording)
+      method = recording.name
+      define_singleton_method(method) do
+        if @__retvals_recorded[method]
+          @__retvals[method]
+        else
+          @__retvals_recorded[method] = true
+          @__retvals[method] = __record(recording)
+        end
+      end
+    end
+
+    def __record(recording)
+      instance_eval(&recording.block)
+    end
+
+    def __ivars
+      ivars = instance_variables - [:@__retvals, :@__retvals_recorded]
+      ivars.inject({}) do |hash, key|
+        val = instance_variable_get(key)
+        hash[key] = val
+        hash
+      end
+    end
+
+    def __data
+      [__ivars, @__retvals]
+    end
+
+    def copy(mixins)
+      copy = self.class.new(mixins)
+      copy.copy_from(self)
+      copy
+    end
+
+    def copy_from(other)
+      ivars, @__retvals = Marshal.load(Marshal.dump(other.__data))
+      ivars.each do |key, value|
+        instance_variable_set(key, value)
+      end
+      @__retvals.each do |key, value|
+        define_singleton_method(key) { value }
+      end
+    end
+  end
+end
+

data/lib/onceler/configuration.rb

@@ -0,0 +1,19 @@
+module Onceler
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield configuration
+  end
+
+  class Configuration
+    def modules
+      @modules ||= []
+    end
+
+    def include(mod)
+      modules << mod
+    end
+  end
+end

data/lib/onceler/extensions/active_record.rb

@@ -0,0 +1,3 @@
+module ActiveRecord::TestFixtures
+  def teardown_fixtures; end # we manage it ourselves
+end

data/lib/onceler/recorder.rb

@@ -0,0 +1,127 @@
+require "onceler/blank_tape"
+
+module Onceler
+  class Recorder
+    attr_accessor :tape, :helper_proxy
+
+    def initialize(parent)
+      @parent = parent
+      @recordings = []
+      @named_recordings = []
+    end
+
+    def <<(block)
+      @recordings << Recording.new(block)
+    end
+
+    def []=(name, block)
+      @named_recordings << name
+      @recordings << NamedRecording.new(block, name)
+    end
+
+    def [](name)
+      @retvals[name]
+    end
+
+    def record!
+      @tape = @parent ? @parent.tape.copy(mixins) : BlankTape.new(mixins)
+      proxy_recordable_methods!
+
+      # we don't know the order named recordings will be called (or if
+      # they'll call each other), so prep everything first
+      @recordings.each do |recording|
+        recording.prepare_medium!(@tape)
+      end
+      @recordings.each do |recording|
+        recording.record_onto!(@tape)
+      end
+      @data = Marshal.dump(@tape.__data)
+    end
+
+    def proxy_recordable_methods!
+      # the proxy is used to run non-recordable methods that may be called
+      # by ones are recording. since the former could in turn call more of
+      # the latter, we need to proxy the other way too
+      return unless helper_proxy
+      methods = @named_recordings
+      reverse_proxy = @tape
+      helper_proxy.instance_eval do
+        methods.each do |method|
+          define_singleton_method(method) { reverse_proxy.send(method) }
+        end
+      end
+    end
+
+    def helper_methods
+      @helper_methods ||= {}
+    end
+
+    def mixins
+      mixins = (@parent ? @parent.mixins : Onceler.configuration.modules).dup
+      if methods = @helper_methods
+        mixin = Module.new do
+          methods.each do |key, method|
+            define_method(key, &method)
+          end
+        end
+        mixins.push mixin
+      end
+      mixins
+    end
+
+    def reconsitute_data!
+      @ivars, @retvals = Marshal.load(@data)
+      identity_map = {}
+      reidentify!(@ivars, identity_map)
+      reidentify!(@retvals, identity_map)
+    end
+
+    def reidentify!(hash, identity_map)
+      hash.each do |key, value|
+        if identity_map.key?(value)
+          hash[key] = identity_map[value]
+        else
+          identity_map[value] = value
+        end
+      end
+    end
+
+    def replay_into!(instance)
+      reconsitute_data!
+      @ivars.each do |key, value|
+        instance.instance_variable_set(key, value)
+      end
+    end
+  end
+
+  class Recording
+    attr_reader :block
+
+    def initialize(block)
+      @block = block
+    end
+
+    def prepare_medium!(tape); end
+
+    def record_onto!(tape)
+      tape.__record(self)
+    end
+  end
+
+  class NamedRecording < Recording
+    attr_reader :name
+
+    def initialize(block, name = nil)
+      super(block)
+      @name = name
+    end
+
+    def prepare_medium!(tape)
+      tape.__prepare_recording(self)
+    end
+
+    def record_onto!(tape)
+      tape.send(@name)
+    end
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: once-ler
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Jon Jensen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-06-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2.14'
+description: once-ler supercharges your let's and before's with the performance of
+  before(:all)
+email: jon@instructure.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/once-ler.rb
+- lib/onceler/ambitious_helpers.rb
+- lib/onceler/around_all.rb
+- lib/onceler/basic_helpers.rb
+- lib/onceler/blank_tape.rb
+- lib/onceler/configuration.rb
+- lib/onceler/extensions/active_record.rb
+- lib/onceler/recorder.rb
+- lib/onceler.rb
+homepage: http://github.com/instructure/onceler
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.5
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: rspec supercharger
+test_files: []
+has_rdoc: