puffing-billy 0.2.1 → 0.2.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 77894c8ea71e9f2b91cb3aae48c6bc1311ab45ba
+  data.tar.gz: 2af9cc1a8fafdfafa15ac9bf1d088e2cb648ae59
+SHA512:
+  metadata.gz: 00faa0d3c37550847f947b5440770e628978593476771c27f26d31516b8ff176540340a00cba098b2fca5ebcd86bc53b29a94d53af57c4b92547be3a3b07f603
+  data.tar.gz: 642297885633e8f29efab30ad78faef48d173dd4b4a902cb92cbef118c616b349a01671d27f5b3b38af8b8ad4b341f251d0d23fdff9e1b7b3096b118efd246a6

data/.gitignore

@@ -1,3 +1,4 @@
 node_modules/
 log/test.log
+.idea/
 .ruby-version

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    puffing-billy (0.2.1)
+    puffing-billy (0.2.3)
       capybara
       em-http-request
       eventmachine
@@ -12,108 +12,120 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.3.3)
-    builder (3.2.0)
-    capybara (2.0.2)
+    addressable (2.3.5)
+    builder (3.2.2)
+    capybara (2.1.0)
       mime-types (>= 1.16)
       nokogiri (>= 1.3.3)
       rack (>= 1.0.0)
       rack-test (>= 0.5.4)
-      selenium-webdriver (~> 2.0)
-      xpath (~> 1.0.0)
-    capybara-webkit (0.14.2)
-      capybara (~> 2.0, >= 2.0.2)
+      xpath (~> 2.0)
+    capybara-webkit (1.1.1)
+      capybara (>= 2.0.2, < 2.2.0)
       json
-    childprocess (0.3.8)
+    celluloid (0.15.2)
+      timers (~> 1.1.0)
+    childprocess (0.4.0)
       ffi (~> 1.0, >= 1.0.11)
-    coderay (1.0.9)
+    cliver (0.3.2)
+    coderay (1.1.0)
     cookiejar (0.3.0)
-    cucumber (1.2.5)
+    cucumber (1.3.10)
       builder (>= 2.1.2)
       diff-lcs (>= 1.1.3)
-      gherkin (~> 2.11.7)
-      multi_json (~> 1.3)
+      gherkin (~> 2.12)
+      multi_json (>= 1.7.5, < 2.0)
+      multi_test (>= 0.0.2)
     daemons (1.1.9)
-    diff-lcs (1.2.1)
-    em-http-request (1.0.3)
-      addressable (>= 2.2.3)
+    diff-lcs (1.2.5)
+    em-http-request (1.1.2)
+      addressable (>= 2.3.4)
       cookiejar
-      em-socksify
-      eventmachine (>= 1.0.0.beta.4)
-      http_parser.rb (>= 0.5.3)
-    em-socksify (0.2.1)
+      em-socksify (>= 0.3)
+      eventmachine (>= 1.0.3)
+      http_parser.rb (>= 0.6.0)
+    em-socksify (0.3.0)
       eventmachine (>= 1.0.0.beta.4)
-    eventmachine (1.0.1)
+    eventmachine (1.0.3)
     eventmachine_httpserver (0.2.1)
-    faraday (0.8.6)
-      multipart-post (~> 1.1)
-    faye-websocket (0.4.7)
-      eventmachine (>= 0.12.0)
-    ffi (1.4.0)
-    gherkin (2.11.8)
+    faraday (0.9.0)
+      multipart-post (>= 1.2, < 3)
+    ffi (1.9.3)
+    formatador (0.2.4)
+    gherkin (2.12.2)
       multi_json (~> 1.3)
-    guard (1.6.2)
-      listen (>= 0.6.0)
-      lumberjack (>= 1.0.2)
-      pry (>= 0.9.10)
-      terminal-table (>= 1.4.3)
-      thor (>= 0.14.6)
-    http_parser.rb (0.5.3)
-    json (1.7.7)
-    listen (0.7.3)
-    lumberjack (1.0.2)
-    method_source (0.8.1)
-    mime-types (1.21)
-    multi_json (1.6.1)
-    multipart-post (1.2.0)
-    nokogiri (1.5.6)
-    poltergeist (1.1.0)
-      capybara (~> 2.0, >= 2.0.1)
-      faye-websocket (~> 0.4, >= 0.4.4)
-      http_parser.rb (~> 0.5.3)
-    pry (0.9.12)
-      coderay (~> 1.0.5)
+    guard (2.4.0)
+      formatador (>= 0.2.4)
+      listen (~> 2.1)
+      lumberjack (~> 1.0)
+      pry (>= 0.9.12)
+      thor (>= 0.18.1)
+    http_parser.rb (0.6.0)
+    json (1.8.1)
+    listen (2.4.1)
+      celluloid (>= 0.15.2)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+    lumberjack (1.0.4)
+    method_source (0.8.2)
+    mime-types (2.1)
+    mini_portile (0.5.2)
+    multi_json (1.8.4)
+    multi_test (0.0.3)
+    multipart-post (2.0.0)
+    nokogiri (1.6.1)
+      mini_portile (~> 0.5.0)
+    poltergeist (1.5.0)
+      capybara (~> 2.1)
+      cliver (~> 0.3.1)
+      multi_json (~> 1.0)
+      websocket-driver (>= 0.2.0)
+    pry (0.9.12.6)
+      coderay (~> 1.0)
       method_source (~> 0.8)
       slop (~> 3.4)
     rack (1.5.2)
     rack-test (0.6.2)
       rack (>= 1.0)
