wait_for_it 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 348eca90f6ed848d47e98f5e155fdc23d71574f0
-  data.tar.gz: b962f7ff42d548d8d82523c61defc1485166730e
+  metadata.gz: d0f834a28065f71917777d4683074b39c94a23da
+  data.tar.gz: 6d9c2443ce1c46e603da9d8e7a34bbaea979a06a
 SHA512:
-  metadata.gz: 07f41e55079029af4357841f9f11c6fdb410385f6bc09a7544cbeb78470bf0acf0b8f6afc793abe6054c7d7385c319fe8dbc0f3d6273d0b23e6a2199138e0559
-  data.tar.gz: 1c3df44812ce0c82ba8d8dd9bdfdb2fa86583132610dd4d9ce4897d54e2790a82b71e47bf81e865eff1a8254a1ba3e4d25a824e1cdcd6b7db71e9cefa78392b0
+  metadata.gz: abfdd59d18cb4747bb284c5edd0342fc59ccdb623ab61d6bc0920e1259adfa5ba86bf7324848836170f3f27bfc729dfe2648daa2b82d054cb17483aeedf96ee7
+  data.tar.gz: 5d8f53f05f3ff7f186089c3260c29445bfc012cace2195cc3566092c85ba2e34915d9d58f1c826983847fc41769870aca7c216a4cf4a1c69150313adee77bd6f

data/.travis.yml

@@ -1,4 +1,8 @@
 language: ruby
 rvm:
+  - 1.9.3
   - 2.3.0
+  - 2.0
+  - 2.1
+  - 2.2
 before_install: gem install bundler -v 1.11.2

data/README.md

