happybara 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f07111257fd0128b45efe622094b7cbadb1904e2
+  data.tar.gz: d9dd81e7fe06f279ae1590f17ae5513ba686e0c7
+SHA512:
+  metadata.gz: ceae202a3842453f47586a01e7a5818e26f3b96e7da9a226d162edee0153f8a6ef7a6eab40c4216fc8c20dafbc1d4edfeb90e52f2ca47ee0c75d712cfdac8db1
+  data.tar.gz: 84b24d10b0b2af0a9a4f1583b99d4cefe71e7ff17067c6464078487266f376994a97d8fccc76479e0653ced15288b68335d0593b0f1ff9d9199d0856d8587c2f

data/lib/happybara.rb

@@ -0,0 +1,9 @@
+require_relative './happybara/agent'
+require_relative './happybara/callbacks'
+require_relative './happybara/executor'
+require_relative './happybara/serializer'
+require_relative './happybara/synchronizer'
+require_relative './happybara/version'
+
+module Happybara
+end

data/lib/happybara/agent.rb

@@ -0,0 +1,117 @@
+require 'colorize'
+require 'singleton'
+require_relative './callbacks'
+require_relative './serializer'
+require_relative './synchronizer'
+require_relative './registry'
+
+module Happybara
+  class Agent
+    include Callbacks
+
+    attr_accessor :grace_timeout
+
+    # Create a new Agent instance and configure it.
+    #
+    # @yield [Happybara::Agent] instance
+    #        The new agent instance. The block will evaluated in this instance's
+    #        scope so you can call methods like #on and #before() globally.
+    #
+    # @return [Happybara::Agent]
+    def self.create(&block)
+      Happybara::Agent.new.tap do |instance|
+        instance.instance_exec do
+          block[self]
+        end
+      end
+    end
+
+    def initialize(serializer: Serializer.new)
+      @serializer = serializer
+      @reflections = {}
+      @mutex = Synchronizer.new({
+        on_abrupt_termination: ->() {
+          run_callbacks(:abrupt_termination)
+          run_after_example
+        },
+
+        on_forced_release: ->() {
+          run_callbacks(:forced_release)
+          run_after_example
+        },
+
+        on_race_condition: ->() {
+          run_callbacks(:race_condition)
+        }
+      })
+    end
+
+    # Bind the Agent to a websocket to start a testing session.
+    #
+    # @param [Websocket] socket
+    # @param [Object] actor
+    #        An instance of an object that will be receiving the RPC calls. Any
+    #        `eval` RPCs will be evaluated in this object's context. If you're
+    #        using Tubesock and hijacking a Rails controller, you can pass the
+    #        controller itself as an actor, then you also have access to
+    #        ApplicationController methods and helpers as RPCs.
+    #
+    # @return [NilClass]
+    def bind(socket, actor)
+      @mutex.lock(socket: socket, timeout: grace_timeout) do
+        executor = Executor.new(actor: actor, socket: socket, serializer: @serializer)
+        executor.run_before_example = method(:run_before_example)
+        executor.run_after_example = method(:run_after_example)
+        executor.run_around_command = method(:run_around_command)
+
+        socket.onopen do
+          puts "Happybara: client connected.".green
+        end
+
+        socket.onmessage do |payload|
+          executor.handle_message(payload)
+        end
+
+        socket.onclose do
+          puts "Happybara: client disconnected.".green
+        end
+      end
+
+      nil
+    end
+
+    def on_forced_release(&callback)
+      on(:forced_release, &callback)
+    end
+
+    def on_abrupt_termination(&callback)
+      on(:abrupt_termination, &callback)
+    end
+
+    def on_race_condition(&callback)
+      on(:race_condition, &callback)
+    end
+
+    private
+
+    def run_before_example
+      run_callbacks(:before_each)
+    end
+
+    def run_after_example
+      run_callbacks(:after_each)
+      @mutex.release
+    end
+
+    def run_around_command(message, &block)
+      # TODO: support nested procs.. ?
+      callback = callbacks[:around_command] && callbacks[:around_command].first
+
+      if callback
+        callback.call(message, block)
+      else
+        block.call
+      end
+    end
+  end
+end