-    rb-inotify (0.9.0)
+    rb-fsevent (0.9.4)
+    rb-inotify (0.9.3)
       ffi (>= 0.5.0)
-    rspec (2.13.0)
-      rspec-core (~> 2.13.0)
-      rspec-expectations (~> 2.13.0)
-      rspec-mocks (~> 2.13.0)
-    rspec-core (2.13.0)
-    rspec-expectations (2.13.0)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.5)
       diff-lcs (>= 1.1.3, < 2.0)
-    rspec-mocks (2.13.0)
-    rubyzip (0.9.9)
-    selenium-webdriver (2.30.0)
+    rspec-mocks (2.14.5)
+    rubyzip (1.1.0)
+    selenium-webdriver (2.39.0)
       childprocess (>= 0.2.5)
       multi_json (~> 1.0)
-      rubyzip
+      rubyzip (~> 1.0)
       websocket (~> 1.0.4)
-    slop (3.4.3)
-    terminal-table (1.4.5)
-    thin (1.5.0)
+    slop (3.4.7)
+    thin (1.6.1)
       daemons (>= 1.0.9)
-      eventmachine (>= 0.12.6)
+      eventmachine (>= 1.0.0)
       rack (>= 1.0.0)
-    thor (0.17.0)
+    thor (0.18.1)
+    timers (1.1.0)
     websocket (1.0.7)
-    xpath (1.0.0)
+    websocket-driver (0.3.2)
+    xpath (2.0.0)
       nokogiri (~> 1.3)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  capybara-webkit
+  capybara-webkit (~> 1.0)
   cucumber
   faraday
   guard
   poltergeist
+  pry
   puffing-billy!
   rack
   rb-inotify

data/README.md

@@ -57,6 +57,10 @@ Capybara.javascript_driver = :selenium_billy
 # Capybara.javascript_driver = :poltergeist_billy
 ```
 
+Note: :poltergeist_billy doesn't support proxying any localhosts, so you must use
+:webkit_billy for headless specs when using puffing-billy for other local rack apps.
+See [this phantomjs issue](https://github.com/ariya/phantomjs/issues/11342) for any updates.
+
 In your tests:
 
 ```ruby
@@ -150,6 +154,16 @@ Billy.configure do |c|
 end
 ```
 
+If you would like to cache other local rack apps, you must whitelist only the
+specific port for the application that is executing tests.  If you are using
+[Capybara](https://github.com/jnicklas/capybara), this can be accomplished by
+adding this in your `spec_helper.rb`:
+
+```ruby
+server = Capybara.current_session.server
+Billy.config.whitelist = ["#{server.host}:#{server.port}"]
+```
+
 If you want to use puffing-billy like you would [VCR](https://github.com/vcr/vcr)
 you can turn on cache persistence. This way you don't have to manually mock out
 everything as requests are automatically recorded and played back. With cache
@@ -158,6 +172,7 @@ persistence you can take tests completely offline.
 ```ruby
 Billy.configure do |c|
   c.cache = true
+  c.cache_request_headers = false
   c.ignore_params = ["http://www.google-analytics.com/__utm.gif",
                      "https://r.twimg.com/jot",
                      "http://p.twitter.com/t.gif",
@@ -165,22 +180,112 @@ Billy.configure do |c|
                      "http://www.facebook.com/plugins/like.php",
                      "https://www.facebook.com/dialog/oauth",
                      "http://cdn.api.twitter.com/1/urls/count.json"]
+  c.path_blacklist = []
   c.persist_cache = true
+  c.ignore_cache_port = true # defaults to true
+  c.non_successful_cache_disabled = false
+  c.non_successful_error_level = :warn
+  c.non_whitelisted_requests_disabled = false
   c.cache_path = 'spec/req_cache/'
 end