@@ -1,8 +1,12 @@
 # WaitForIt
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/wait_for_it`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Build Status](https://travis-ci.org/schneems/wait_for_it.svg?branch=master)](https://travis-ci.org/schneems/wait_for_it)
 
-TODO: Delete this and the text above, and describe your gem
+Spawns processes and waits for them so you can integration test really complicated things with determinism. For inspiration behind why you should use something like this check out my talk [Testing the Untestable](https://www.youtube.com/watch?v=QHMKIHkY1nM). You can test long running processes such as webservers, or features that require concurrency or libraries that use global configuration.
+
+Don't add `sleep` to your tests, instead...
+
+![](https://media.giphy.com/media/RL9YUXgD6a3du/giphy.gif)
 
 ## Installation
 
@@ -22,7 +26,134 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+> For actual usage examples check out the [specs](https://github.com/schneems/wait_for_it/blob/master/spec/wait_for_it_spec.rb).
+
+This library spawns processes (sorry, doesn't work on windows) and instead of sleeping a predetermined time to wait for that process to do something it reads in a log file until certain outputs are received. For example if you wanted to test booting up a puma webserver, manually when you start it you might get this output
+
+```sh
+$ bundle exec puma
+[5322] Puma starting in cluster mode...
+[5322] * Version 2.15.3 (ruby 2.3.0-p0), codename: Autumn Arbor Airbrush
+[5322] * Min threads: 5, max threads: 5
+[5322] * Environment: development
+[5322] * Process workers: 2
+[5322] * Preloading application
+[5322] * Listening on tcp://0.0.0.0:3000
+[5322] Use Ctrl-C to stop
+[5322] - Worker 0 (pid: 5323) booted, phase: 0
+[5322] - Worker 1 (pid: 5324) booted, phase: 0
+```
+
+So you can see that when `booted` makes its way to the stdout we know it has fully launched and now we can start to use this running process. To do the same thing using this library we could
+
+```ruby
+require 'wait_for_it'
+
+WaitForIt.new("bundle exec puma", wait_for: "booted") do |spawn|
+  # ...
+end
+```
+
+> NOTE: If you don't use the block syntax you must call `cleanup` on the object, otherwise you may have stray files or process around after you code exits. I recommend calling it in an `ensure` block of code.
+
+Your main code will wait until it receives an output of "booted" from the `bundle exec puma` command. Now the process is running, you could programatically send it a request via `$ curl http://localhost:3000/repos/new` and verify the output using helper methods. Let's say you expect this to trigger a `302` response, the log would look like
+
+```sh
+[5324] 127.0.0.1 - - [02/Feb/2016:12:35:15 -0600] "GET /repos/new HTTP/1.1" 302 - 0.0183
+```
+
+You can now assert that is found in your puma output
+
+
+```ruby
+WaitForIt.new("bundle exec puma", wait_for: "booted") do |spawn|
+  `curl http://localhost:3000/repos/new`
+  assert_equal 1, spawn.count("302")
+end
+# ...
+spawn.cleanup
+```
+
+If you have a background thread that sporatically emits information to the logs like [Puma Worker Killer](https://github.com/schneems/puma_worker_killer), if you configure it to do a rolling restart, you could either wait for that to happen.
+
+
+```ruby
+WaitForIt.new("bundle exec puma", wait_for: "booted") do |spawn
+  if spawn.wait("PumaWorkerKiller: Rolling Restart")
+    # ...
+  end
+end
+```
+
+The `wait` command will return a false if it reaches a timeout before finding the output, If you prefer you can raise an exception by using `wait!` method.
+
+You can also assert if the output contains a phrase a string or regex:
+
+```ruby
+WaitForIt.new("bundle exec puma", wait_for: "booted") do |spawn|
+  spawn.contains?("PumaWorkerKiller: Rolling Restart")
+end
+```
+
+You can directly read from the log if you want
+
+
+```ruby
+WaitForIt.new("bundle exec puma", wait_for: "booted") do |spawn|
+  spawn.log.read
+end
+```
+
+The `log` method returns a `Pathname` object.
+
+## Config
+
+You can send environment variables to your process using the `env` key
+
+```ruby
+WaitForIt.new("bundle exec puma", wait_for: "booted", env: { RACK_ENV: "production "}) do
+end
+```
+
+By default redirection is performed using `" >> "` you can change the [IO redirection](http://www.tldp.org/LDP/abs/html/io-redirection.html) by setting the `redirection` key. For example if you wanted to capture STDERR in addition to stdout:
+
+```ruby
+spawn = WaitForIt.new("bundle exec puma", wait_for: "booted", redirection: "2>>") do
+end
+```
+
+If you're using Bash 4 you can get STDERR and STDOUT using `"&>>"` [Stack Overflow](http://stackoverflow.com/questions/876239/how-can-i-redirect-and-append-both-stdout-and-stderr-to-a-file-with-bash).
+
+You can change the default timeout using the `timeout` key (default is 10 seconds).
+
+```ruby
+spawn = WaitForIt.new("bundle exec puma", wait_for: "booted", timeout: 60) do
+end
+```
+
+If you need an individual `wait` have a different timeout you can pass in a timeout value
+
+```ruby
+WaitForIt.new("bundle exec puma", wait_for: "booted", timeout: 60) do |spawn|
+  spawn.wait("GET /repos/new", 2) # timeout after 2 seconds
+end
+```
+
+## Global config
+
+If you're doing a lot of "waiting for it" you can supply default arguments globally
+
+```
+WaitForIt.config do |config|
+  config.timeout     = 60
+  config.redirection = "2>>"
+  config.env         = { RACK_ENV: "production"}
+end
+```
+
+## Concurrency Issues
+
+You should be aware of cases where your tests might be run concurrently. For example if you're testing something that uses a lock in postgres, when you run your tests on a CI server it may spin up multiple tests at the same time that all try to grab the same lock. Most CI servers provide unique build IDs that you could use in this case to generate unique keys. Another thing to watch out for is files, if you're tesing a process that writes a `pidfile` you probably want to do something like make a temporary directory and copy files into that directory so that multiple tests could run at the same time and not try to write to the same file.
 
 ## Development
 
@@ -32,8 +163,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/wait_for_it. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-
+Bug reports and pull requests are welcome on GitHub at https://github.com/schneems/wait_for_it. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 

data/lib/wait_for_it.rb

@@ -1,5 +1,176 @@
 require "wait_for_it/version"
 
-module WaitForIt
-  # Your code goes here...
+require 'pathname'
+require 'shellwords'
+require 'tempfile'
+require 'timeout'
+
+class WaitForIt
+  class WaitForItTimeoutError < StandardError
+    def initialize(options = {})
+      command = options[:command]
+      input   = options[:input]
+      timeout = options[:timeout]
+      log     = options[:log]
+      super "Running command: '#{ command }', waiting for '#{ input }' did not occur within #{ timeout } seconds:\n#{ log.read }"
+    end
+  end
+
+  DEFAULT_TIMEOUT = 10 # seconds
+  DEFAULT_OUT     = ">>"
+  DEFAULT_ENV     = {}
+
+  # Configure global WaitForIt settings
+  def self.config
+    yield self
+    self
+  end
+
+  # The default output is expected in the logs before the process is considered "booted"
+  def self.wait_for=(wait_for)
+    @wait_for = wait_for
+  end
+
+  def self.wait_for
+    @wait_for
+  end
+
+  # The default timeout that is waited for a process to boot
+  def self.timeout=(timeout)
+    @timeout = timeout
+  end
+
+  def self.timeout
+    @timeout || DEFAULT_TIMEOUT
+  end
+
+
+  # The default shell redirect to the logs
+  def self.redirection=(redirection)
+    @redirection = redirection
+  end
+
+  def self.redirection
+    @redirection || DEFAULT_OUT
+  end
+
+
+  # Default environment variables under which commands should be executed.
+  def self.env=(env)
+    @env = env
+  end
+
+  def self.env
+    @env || DEFAULT_ENV
+  end
+
+  # Creates a new WaitForIt instance
+  #
+  # @param [String] command Command to spawn
+  # @param [Hash] options
+  # @options options [Fixnum] :timeout The duration to wait a commmand to boot, default is 10 seconds
+  # @options options [String] :wait_for The output the process emits when it has successfully booted.
+  #   When present the calling process will block until the message is received in the log output
+  #   or until the timeout is hit.
+  # @options options [String] :redirection The shell redirection used to pipe to log file
+  # @options options [Hash]   :env Keys and values for environment variables in the process
+  def initialize(command, options = {})
+    @command    = command
+    @timeout    = options[:timeout]     || WaitForIt.timeout
+    @wait_for   = options[:wait_for]    || WaitForIt.wait_for
+    redirection = options[:redirection] || WaitForIt.redirection
+    env         = options[:env]         || WaitForIt.env
+    @log        = set_log
+    @pid        = nil
+
+    raise "Must provide a wait_for: option" unless @wait_for
+    spawn(command, redirection, env)
+    wait!(@wait_for)
+
+    if block_given?
+      begin
+        yield self
+      ensure
+        cleanup
+      end
+    end
+  end
+
+  attr_reader :timeout, :log
+
+  # Checks the logs of the process to see if they contain a match.
+  # Can use a string or a regular expression.
+  def contains?(input)
+    log.read.match convert_to_regex(input)
+  end
+
+  # Returns a count of the number of times logs match the input.
+  # Can use a string or a regular expression.
+  def count(input)
+    log.read.scan(convert_to_regex(input)).count
+  end
+
+  # Blocks parent process until given message appears at the
+  def wait(input, t = timeout)
+    regex = convert_to_regex(input)
+    Timeout::timeout(t) do
+      until log.read.match regex
+        sleep 0.01
+      end
+    end
+    sleep 0.01
+    self
+  rescue Timeout::Error
+    puts "Timeout waiting for #{input.inspect} to find a match using #{ regex } in \n'#{ log.read }'"
+    false
+  end
+
+  # Same as `wait` but raises an error if timeout is reached
+  def wait!(input, t = timeout)
+    unless wait(input)
+      options = {}
+      options[:command] = @command
+      options[:input]   = input
+      options[:timeout] = t
+      options[:log]     = @log
+      raise WaitForItTimeoutError.new(options)
+    end
+  end
+
+  # Kills the process and removes temporary files
+  def cleanup
+    shutdown
+    @tmp_file.close
+    @log.unlink
+  end
+
+private
+  def set_log
+    @tmp_file  = Tempfile.new(["wait_for_it", ".log"])
+    log_file   = Pathname.new(@tmp_file)
+    log_file.mkpath unless log_file.exist?
+    log_file
+  end
+
+  def spawn(command, redirection, env_hash = {})
+    env     = env_hash.map {|key, value| "#{ key.to_s.shellescape }=#{ value.to_s.shellescape }" }.join(" ")
+    command = "/usr/bin/env #{ env } bash -c #{ command.shellescape } #{ redirection } #{ log }"
+    @pid = Process.spawn("#{ command }")
+  end
+
+  def convert_to_regex(input)
+    return input if input.is_a?(Regexp)
+    Regexp.new(Regexp.escape(input))
+  end
+
+  # Kills the process and waits for it to exit
+  def shutdown
+    if @pid
+      Process.kill('TERM', @pid)
+      Process.wait(@pid)
+      @pid = nil
+    end
+  rescue Errno::ESRCH
+    # Process doesn't exist, nothing to kill
+  end
 end

data/lib/wait_for_it/version.rb

@@ -1,3 +1,3 @@
-module WaitForIt
-  VERSION = "0.1.0"
+class WaitForIt
+  VERSION = "0.1.1"
 end

data/wait_for_it.gemspec

@@ -9,9 +9,9 @@ Gem::Specification.new do |spec|
   spec.authors       = ["schneems"]
   spec.email         = ["richard.schneeman@gmail.com"]
 
-  spec.summary       = %q{: Write a short summary, because Rubygems requires one.}
-  spec.description   = %q{: Write a longer description or delete this line.}
-  spec.homepage      = ""
+  spec.summary       = %q{ Stop sleeping in your tests, instead wait for it... }
+  spec.description   = %q{ Make your complicated integration tests more deterministic with wait for it}
+  spec.homepage      = "https://github.com/schneems/wait_for_it"
   spec.license       = "MIT"
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wait_for_it
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - schneems
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-02 00:00:00.000000000 Z
+date: 2016-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,7 +52,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: ": Write a longer description or delete this line."
+description: " Make your complicated integration tests more deterministic with wait
+  for it"
 email:
 - richard.schneeman@gmail.com
 executables: []
@@ -72,7 +73,7 @@ files:
 - lib/wait_for_it.rb
 - lib/wait_for_it/version.rb
 - wait_for_it.gemspec
-homepage: ''
+homepage: https://github.com/schneems/wait_for_it
 licenses:
 - MIT
 metadata: {}
@@ -95,5 +96,5 @@ rubyforge_project:
 rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
-summary: ": Write a short summary, because Rubygems requires one."
+summary: Stop sleeping in your tests, instead wait for it...
 test_files: []