elasticsearch-extensions 0.0.4 → 0.0.5

data/README.md

@@ -19,7 +19,125 @@ Display a table with the output of the `_analyze` API:
     require 'elasticsearch/extensions/ansi'
     puts Elasticsearch::Client.new.indices.analyze(text: 'Quick Brown Fox Jumped').to_ansi
 
-[Full documentation](http://rubydoc.info/gems/elasticsearch-extensions/Elasticsearch/Extensions/ANSI).
+[Full documentation](http://rubydoc.info/gems/elasticsearch-extensions/Elasticsearch/Extensions/ANSI)
+
+### Test::Cluster
+
+Allows to programatically start and stop an Elasticsearch cluster suitable for isolating tests.
+
+HTTP service is running on ports `9250-*` by default, and the cluster runs in-memory only.
+
+Start and stop the default cluster:
+
+    require 'elasticsearch/extensions/test/cluster'
+
+    Elasticsearch::Extensions::Test::Cluster.start
+    Elasticsearch::Extensions::Test::Cluster.stop
+
+Start the cluster on specific port, with a specific Elasticsearch version, number of nodes and cluster name:
+
+    require 'elasticsearch/extensions/test/cluster'
+
+    Elasticsearch::Extensions::Test::Cluster.start \
+      cluster_name: "my-testing-cluster",
+      command:      "/usr/local/Cellar/elasticsearch/1.0.0.Beta2/bin/elasticsearch",
+      nodes:        3,
+      port:         9350
+
+    # Starting 3 Elasticsearch nodes.....................
+    # --------------------------------------------------------------------------------
+    # Cluster:            my-testing-cluster
+    # Status:             green
+    # Nodes:              3
+    #                     - node-1 | version: 1.0.0.Beta2, pid: 54469
+    #                     + node-2 | version: 1.0.0.Beta2, pid: 54470
+    #                     - node-3 | version: 1.0.0.Beta2, pid: 54468
+    # => true
+
+
+Stop this cluster:
+
+    require 'elasticsearch/extensions/test/cluster'
+
+    Elasticsearch::Extensions::Test::Cluster.stop \
+      command:      "/usr/local/Cellar/elasticsearch/1.0.0.Beta2/bin/elasticsearch",
+      port:         9350
+
+    # Stopping Elasticsearch nodes... stopped PID 54469. stopped PID 54470. stopped PID 54468.
+    # # => [54469, 54470, 54468]
+
+[Full documentation](http://rubydoc.info/gems/elasticsearch-extensions/Elasticsearch/Extensions/Test/Cluster)
+
+### Test::StartupShutdown
+
+Allows to register `startup` and `shutdown` hooks for Test::Unit, similarly to RSpec's `before(:all)`,
+compatible with the [Test::Unit 2](https://github.com/test-unit/test-unit/blob/master/lib/test/unit/testcase.rb) syntax.
+
+The extension is useful for e.g. starting the testing Elasticsearch cluster before the test suite is executed,
+and stopping it afterwards.
+
+** IMPORTANT NOTE ** You have to register the handler for `shutdown` hook before requiring 'test/unit':
+
+    # File: test_helper.rb
+    at_exit { MyTest.__run_at_exit_hooks }
+    require 'test/unit'
+
+Example of handler registration:
+
+    class MyTest < Test::Unit::TestCase
+      extend Elasticsearch::Extensions::Test::StartupShutdown
+
+      startup  { puts "Suite starting up..." }
+      shutdown { puts "Suite shutting down..." }
+    end
+
+[Full documentation](http://rubydoc.info/gems/elasticsearch-extensions/Elasticsearch/Extensions/Test/StartupShutdown)
+
+Examples in the Elasticsearch gem test suite: [1](https://github.com/elasticsearch/elasticsearch-ruby/blob/master/elasticsearch-transport/test/integration/client_test.rb#L4-L6), [2](https://github.com/elasticsearch/elasticsearch-ruby/blob/master/elasticsearch-transport/test/test_helper.rb#L44)
+
+### Test::Profiling
+
+Allows to define and execute profiling tests within [Shoulda](https://github.com/thoughtbot/shoulda) contexts.
+Measures operations and reports statistics, including code profile.
+
+Let's define a simple profiling test in a `profiling_test.rb` file:
+
+    require 'test/unit'
+    require 'shoulda/context'
+    require 'elasticsearch/extensions/test/profiling'
+
+    class ProfilingTest < Test::Unit::TestCase
+      extend Elasticsearch::Extensions::Test::Profiling
+
+      context "Mathematics" do
+        measure "divide numbers", count: 10_000 do
+          assert_nothing_raised { 1/2 }
+        end
+      end
+
+    end
+
+Let's run it:
+
+    $ QUIET=y ruby profiling_test.rb
+
+    ...
+    ProfilingTest
+
+    -------------------------------------------------------------------------------
+    Context: Mathematics should divide numbers (10000x)
+    mean: 0.03ms | avg: 0.03ms | max: 0.14ms
+    -------------------------------------------------------------------------------
+         PASS (0:00:00.490) test: Mathematics should divide numbers (10000x).
+    ...
+
+When using the `QUIET` option, only the statistics on operation throughput are printed.
+When omitted, the full code profile by [RubyProf](https://github.com/ruby-prof/ruby-prof) is printed.
+
+[Full documentation](http://rubydoc.info/gems/elasticsearch-extensions/Elasticsearch/Extensions/Test/StartupShutdown)
+
+[Example in the Elasticsearch gem](https://github.com/elasticsearch/elasticsearch-ruby/blob/master/elasticsearch-transport/test/profile/client_benchmark_test.rb)
+
 
 ## Installation
 

data/Rakefile

@@ -49,17 +49,15 @@ namespace :test do
     desc "Start Elasticsearch nodes for tests"
     task :start do
       $LOAD_PATH << File.expand_path('../lib', __FILE__) << File.expand_path('../test', __FILE__)
-      require 'elasticsearch/transport'
-      require 'elasticsearch/transport/extensions/test_cluster'
-      Elasticsearch::TestCluster.start
+      require 'elasticsearch/extensions/test/cluster'
+      Elasticsearch::Extensions::Test::Cluster.start
     end
 
     desc "Stop Elasticsearch nodes for tests"
     task :stop do
       $LOAD_PATH << File.expand_path('../lib', __FILE__) << File.expand_path('../test', __FILE__)
-      require 'elasticsearch/transport'
-      require 'elasticsearch/transport/extensions/test_cluster'
-      Elasticsearch::TestCluster.stop
+      require 'elasticsearch/extensions/test/cluster'
+      Elasticsearch::Extensions::Test::Cluster.stop
     end
   end
 end

data/elasticsearch-extensions.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |s|
 
   s.add_dependency "elasticsearch", '~> 0.4'
   s.add_dependency "ansi"
+  s.add_dependency "ruby-prof"
 
   s.add_development_dependency "bundler", "> 1"
   s.add_development_dependency "rake"

data/lib/elasticsearch/extensions/test/cluster.rb

@@ -0,0 +1,251 @@
+require 'timeout'
+require 'net/http'
+require 'uri'
+require 'json'
+require 'ansi'
+
+STDOUT.sync = true
+
+class String
+
+  # Redefine the ANSI method: do not print ANSI when not running in the terminal
+  #
+  def ansi(*args)
+    STDOUT.tty? ? ANSI.ansi(self, *args) : self
+  end
+end
+
+module Elasticsearch
+  module Extensions
+    module Test
+
+      # A convenience Ruby class for starting and stopping a separate testing in-memory cluster,
+      # to not depend on -- and not mess up -- <localhost:9200>.
+      #
+      # @example Start a cluster with default configuration
+      #      require 'elasticsearch/extensions/test/cluster'
+      #      Elasticsearch::Extensions::Test::Cluster.start
+      #
+      # @see Cluster#start Cluster.start
+      # @see Cluster#stop Cluster.stop
+      #
+      module Cluster
+
+        # Starts a cluster
+        #
+        # Launches the specified number of nodes in test-suitable configuration by default
+        # and prints information about the cluster -- unless this specific cluster is running already.
+        #
+        # Use the {Cluster#stop Cluster.stop} command with the same arguments to stop this cluster.
+        #
+        # @option arguments [String]  :command      Elasticsearch command (default: `elasticsearch`).
+        # @option arguments [Integer] :nodes        Number of desired nodes (default: 2).
+        # @option arguments [String]  :cluster_name Cluster name (default: `elasticsearch_test`).
+        # @option arguments [String]  :port         Starting port number; will be auto-incremented (default: 9250).
+        # @option arguments [Integer] :timeout      Timeout when starting the cluster (default: 30).
+        #
+        # You can also use environment variables to set these options.
+        #
+        # @example Start a cluster with default configuration (2 nodes, in-memory, etc)
+        #      Elasticsearch::Extensions::Test::Cluster.start
+        #
+        # @example Start a cluster with a custom configuration
+        #      Elasticsearch::Extensions::Test::Cluster.start \
+        #        cluster_name: 'my-cluster',
+        #        nodes: 3,
+        #        node_name: 'my-node',
+        #        port: 9350
+        #
+        # @example Start a cluster with a different Elasticsearch version
+        #      Elasticsearch::Extensions::Test::Cluster.start \
+        #        command: "/usr/local/Cellar/elasticsearch/1.0.0.Beta2/bin/elasticsearch"
+        #
+        # @return Boolean
+        # @see Cluster#stop Cluster.stop
+        #
+        def start(arguments={})
+          @@number_of_nodes = (ENV['TEST_CLUSTER_NODES'] || arguments[:nodes] || 2).to_i
+
+          arguments[:command]      ||= ENV['TEST_CLUSTER_COMMAND'] || 'elasticsearch'
+          arguments[:port]         ||= (ENV['TEST_CLUSTER_PORT'] || 9250).to_i
+          arguments[:cluster_name] ||= ENV['TEST_CLUSTER_NAME'] || 'elasticsearch_test'
+          arguments[:node_name]    ||= 'node'
+          arguments[:timeout]      ||= 30
+
+          if running? :on => arguments[:port], :as => arguments[:cluster_name]
+            print "[!] Elasticsearch cluster already running".ansi(:red)
+            wait_for_green(arguments[:port], arguments[:timeout])
+            return false
+          end
+
+          print "Starting ".ansi(:faint) +
+                @@number_of_nodes.to_s.ansi(:bold, :faint) +
+                " Elasticsearch nodes..".ansi(:faint)
+
+          @@number_of_nodes.times do |n|
+            n += 1
+            pidfile = File.expand_path("tmp/elasticsearch-#{n}.pid", Dir.pwd)
+            pid = Process.spawn <<-COMMAND
+              #{arguments[:command]} \
+                -D es.foreground=yes \
+                -D es.cluster.name=#{arguments[:cluster_name]} \
+                -D es.node.name=#{arguments[:node_name]}-#{n} \
+                -D es.http.port=#{arguments[:port].to_i + (n-1)} \
+                -D es.gateway.type=none \
+                -D es.index.store.type=memory \
+                -D es.network.host=0.0.0.0 \
+                -D es.discovery.zen.ping.multicast.enabled=true \
+                -D es.pidfile=#{pidfile} \
+                > /dev/null 2>&1
+            COMMAND
+            Process.detach pid
+          end
+
+          wait_for_green(arguments[:port], arguments[:timeout])
+          return true
+        end
+
+        # Stop the cluster.
+        #
+        # Fetches the PID numbers from "Nodes Info" API and terminates matching nodes.
+        #
+        # @example Stop the default cluster
+        #      Elasticsearch::Extensions::Test::Cluster.stop
+        #
+        # @example Stop the cluster reachable on specific port
+        #      Elasticsearch::Extensions::Test::Cluster.stop port: 9350
+        #
+        # @return Boolean
+        # @see Cluster#start Cluster.start
+        #
+        def stop(arguments={})
+          arguments[:port] ||= (ENV['TEST_CLUSTER_PORT'] || 9250).to_i
+
+          nodes = JSON.parse(Net::HTTP.get(URI("http://localhost:#{arguments[:port]}/_cluster/nodes/?process"))) rescue nil
+
+          return false if nodes.nil? or nodes.empty?
+
+          pids  = nodes['nodes'].map { |id, info| info['process']['id'] }
+
+          unless pids.empty?
+            print "Stopping Elasticsearch nodes... ".ansi(:faint)
+            pids.each_with_index do |pid, i|
+              begin
+                print "stopped PID #{pid}. ".ansi(:green) if Process.kill 'KILL', pid
+              rescue Exception => e
+                print "[#{e.class}] PID #{pid} not found. ".ansi(:red)
+              end
+            end
+            puts
+          else
+            false
+          end
+
+          return pids
+        end
+
+        # Returns true when a specific test node is running within the cluster.
+        #
+        # @option arguments [Integer] :on The port on which the node is running.
+        # @option arguments [String]  :as The cluster name.
+        #
+        # @return Boolean
+        #
+        def running?(arguments={})
+          port         = arguments[:on] || (ENV['TEST_CLUSTER_PORT'] || 9250).to_i
+          cluster_name = arguments[:as] ||  ENV['TEST_CLUSTER_NAME'] || 'elasticsearch_test'
+
+          if cluster_health = Timeout::timeout(0.25) { __get_cluster_health(port) } rescue nil
+            return cluster_health['cluster_name']    == cluster_name && \
+                   cluster_health['number_of_nodes'] == @@number_of_nodes
+          end
+          return false
+        end
+
+        # Waits until the cluster is green and prints information
+        #
+        # @example Print the information about the default cluster
+        #     Elasticsearch::Extensions::Test::Cluster.wait_for_green
+        #
+        # @param (see #__wait_for_status)
+        #
+        # @return Boolean
+        #
+        def wait_for_green(port=9250, timeout=60)
+          __wait_for_status('green', port, timeout)
+        end
+
+        # Blocks the process and waits for the cluster to be in a "green" state.
+        #
+        # Prints information about the cluster on STDOUT if the cluster is available.
+        #
+        # @param status  [String]  The status to wait for (yellow, green)
+        # @param port    [Integer] The port on which the cluster is reachable
+        # @param timeout [Integer] The explicit timeout for the operation
+        #
+        # @api private
+        #
+        # @return Boolean
+        #
+        def __wait_for_status(status='green', port=9250, timeout=30)
+          uri = URI("http://localhost:#{port}/_cluster/health?wait_for_status=#{status}")
+
+          Timeout::timeout(timeout) do
+            loop do
+              response = begin
+                JSON.parse(Net::HTTP.get(uri))
+              rescue Exception => e
+                puts e.inspect if ENV['DEBUG']
+                nil
+              end
+
+              if response && response['status'] == status && ( @@number_of_nodes.nil? || @@number_of_nodes == response['number_of_nodes'].to_i  )
+                __print_cluster_info(port) and break
+              end
+
+              print '.'.ansi(:faint)
+              sleep 1
+            end
+          end
+
+          return true
+        end
+
+        # Print information about the cluster on STDOUT
+        #
+        # @api private
+        #
+        def __print_cluster_info(port)
+          health = JSON.parse(Net::HTTP.get(URI("http://localhost:#{port}/_cluster/health")))
+          nodes  = JSON.parse(Net::HTTP.get(URI("http://localhost:#{port}/_cluster/nodes/?process")))
+          master = JSON.parse(Net::HTTP.get(URI("http://localhost:#{port}/_cluster/state")))['master_node']
+
+          puts "\n",
+                ('-'*80).ansi(:faint),
+               'Cluster: '.ljust(20).ansi(:faint) + health['cluster_name'].to_s.ansi(:faint),
+               'Status:  '.ljust(20).ansi(:faint) + health['status'].to_s.ansi(:faint),
+               'Nodes:   '.ljust(20).ansi(:faint) + health['number_of_nodes'].to_s.ansi(:faint)
+
+          nodes['nodes'].each do |id, info|
+            m = id == master ? '+' : '-'
+            puts ''.ljust(20) +
+                 "#{m} #{info['name'].ansi(:bold)} | version: #{info['version']}, pid: #{info['process']['id']}".ansi(:faint)
+          end
+        end
+
+        # Tries to load cluster health information
+        #
+        # @api private
+        #
+        def __get_cluster_health(port=9250)
+          uri = URI("http://localhost:#{port}/_cluster/health")
+          if response = Net::HTTP.get(uri) rescue nil
+            return JSON.parse(response)
+          end
+        end
+
+        extend self
+      end
+    end
+  end
+end

data/lib/elasticsearch/extensions/test/profiling.rb

@@ -0,0 +1,98 @@
+require 'ruby-prof'
+require 'benchmark'
+require 'ansi'
+
+module Elasticsearch
+  module Extensions
+    module Test
+
+      # Allows to define and execute profiling tests within [Shoulda](https://github.com/thoughtbot/shoulda) contexts.
+      #
+      # Measures operations and reports statistics, including code profile.
+      #
+      # Uses the "benchmark" standard library and the "ruby-prof" gem.
+      #
+      #     File: profiling_test.rb
+      #
+      #     require 'test/unit'
+      #     require 'shoulda/context'
+      #     require 'elasticsearch/extensions/test/profiling'
+      #
+      #     class ProfilingTest < Test::Unit::TestCase
+      #       extend Elasticsearch::Extensions::Test::Profiling
+      #
+      #       context "Mathematics" do
+      #         measure "divide numbers", count: 10_000 do
+      #           assert_nothing_raised { 1/2 }
+      #         end
+      #       end
+      #
+      #     end
+      #
+      #     $ QUIET=y ruby profiling_test.rb
+      #
+      #     ...
+      #     ProfilingTest
+      #
+      #     -------------------------------------------------------------------------------
+      #     Context: Mathematics should divide numbers (10000x)
+      #     mean: 0.03ms | avg: 0.03ms | max: 0.14ms
+      #     -------------------------------------------------------------------------------
+      #          PASS (0:00:00.490) test: Mathematics should divide numbers (10000x).
+      #     ...
+      #
+      module Profiling
+
+        # Profiles the passed block of code.
+        #
+        #     measure "divide numbers", count: 10_000 do
+        #      assert_nothing_raised { 1/2 }
+        #     end
+        #
+        # @todo Try to make progress bar not to interfere with tests
+        #
+        def measure(name, options={}, &block)
+          ___          = '-'*ANSI::Terminal.terminal_width
+          test_name    = self.name.split('::').last
+          context_name = self.context(nil) {}.first.parent.name
+          count        = Integer(ENV['COUNT'] || options[:count] || 1_000)
+          ticks        = []
+          # progress   = ANSI::Progressbar.new("#{name} (#{count}x)", count)
+
+          should "#{name} (#{count}x)" do
+            RubyProf.start
+
+            count.times do
+              ticks << Benchmark.realtime { self.instance_eval(&block) }
+              # RubyProf.pause
+              # progress.inc
+              # RubyProf.resume
+            end
+
+            result = RubyProf.stop
+            # progress.finish
+
+            total = result.threads.reduce(0) { |total,info| total += info.total_time; total }
+            mean  = (ticks.sort[(ticks.size/2).round-1])*1000
+            avg   = (ticks.inject {|sum,el| sum += el; sum}.to_f/ticks.size)*1000
+            max   = ticks.max*1000
+
+
+            result.eliminate_methods!([/Integer#times|Benchmark.realtime|ANSI::Code#.*|ANSI::ProgressBar#.*/])
+            printer = RubyProf::FlatPrinter.new(result)
+            # printer = RubyProf::GraphPrinter.new(result)
+
+            puts "\n",
+                 ___,
+                 'Context: ' + ANSI.bold(context_name) + ' should ' + ANSI.bold(name) + " (#{count}x)",
+                 "mean: #{sprintf('%.2f', mean)}ms | " +
+                 "avg: #{sprintf('%.2f',  avg)}ms | " +
+                 "max: #{sprintf('%.2f',  max)}ms",
+                 ___
+            printer.print(STDOUT, {}) unless ENV['QUIET'] || options[:quiet]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elasticsearch/extensions/test/startup_shutdown.rb

@@ -0,0 +1,54 @@
+module Elasticsearch
+  module Extensions
+    module Test
+      # Startup/shutdown support for test suites
+      #
+      # Example:
+      #
+      #     class MyTest < Test::Unit::TestCase
+      #       extend Elasticsearch::Extensions::Test::StartupShutdown
+      #
+      #       startup  { puts "Suite starting up..." }
+      #       shutdown { puts "Suite shutting down..." }
+      #     end
+      #
+      # *** IMPORTANT NOTE: **********************************************************
+      #
+      # You have to register the handler for shutdown before requiring 'test/unit':
+      #
+      #     # File: test_helper.rb
+      #     at_exit { MyTest.__run_at_exit_hooks }
+      #     require 'test/unit'
+      #
+      # The API follows Test::Unit 2.0
+      # <https://github.com/test-unit/test-unit/blob/master/lib/test/unit/testcase.rb>
+      #
+      module StartupShutdown
+        @@started           = false
+        @@shutdown_blocks ||= []
+
+        def startup &block
+          return if started?
+          @@started = true
+          yield block if block_given?
+        end
+
+        def shutdown &block
+          @@shutdown_blocks << block if block_given?
+        end
+
+        def started?
+          !! @@started
+        end
+
+        def __run_at_exit_hooks
+          return unless started?
+          STDERR.puts ANSI.faint("Running at_exit hooks...")
+          puts ANSI.faint('-'*80)
+          @@shutdown_blocks.each { |b| b.call }
+          puts ANSI.faint('-'*80)
+        end
+      end
+    end
+  end
+end

data/lib/elasticsearch/extensions/version.rb

@@ -1,5 +1,5 @@
 module Elasticsearch
   module Extensions
-    VERSION = "0.0.4"
+    VERSION = "0.0.5"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: elasticsearch-extensions
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-07 00:00:00.000000000 Z
+date: 2013-12-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: elasticsearch
@@ -43,6 +43,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby-prof
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -238,6 +254,9 @@ files:
 - lib/elasticsearch/extensions/ansi/actions.rb
 - lib/elasticsearch/extensions/ansi/helpers.rb
 - lib/elasticsearch/extensions/ansi/response.rb
+- lib/elasticsearch/extensions/test/cluster.rb
+- lib/elasticsearch/extensions/test/profiling.rb
+- lib/elasticsearch/extensions/test/startup_shutdown.rb
 - lib/elasticsearch/extensions/version.rb
 - test/ansi/unit/ansi_test.rb
 - test/test_helper.rb