-
-# need to call this because of a race condition between persist_cache
-# being set and the proxy being loaded for the first time
-Billy.proxy.restore_cache
 ```
 
+The cache works with all types of requests and will distinguish between
+different POST requests to the same URL.
+
+`c.cache_request_headers` is used to store the outgoing request headers in the cache.
+It is also saved to yml if `persist_cache` is enabled.  This additional information
+is useful for debugging (for example: viewing the referer of the request).
+
 `c.ignore_params` is used to ignore parameters of certain requests when
 caching. You should mostly use this for analytics and various social buttons as
 they use cache avoidance techniques, but return practically the same response
 that most often does not affect your test results.
 
-The cache works with all types of requests and will distinguish between
-different POST requests to the same URL.
+`c.path_blacklist = []` is used to always cache specific paths on any hostnames,
+including whitelisted ones.  This is useful if your AUT has routes that get data
+from external services, such as `/api` where the ajax request is a local URL but
+the actual data is coming from a different application that you want to cache.
+
+`c.ignore_cache_port` is used to strip the port from the URL if it exists.  This
+is useful when caching local paths (via `path_blacklist`) or other local rack apps
+that are running on random ports.
+
+`c.non_successful_cache_disabled` is used to not cache responses without 200-series
+or 304 status codes.  This prevents unauthorized or internal server errors from
+being cached and used for future test runs.
+
+`c.non_successful_error_level` is used to log when non-successful resposnes are
+received.  By default, it just writes to the log file, but when set to `:error`
+it throws an error with the URL and status code received for easier debugging.
+
+`c.non_whitelisted_requests_disabled` is used to disable hitting new URLs when
+no cache file exists.  Only whitelisted URLs (on non-blacklisted paths) are
+allowed, all others will throw an error with the URL attempted to be accessed.
+This is useful for debugging issues in isolated environments (ie.
+continuous integration).
+
+### Cache Scopes
+
+If you need to cache different responses to the same HTTP request, you can use
+cache scoping.
+
+For example, an index page may return zero or more items in a list, with or
+without pagination, depending on the number of entries in a database.
+
+There are a few different ways to use cache scopes:
+
+```ruby
+# If you do nothing, it uses the default cache scope:
+it 'defaults to nil scope' do
+  expect(proxy.cache.scope).to be_nil
+end
+
+# You can change context indefinitely to a specific cache scope:
+context 'with a cache scope' do
+  before do
+    proxy.cache.scope_to "my_cache"
+  end
+
+  # Remember to set the cache scope back to the default in an after block
+  # within the context it is used, and/or at the global spec_helper level!
+  after do
+    proxy.cache.use_default_scope
+  end
+
+  it 'uses the cache scope' do
+    expect(proxy.cache.scope).to eq("my_cache")
+  end
+
+  it 'can be reset to the default scope' do
+    proxy.cache.use_default_scope
+    expect(proxy.cache.scope).to be_nil
+  end
+
+  # Or you can run a block within the context of a cache scope:
+  # Note: When using scope blocks, be sure that both the action that triggers a 
+  #       request and the assertion that a response has been received are within the block
+  it 'can execute a block against a named cache' do
+    expect(proxy.cache.scope).to eq("my_cache")
+    proxy.cache.with_scope "another_cache" do
+      expect(proxy.cache.scope).to eq "another_cache"
+    end
+    # It
+    expect(proxy.cache.scope).to eq("my_cache")
+  end
+end
+```
+
+If you use named caches it is highly recommend that you use a global
+hook to set the cache back to the default before or after each test.
+
+In Rspec:
+
+```ruby
+RSpec.configure do |config|
+  config.before :each { proxy.cache.use_default_scope }
+end
+```
 
 ## Customising the javascript driver
 

data/lib/billy.rb

@@ -4,13 +4,15 @@ require "billy/proxy_request_stub"
 require "billy/cache"
 require "billy/proxy"
 require "billy/proxy_connection"
-
-$billy_proxy = Billy::Proxy.new
-$billy_proxy.start
+require "billy/railtie" if defined?(Rails)
 
 module Billy
   def self.proxy
-    $billy_proxy
+    @billy_proxy ||= (
+      proxy = Billy::Proxy.new
+      proxy.start
+      proxy
+    )
   end
 
   def self.register_drivers

data/lib/billy/cache.rb

@@ -1,49 +1,61 @@
 require 'resolv'
 require 'uri'
 require 'yaml'
+require 'billy/json_utils'
 
 module Billy
   class Cache
+    attr_reader :scope
+
     def initialize
       reset
-      load_dir
     end
 
-    def cacheable?(url, headers)
-      if Billy.config.cache
-        host = URI(url).host
-        !Billy.config.whitelist.include?(host)
-        # TODO test headers for cacheability
-      end
+    def cached?(method, url, body)
+      # Only log the key the first time it's looked up (in this method)
+      key = key(method, url, body, true)
+      !@cache[key].nil? or persisted?(key)
     end
 
-    def cached?(method, url, body)
-      !@cache[key(method, url, body)].nil?
+    def persisted?(key)
+      Billy.config.persist_cache and File.exists?(cache_file(key))
     end
 
     def fetch(method, url, body)
-      @cache[key(method, url, body)]
+      key = key(method, url, body)
+      @cache[key] or fetch_from_persistence(key)
     end
 
-    def store(method, url, body, status, headers, content)
+    def fetch_from_persistence(key)
+      begin
+        @cache[key] = YAML.load(File.open(cache_file(key))) if persisted?(key)
+      rescue ArgumentError => e
+        puts "Could not parse YAML: #{e.message}"
+        nil
+      end
+    end
+
+    def store(method, url, request_headers, body, response_headers, status, content)
       cached = {
-        :url => url,
+        :scope => scope,
+        :url => format_url(url),
         :body => body,
         :status => status,
         :method => method,
-        :headers => headers,
+        :headers => response_headers,
         :content => content
       }
 
-      @cache[key(method, url, body)] = cached
+      cached.merge!({:request_headers => request_headers}) if Billy.config.cache_request_headers
+
+      key = key(method, url, body)
+      @cache[key] = cached
 
       if Billy.config.persist_cache
         Dir.mkdir(Billy.config.cache_path) unless File.exists?(Billy.config.cache_path)
 
         begin
-          path = File.join(Billy.config.cache_path,
-                           "#{key(method, url, body)}.yml")
-          File.open(path, 'w') do |f|
+          File.open(cache_file(key), 'w') do |f|
             f.write(cached.to_yaml(:Encoding => :Utf8))
           end
         rescue StandardError => e
@@ -55,35 +67,56 @@ module Billy
       @cache = {}
     end
 
-    def load_dir
-      if Billy.config.persist_cache
-        Dir.glob(Billy.config.cache_path+"*.yml") { |filename|
-          data = begin
-                   YAML.load(File.open(filename))
-                 rescue ArgumentError => e
-                   puts "Could not parse YAML: #{e.message}"
-                 end
-
-          @cache[key(data[:method], data[:url], data[:body])] = data
-        }
+    def key(method, orig_url, body, log_key = false)
+      ignore_params = Billy.config.ignore_params.include?(format_url(orig_url, true))
+      url = URI(format_url(orig_url, ignore_params))
+      key = method+'_'+url.host+'_'+Digest::SHA1.hexdigest(scope.to_s + url.to_s)
+      body_msg = ''
+
+      if method == 'post' and !ignore_params
+        body_formatted = JSONUtils::json?(body.to_s) ? JSONUtils::sort_json(body.to_s) : body.to_s
+        body_msg = " with body '#{body_formatted}'"
+        key += '_'+Digest::SHA1.hexdigest(body_formatted)
       end
+
+      Billy.log(:info, "puffing-billy: CACHE KEY for '#{orig_url}#{body_msg}' is '#{key}'") if log_key
+      key
     end
 
-    def key(method, url, body)
+    def format_url(url, ignore_params=false)
       url = URI(url)
-      no_params = url.scheme+'://'+url.host+url.path
-
-      if Billy.config.ignore_params.include?(no_params)
-        url = URI(no_params)
+      port_to_include = Billy.config.ignore_cache_port ? '' : ":#{url.port}"
+      formatted_url = url.scheme+'://'+url.host+port_to_include+url.path
+      unless ignore_params
+        formatted_url += '?'+url.query if url.query
+        formatted_url += '#'+url.fragment if url.fragment
       end
+      formatted_url
+    end
 
-      key = method+'_'+url.host+'_'+Digest::SHA1.hexdigest(url.to_s)
+    def cache_file(key)
+      File.join(Billy.config.cache_path, "#{key}.yml")
+    end
 
-      if method == 'post' and !Billy.config.ignore_params.include?(no_params)
-        key += '_'+Digest::SHA1.hexdigest(body.to_s)
-      end
+    def scope_to(new_scope = nil)
+      self.scope = new_scope
+    end
 
-      key
+    def with_scope(use_scope = nil, &block)
+      raise ArgumentError, 'Expected a block but none was received.' if block.nil?
+      original_scope = scope
+      scope_to use_scope
+      block.call()
+    ensure
+      scope_to original_scope
+    end
+
+    def use_default_scope
+      scope_to nil
     end
+
+    private
+
+    attr_writer :scope
   end
 end