data/lib/happybara/callbacks.rb

@@ -0,0 +1,49 @@
+module Happybara
+  module Callbacks
+    def before(stage, &callback)
+      case stage.to_sym
+      when :each
+        on(:before_each, &callback)
+      when :all
+        Rails.configuration.after_initialize(&callback)
+      else
+        fail "Unknown :before stage '#{stage}'"
+      end
+    end
+
+    def after(stage, &callback)
+      case stage.to_sym
+      when :each
+        on(:after_each, &callback)
+      else
+        fail "Unknown :after stage '#{stage}'"
+      end
+    end
+
+    def around(stage, &callback)
+      case stage.to_sym
+      when :command
+        on(:around_command, &callback)
+      else
+        fail "Unknown :around stage '#{stage}'"
+      end
+    end
+
+    def on(event, &handler)
+      callbacks[event.to_sym] ||= []
+      callbacks[event.to_sym] << handler
+    end
+
+    protected
+
+    def callbacks
+      @callbacks ||= {}
+    end
+
+    def run_callbacks(event)
+      callbacks.fetch(event).each do |callback|
+        callback.call
+      end
+    end
+  end
+end

data/lib/happybara/executor.rb

@@ -0,0 +1,133 @@
+module Happybara
+  class Executor
+    attr_accessor :run_before_example, :run_after_example, :run_around_command
+
+    def initialize(actor:, socket:, serializer:)
+      @actor = actor
+      @socket = socket
+      @serializer = serializer
+      @registry = Registry.new
+    end
+
+    def handle_message(payload)
+      message = @serializer.deserialize payload
+      respond = method(:respond_to_message).curry[message['id']]
+
+      case message['type']
+      when 'SETUP'
+        handle_setup(message, &respond)
+      when 'RPC'
+        handle_rpc(message, &respond)
+      when 'EVAL'
+        handle_eval(message, &respond)
+      when 'QUERY'
+        handle_query(message, &respond)
+      when 'REFLECT'
+        handle_reflect(message, &respond)
+      when 'TEARDOWN'
+        handle_teardown(message, &respond)
+      else
+        fail "unknown message type #{message['type']}"
+      end
+    rescue StandardError => e
+      puts "#{'=' * 80}\nHandler error!\n#{'-' * 80}"
+      puts e.message
+      puts e.backtrace
+
+      respond['error', { details: e.message, backtrace: e.backtrace }]
+    end
+
+    private
+
+    def respond_to_message(message_id, type, data)
+      @socket.send_data({
+        id: message_id,
+        type: type,
+        data: data
+      }.to_json)
+    end
+
+    def handle_setup(message, &respond)
+      run_before_example[]
+
+      respond['SETUP_RESPONSE', @serializer.serialize_value(true)]
+    end
+
+    def handle_query(message, &respond)
+      @registry.open!(message['data']['klass_name'])
+
+      klass = message['data']['klass_name'].constantize
+      klass.public_instance_methods(true)
+        .sort
+        .map(&:to_s)
+        .reject { |s| s[0] =~ /[\W|_]/ }
+        .tap do |visible_instance_methods|
+          respond['QUERY_RESPONSE', @serializer.serialize({
+            instance_methods: visible_instance_methods
+          })]
+        end
+    end
+
+    def handle_rpc(message, &respond)
+      method_name = message['data']['procedure']
+      method_args = message['data']['payload'] || {}
+      method_opts = message['data']['options'] || {}
+
+      fail "Unknown RPC #{method_name}" unless @actor.respond_to?(method_name)
+
+      result = around_command(message) do
+        @actor.send(message['data']['procedure'], **method_args.symbolize_keys)
+      end
+
+      @registry << result
+
+      respond['RPC_RESPONSE', @serializer.serialize_value(result)]
+    end
+
+    def handle_eval(message, &respond)
+      string = message['data']['string']
+      options = message['data']['options'] || {}
+
+      around_command(message) do
+        result = @actor.instance_eval { eval(string) }
+        @registry << result
+        respond['EVAL_RESPONSE', @serializer.serialize_value(result)]
+      end
+    end
+
+    def handle_reflect(message, &respond)
+      object_id = message['data']['object_id']
+      klass_name = message['data']['klass_name']
+      method_name = message['data']['method']
+      method_args = message['data']['arguments']
+      method_opts = message['data']['options'] || {}
+
+      ref = resolve_reference(message['data'])
+
+      fail "Object #{object_id} of type #{klass_name} could not be reflected" if ref.nil?
+
+      rc = around_command(message) do
+        ref.send(method_name, *method_args)
+      end
+
+      @registry << rc
+
+      respond['REFLECT_RESPONSE', @serializer.serialize_value(rc)]
+    end
+
+    def handle_teardown(message, &respond)
+      @registry.release!
+      run_after_example[]
+
+      respond['TEARDOWN_RESPONSE', @serializer.serialize_value(true)]
+    end
+
+    def around_command(message, &block)
+      run_around_command[message['data'], &block]
+    end
+
+    def resolve_reference(descriptor)
+      @registry[descriptor['object_id']]
+    end
+  end
+end

