capybara-paparazzi 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4e37b4dd76d939ff8af81d07dffd57b8bec00451
+  data.tar.gz: f0b32e133aae2070f4c533b645eca45b9de6dfe1
+SHA512:
+  metadata.gz: 875d8f5a8f55c4c79435cd577fde4da551fda8a42b1b56f83bc1419ff3bea67b12100eb088fc13b7ccc5a95706a6a4945c7116efdabb575c2cc563b5772e6557
+  data.tar.gz: e15368acf07fe259bf8f7e7330a385e2cea4f83b1ff6ef5f594a48800f358b78cd9444230986c23f064ed5a6092d21de9e81c90a4e010954edc40473899b5204

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in capybara-paparazzi.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Steven Bull
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,150 @@
+# Capybara::Paparazzi
+
+Capybara::Paparazzi simplifies and automates the task of capturing
+screenshots of your app by snapping full-length photos of your pages
+in various window widths during a run of your test suite. If you've
+ever wanted to get screenshots of your user flows to check how
+everything looks on a phone vs. on a tablet vs. on a desktop, this gem
+is for you. This is particularly useful if you are using responsive
+CSS. Additionally, it draws a line on the screenshot where the "fold"
+would be, showing a user's first impression of a page.
+
+Capybara::Paparazzi hooks into Capybara's feature tests and takes
+pictures at significant user actions (like visiting a page, clicking
+buttons, etc.). It relies on a driver that supports saving screenshots
+and executing javascript, and was originally built with Poltergeist in
+mind.
+
+A few driving principles of Capybara::Paparazzi:
+
+- **Unobtrusive**: You shouldn't need to edit your feature test scenarios
+  to get screenshots.
+- **Easy**: Simple to set up, and out-of-the-box settings should get you far.
+- **Customizable**: You should be able to tweak it to your needs easily,
+  without needing to re-invent too much to achieve what you want.
+- **Exhaustive**: Taking extra screenshots is better than missing out on
+  important things. It's easy to delete or ignore unnecessary files later.
+
+## Installation
+
+Add a line to your application's Gemfile:
+
+    group :test do
+      gem 'rspec-rails'
+      gem 'capybara'
+      gem 'poltergeist'
+      gem 'capybara-paparazzi' # <-- add this one
+    end
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install capybara-paparazzi
+
+## Usage
+
+### Quick-Start
+
+After getting the gem installed, using Capybara::Paparazzi is pretty simple.
+In your test setup file (using rspec, probably `spec/spec_helper.rb`),
+add something like this:
+
+```ruby
+# Other rspec & capybara setup, such as:
+# require 'rspec/rails'
+# require 'capybara/rspec'
+
+require 'capybara/poltergeist' # <-- Use a fancy driver.
+Capybara.default_driver = :poltergeist # <-- Set it to be used for everything.
+
+Capybara::Paparazzi.follow(:poltergeist) # <-- Take screenshots of everything the driver does.
+
+```
+
+Now just run
+
+    $ rspec
+
+or
+
+    $ rake
+
+and you'll get screenshots in a `screenshots` folder.
+
+### Configuring
+
+Use `Capybara::Paparazzi.follow(<driver_name>, ...)` to take screenshots
+for a particular driver. You can also do `config.follow(<driver_name>, ...)`
+inside of a configuration block, instead. It doesn't matter if this
+happens before or after the driver itself is actually registered with
+Capybara, just as long as the name matches.
+
+Here's a fairly complete list of things you can do:
+
+```ruby
+Capybara::Paparazzi.config do |config|
+  config.js_var_name = 'MY_DIV' # Name of the div used to draw the fold line.
+  config.js_var_style.merge!(color: 'red', fontWeight: 'bold')
+  config.screenshot_sizes = [ config.screenshot_sizes.first, (config.screenshot_sizes.last + [ :EXTRA_DATA ]) ]
+  config.file_dir = '../screenshots'
+  # config.js_setup_script = ->(shooter){ ... }
+  config.js_resize_script = ->(shooter, height) {
+    "#{shooter.js_var_name}.style.height = '#{height}px'; MY_DIV.textContent = #{shooter.screenshot_size.inspect.to_json}; MY_DIV.style.fontSize = '#{height/4}px';"
+  }
+  # config.js_cleanup_script = ->(shooter){}
+  config.before_save_callback = ->(shooter) {
+    shooter.resize_window(shooter.width * 2, shooter.height / 2)
+    shooter.do_shot = shooter.suffix.to_s.empty?
+  }
+  config.follow(:poltergeist)
+end
+```
+
+For the default settings, see [shooter.rb](https://github.com/sbull/capybara-paparazzi/blob/master/lib/capybara/paparazzi/shooter.rb).
+
+### Screenshot Sizes
+
+Capybara::Paparazzi uses default screen sizes to represent common
+phone, tablet, and desktop browser dimensions. The most important
+feature is the width. The height is used to draw the "fold" line - the
+default sizes attempt to take into account the browser chrome that
+gets added to the top and bottom of browser windows, which results in
+a shorter view than the actual device height.
+
+## Tips & Tricks
+
+### Turning Capybara::Paparazzi On and Off
+
+Use an environment variable to turn screenshots on or off.
+You probably don't want them running all the time, and only
+need them on occasion:
+
+    Capybara::Paparazzi.follow(Capybara.default_driver, Capybara.javascript_driver) if ENV['CAPYBARA_PAPARAZZI_ENABLED']
+
+### Driver Setup
+
+Poltergeist is a great headless driver to use, particularly due to its
+ease of installation.
+Here's a simple approach that could work for you:
+
+1. Install [PhantomJS](http://phantomjs.org/).
+  1. Prereqs: install [nodejs](http://nodejs.org/) and npm.
+     Try something like: `sudo apt-get install nodejs`
+  2. Use npm to install phantomjs: `sudo npm install -g phantomjs`
+2. Install [Poltergeist](https://github.com/teampoltergeist/poltergeist).
+  1. Add poltergeist to your Gemfile: `gem 'poltergeist'`
+  2. `bundle install`
+3. Use Poltergeist:
+  1. `require 'capybara/poltergeist'`
+  2. `Capybara.javascript_driver = :poltergeist`
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/capybara-paparazzi.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'capybara/paparazzi/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "capybara-paparazzi"
+  spec.version       = Capybara::Paparazzi::VERSION
+  spec.authors       = ["Steven Bull"]
+  spec.email         = ["steven@thebulls.us"]
+  spec.description = <<DESCRIPTION
+Capybara::Paparazzi automatically takes screenshots of all of your pages,
+in a variety of different window sizes. It clearly indicates where the
+initial view of the page cuts off (the "fold"), and is easily configurable.
+DESCRIPTION
+  spec.summary       = 'Take responsive screenshots of your site.'
+  spec.homepage      = 'https://github.com/sbull/capybara-paparazzi'
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+
+  spec.add_runtime_dependency 'capybara', '~> 2.0'
+end

data/lib/capybara-paparazzi.rb

@@ -0,0 +1,42 @@
+require 'capybara'
+
+require 'capybara/paparazzi/version'
+require 'capybara/paparazzi/shooter'
+require 'capybara/paparazzi/driver'
+require 'capybara/paparazzi/element'
+require 'capybara/paparazzi/session'
+
+module Capybara::Paparazzi
+
+  module ClassMethods
+
+    def config(&block)
+      Capybara::Paparazzi::Shooter.config(&block)
+    end
+
+    def follow(*driver_names)
+      driver_names.each do |name|
+        used_drivers[name] = true
+      end
+    end
+
+    def used_drivers
+      @used_drivers ||= {}
+    end
+
+    def take_snapshots(driver, event_details=nil)
+      Capybara::Paparazzi::Shooter.take_snapshots(driver, event_details)
+    end
+
+  end # ClassMethods
+
+  extend ClassMethods
+end
+
+class Capybara::Node::Element
+  include Capybara::Paparazzi::Element
+end
+
+class Capybara::Session
+  include Capybara::Paparazzi::Session
+end

data/lib/capybara/paparazzi/driver.rb

@@ -0,0 +1,14 @@
+module Capybara::Paparazzi::Driver
+
+  # TODO: go_back, go_forward
+
+  def visit(*args)
+    super(*args)
+    take_snapshots(:visit, args)
+  end
+
+  def take_snapshots(method, args)
+    Capybara::Paparazzi.take_snapshots(self, { method: method, args: args })
+  end
+
+end

data/lib/capybara/paparazzi/element.rb

@@ -0,0 +1,16 @@
+module Capybara::Paparazzi::Element
+
+  def click_with_paparazzi(*args)
+    response = click_without_paparazzi(*args)
+    if session.driver.respond_to?(:take_snapshots)
+      session.driver.take_snapshots(:click, args)
+    end
+    response
+  end
+
+  def self.included(mod)
+    mod.send(:alias_method, :click_without_paparazzi, :click)
+    mod.send(:alias_method, :click, :click_with_paparazzi)
+  end
+
+end

data/lib/capybara/paparazzi/session.rb

@@ -0,0 +1,16 @@
+module Capybara::Paparazzi::Session
+
+  def driver_with_paparazzi(*args)
+    driver = driver_without_paparazzi(*args)
+    if Capybara::Paparazzi.used_drivers[mode] && !driver.is_a?(Capybara::Paparazzi::Driver)
+      driver.extend(Capybara::Paparazzi::Driver)
+    end
+    driver
+  end
+
+  def self.included(mod)
+    mod.send(:alias_method, :driver_without_paparazzi, :driver)
+    mod.send(:alias_method, :driver, :driver_with_paparazzi)
+  end
+
+end

data/lib/capybara/paparazzi/shooter.rb

@@ -0,0 +1,218 @@
+class Capybara::Paparazzi::Shooter
+
+  DEFAULT_SCREENSHOT_SIZES =
+    [
+     [ 320, 444 ], # 568 - 124
+     [ 768, 900 ], # 1024 - 124
+     [ 1024, 644 ], # 768 - 124
+     [ 1336, 600 ],
+    ].freeze
+
+  DEFAULT_FOLD_STYLE = {
+    position: 'fixed',
+    top: '0',
+    left: '0',
+    width: '100%',
+    zIndex: 999999,
+    borderBottom: '1px solid red',
+  }.freeze
+
+  CONFIG_VARS = {
+    js_var_name: 'THE_FOLD',
+    js_var_style: {}.merge(DEFAULT_FOLD_STYLE),
+    screenshot_sizes: ([] + DEFAULT_SCREENSHOT_SIZES),
+    file_dir: 'screenshots',
+    js_setup_script: ->(shooter) {
+      var_name = shooter.js_var_name
+      script = "if (!window.#{var_name}) { #{var_name} = document.createElement('DIV');"
+      shooter.js_var_style.each do |prop_name, prop_val|
+        script += "#{var_name}.style.#{prop_name} = #{prop_val.to_json};"
+      end
+      script += "} document.body.appendChild(#{var_name});"
+    },
+    js_resize_script: ->(shooter, height) { "#{shooter.js_var_name}.style.height = '#{height}px';" },
+    before_save_callback: nil,
+    js_cleanup_script: ->(shooter) { "document.body.removeChild(#{shooter.js_var_name});" },
+  }.freeze
+
+
+  module ClassMethods
+
+    attr_accessor(*CONFIG_VARS.keys)
+
+    def config
+      @_configged ||=
+        begin
+          CONFIG_VARS.each do |cv, default|
+            send("#{cv}=".to_sym, default)
+            true
+          end
+        end
+      if block_given?
+        yield(self)
+      end
+    end
+
+    def follow(*args)
+      Capybara::Paparazzi.follow(*args)
+    end
+
+    def take_snapshots(driver, event_details=nil)
+      # TODO: Be smarter. One shooter per driver, but avoid memory leaks (be mindful of Guard, etc.).
+      new(driver, event_details).take_snapshots
+    end
+
+    def next_suffix_for_path!(path)
+      # TODO: Be smarter about this - multi-threaded, etc.
+      @path_nums ||= {}
+      num = @path_nums[path]
+      @path_nums[path] = num.to_i + 1
+      if num
+        suffix = ".#{num}"
+        if @path_nums[path+suffix]
+          suffix = next_suffix_for_path!(path)
+        end
+      else
+        suffix = ''
+      end
+      suffix
+    end
+
+  end # ClassMethods
+
+  extend ClassMethods
+
+
+  attr_accessor :driver, :event_details
+  attr_accessor :path, :suffix
+  attr_accessor :do_shot, :screenshot_size, :filename
+  attr_accessor :before_save_callback
+
+  attr_accessor(*CONFIG_VARS.keys)
+  # def cv; @cv ||= self.class.config[:cv]; end
+  CONFIG_VARS.each do |cv, default|
+    define_method(cv) do
+      iv_sym = "@#{cv}".to_sym
+      iv = instance_variable_get(iv_sym)
+      unless iv
+        iv = self.class.send(cv.to_sym)
+        instance_variable_set(iv_sym, iv)
+      end
+      iv
+    end
+  end
+
+
+  def initialize(driver, event_details=nil)
+    @driver = driver
+    @event_details = event_details
+    @config = self.class.config
+  end
+
+  def take_snapshots
+    set_path_and_suffix
+    execute_setup_script
+    save_snapshots
+    execute_cleanup_script
+  end
+
+  def width
+    @screenshot_size[0]
+  end
+
+  def height
+    @screenshot_size[1]
+  end
+
+  def resize_window(width, height)
+    begin
+      if driver.respond_to?(:resize) # Poltergeist
+        driver.resize(width, height)
+      elsif driver.respond_to?(:resize_window) # Poltergeist
+        driver.resize_window(width, height)
+      else # Capybara default / Selenium
+        driver.resize_window_to(driver.current_window_handle, width, height)
+      end
+    rescue => e
+      log("Error while resizing window: #{e}")
+    end
+    execute_resize_script(height)
+  end
+
+
+  private
+
+  def set_path_and_suffix
+    path, suffix = path_and_suffix_for_url(driver.current_url)
+    self.path = path
+    self.suffix = suffix
+  end
+
+  def execute_setup_script
+    exec_js(:js_setup_script, self)
+  end
+
+  def exec_js(script_name, *args)
+    begin
+      script = send(script_name)
+      if script
+        script_text = script.is_a?(Proc) ? script.call(*args) : script.to_s
+        driver.execute_script(script_text)
+      end
+    rescue => e
+      log("#{e.message}\nJavascript: #{script_text}")
+    end
+  end
+
+  def save_snapshots
+    screenshot_sizes.each do |w_h_rest|
+      save_snapshot(w_h_rest)
+    end
+  end
+
+  def save_snapshot(width_height_rest)
+    @do_shot = true
+    @screenshot_size = ([] + width_height_rest)
+    @filename = "#{file_dir}#{path}#{suffix}-#{width}.png"
+
+    resize_window(width, height)
+
+    before_save_callback.call(self) if before_save_callback
+
+    if @do_shot
+      save_screenshot
+    end
+  end
+
+  def execute_resize_script(height)
+    exec_js(:js_resize_script, self, height)
+  end
+
+  def execute_cleanup_script
+    exec_js(:js_cleanup_script, self)
+  end
+
+  def save_screenshot
+    driver.save_screenshot(*get_save_screenshot_args)
+  end
+
+  def get_save_screenshot_args
+    [ filename, { full: true } ]
+  end
+
+  def path_and_suffix_for_url(url)
+    path = URI.parse(url).path
+    path += 'index' if path[-1] == '/'
+    suffix = next_suffix_for_path!(path)
+    [ path, suffix ]
+  end
+
+  def next_suffix_for_path!(path)
+    self.class.next_suffix_for_path!(path)
+  end
+
+  def log(msg)
+    warn "Capybara::Paparazzi: #{msg}"
+  end
+
+end

data/lib/capybara/paparazzi/version.rb

@@ -0,0 +1,5 @@
+module Capybara
+  module Paparazzi
+    VERSION = "0.0.1"
+  end
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: capybara-paparazzi
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Steven Bull
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: |
+  Capybara::Paparazzi automatically takes screenshots of all of your pages,
+  in a variety of different window sizes. It clearly indicates where the
+  initial view of the page cuts off (the "fold"), and is easily configurable.
+email:
+- steven@thebulls.us
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- capybara-paparazzi.gemspec
+- lib/capybara-paparazzi.rb
+- lib/capybara/paparazzi/driver.rb
+- lib/capybara/paparazzi/element.rb
+- lib/capybara/paparazzi/session.rb
+- lib/capybara/paparazzi/shooter.rb
+- lib/capybara/paparazzi/version.rb
+homepage: https://github.com/sbull/capybara-paparazzi
+licenses:
+- MIT
+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.0.14
+signing_key: 
+specification_version: 4
+summary: Take responsive screenshots of your site.
+test_files: []