data/lib/happybara/registry.rb

@@ -0,0 +1,29 @@
+module Happybara
+  class Registry
+    def initialize()
+      @reflections = {}
+    end
+
+    def open!(klass_name)
+      @reflections[klass_name.to_s] = {}
+    end
+
+    def <<(object)
+      self.tap do
+        klass_name = object.class.name.to_s
+
+        if @reflections[klass_name]
+          @reflections[klass_name][object.object_id] = object
+        end
+      end
+    end
+
+    def [](object_id)
+      ObjectSpace._id2ref(object_id) || nil
+    end
+
+    def release!()
+      @reflections.clear
+    end
+  end
+end

data/lib/happybara/serializer.rb

@@ -0,0 +1,39 @@
+module Happybara
+  class Serializer
+    def serialize(result)
+      result.as_json
+    end
+
+    def serialize_value(result)
+      {
+        klass: result.class.name,
+        object_id: result.object_id,
+        value: result.as_json
+      }
+    end
+
+    def serialize_reference(ref)
+      {
+        klass: ref.class.name,
+        object_id: ref.object_id,
+      }
+    end
+
+    def deserialize(payload)
+      JSON.load(payload, ->(datum) {
+        case datum
+        when Hash
+          datum.each_pair do |key, value|
+            if value.is_a?(Hash) && value['$$ref'] == true && value['$$object_id']
+              datum[key] = ObjectSpace._id2ref(value['$$object_id']) || nil
+            end
+          end
+
+          datum
+        else
+          datum
+        end
+      })
+    end
+  end
+end

data/lib/happybara/synchronizer.rb

@@ -0,0 +1,94 @@
+module Happybara
+  class Synchronizer
+    def initialize(
+      on_forced_release:,
+      on_abrupt_termination:,
+      on_race_condition: nil
+    )
+      @on_forced_release = on_forced_release || ->() {}
+      @on_abrupt_termination = on_abrupt_termination || ->() {}
+      @on_race_condition = on_race_condition || ->() {}
+      @mutex = Mutex.new
+    end
+
+    def lock(socket:, timeout: 5.0, frequency: 0.1, &block)
+      socket.onopen do
+        acquire!(timeout: timeout, frequency: frequency, &block)
+      end
+
+      socket.onclose do
+        @on_abrupt_termination[] if @mutex.owned? && @mutex.locked?
+      end
+    end
+
+    def release
+      @mutex.unlock
+    end
+
+    private
+
+    def acquire!(timeout:, frequency:, &block)
+      if @mutex.locked? && !@mutex.owned?
+        fail "
+          The Happybara agent is being accessed by multiple threads. This
+          mode of operation is not currently supported.
+
+          (This most likely indicates that you have multiple client runners
+          communicating with this Rails server concurrently.)
+        "
+      elsif @mutex.locked?
+        @on_race_condition[]
+
+        begin
+          Timer.new(frequency: frequency, timeout: timeout)
+            .until { vacant? }
+            .otherwise { @on_forced_release[] }
+            .start!
+        rescue TimeoutError
+          @on_forced_release[]
+        end
+      end
+
+      @mutex.lock
+
+      yield
+    end
+
+    def vacant?
+      !@mutex.locked?
+    end
+
+    class Timer
+      def initialize(frequency:, timeout:)
+        @frequency = frequency
+        @timeout = timeout
+        @until = nil
+        @otherwise = nil
+      end
+
+      def until(&block)
+        @until = block
+      end
+
+      def otherwise(&block)
+        @otherwise = block
+      end
+
+      def start!
+        elapsed = 0.0
+
+        while !@until[]
+          elapsed += frequency
+
+          if elapsed < timeout
+            sleep frequency
+          elsif @otherwise
+            @otherwise[]
+          else
+            raise TimeoutError.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/happybara/version.rb

@@ -0,0 +1,3 @@
+module Happybara
+  VERSION = '1.0.0'
+end

data/spec/lib/happybara/agent_spec.rb

@@ -0,0 +1,7 @@
+require 'fileutils'
+require 'spec_helper'
+
+describe Happybara::Agent do
+  it 'is constructible' do
+  end
+end

data/spec/lib/happybara/serializer_spec.rb

@@ -0,0 +1,19 @@
+require 'fileutils'
+require 'spec_helper'
+
+describe Happybara::Serializer do
+  describe '#deserialize' do
+    it 'resolves references' do
+      some_object = Object.new
+
+      result = subject.deserialize({
+        foo: {
+          '$$ref': true,
+          '$$object_id': some_object.object_id
+        }
+      }.to_json)
+
+      expect(result['foo']).to be(some_object)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+ENV['RAILS_ENV'] ||= "test"
+
+require 'pry'
+require_relative '../lib/happybara'
+require_relative './support/bootstrap'
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+end

data/spec/support/bootstrap.rb

@@ -0,0 +1,38 @@
+# This dance is necessary to subvert railtie from resolving get_smart's Rails
+# application as the "Rails.application"; we really only need a dummy
+# application that can host some routes, and if this gem was sourced elsewhere
+# we could just define such an application directly but since it's sourced
+# within get_smart, railtie will resolve the root `config.ru` and cause sadness.
+#
+# Be happy, unless you're upgrading Rails and this gets broken. :-)
+
+require 'rails/application'
+require 'rails/configuration'
+require 'rails/railtie'
+require 'active_support'
+
+module Rails
+  class << self
+    attr_writer :app_class, :application
+  end
+end
+
+module Happybara
+  class TestApplication < ::Rails::Application
+    class << self
+      def find_root(*)
+        Pathname.new File.realpath File.expand_path(File.dirname(__FILE__))
+      end
+    end
+  end
+end
+
+require 'rails'
+require 'action_view'
+require 'action_controller'
+
+Happybara::TestApplication.configure do
+  config.eager_load = ENV['COVERAGE'] != '1'
+end
+
+Happybara::TestApplication.initialize!

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: happybara
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ahmad Amireh
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-04-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+description: |
+  Happybara is an integration testing platform providing a webserver in Ruby that
+  accepts connections over a websocket where test clients can dispatch RPCs to
+  Ruby from a different language like JavaScript.
+email:
+- ahmad@amireh.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/happybara.rb
+- lib/happybara/agent.rb
+- lib/happybara/callbacks.rb
+- lib/happybara/executor.rb
+- lib/happybara/registry.rb
+- lib/happybara/serializer.rb
+- lib/happybara/synchronizer.rb
+- lib/happybara/version.rb
+- spec/lib/happybara/agent_spec.rb
+- spec/lib/happybara/serializer_spec.rb
+- spec/spec_helper.rb
+- spec/support/bootstrap.rb
+- spec/support/log/test.log
+homepage: https://github.com/amireh/happybara
+licenses:
+- BSD-3
+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: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: An integration test server using Websockets.
+test_files:
+- spec/lib/happybara/agent_spec.rb
+- spec/lib/happybara/serializer_spec.rb
+- spec/spec_helper.rb
+- spec/support/bootstrap.rb
+- spec/support/log/test.log
+has_rdoc: