wraith 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bffb240ff47827e94e770a300822e1050c915251
-  data.tar.gz: d3a59402c518cbf852de2e7817deefdb037e19b9
+  metadata.gz: bc1b08d5b7dbe5e6347a8a661f82560cef5552ea
+  data.tar.gz: 259f28a58b73bf17ff37902636b9bcfb70e836a9
 SHA512:
-  metadata.gz: 2a0d90f1be903f814b696930aec7b4fae86a394ca80882cd49e97cccf894b9ed598571f0553b5fee282e9f7d16a635ff3edb9e856d1a74b037bdeff2f45ec7df
-  data.tar.gz: 2d1894f2ec8515af641c0f6eee94e4b8fdda15efa5f5ca9bab9f52a412dc5dc55d793a3b4513f1d124ded37cbd9ecde64b432b57217394a0e318d0392b6c23b7
+  metadata.gz: 9bf5dc5c91429da67d420246b3b11ea16f260836a9aeccd0e20fbdc249c380d66f2848a475bb440ed53f6e5fdf904cc2a63a665aadf24037089ea5b03edb2a60
+  data.tar.gz: f1e2400695398f549b49d438f0f33dd6e176e8d6524eca2004ed3057d362854194da4956da298ddf38abbd564d8b9ce942626de3796d4b080d8f90c5d15ecfd8

data/Dockerfile

@@ -0,0 +1,14 @@
+FROM ruby:2.1.2
+
+# some of ruby's build scripts are written in ruby
+# we purge this later to make sure our final image uses what we just built
+RUN apt-get update
+RUN curl -o phantomjs.tar.gz -L https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.7-linux-x86_64.tar.bz2
+RUN tar -xvf phantomjs.tar.gz
+RUN mv phantomjs-1.9.7-linux-x86_64/bin/phantomjs /usr/bin
+RUN echo "export phantomjs=/usr/bin/phantomjs" > .bashrc
+RUN apt-get install -y libfreetype6 libfontconfig1
+RUN gem install wraith --no-rdoc --no-ri
+RUN gem install aws-sdk --no-rdoc --no-ri
+
+ENTRYPOINT [ "wraith" ]

data/README.md

@@ -11,8 +11,8 @@ Wraith is a screenshot comparison tool, created by developers at BBC News.
 
 ## What is it?
 
-Wraith uses either [PhantomJS](http://phantomjs.org) or
-[SlimerJS](http://slimerjs.org) to create screen-shots of different environments
+Wraith uses either [PhantomJS](http://phantomjs.org), [CasperJS](http://casperjs.org/) or
+[SlimerJS](http://slimerjs.org) to create screen-shots of webpages on different environments
 and then creates a diff of the two images, the affected areas are highlighted in
 blue
 
@@ -22,7 +22,12 @@ diff](http://bbc-news.github.io/wraith/img/320_diff.png)
 
 ## Requirements
 
-Imagemagick and PhantomJS are required to use Wraith, install via your favourite package manager.  To read our detailed instructions for setup and install, as well as example configs, visit [wraith docs](http://bbc-news.github.io/wraith/index.html)
+Imagemagick and PhantomJS are required to use Wraith, install via your favourite package manager. You can also use SlimerJS and CasperJS, CasperJS can be used to target specific selectors. To read our detailed instructions for setup and install, as well as example configs, visit [wraith docs](http://bbc-news.github.io/wraith/index.html)
+
+```sh
+brew install phantomjs  
+brew install imagemagick
+```
 
 ## Installation
 
@@ -69,6 +74,7 @@ There are other commands also available, these all expect a config_name to be pa
   wraith reset_shots [config_name]          # removes all the files in the shots folder
   wraith save_images [config_name]          # captures screenshots
   wraith setup                              # creates config folder and default config
+  wraith setup_casper                       # creates config folder and default config for casper
   wraith setup_folders [config_name]        # create folders for images
 ```
 
@@ -80,11 +86,21 @@ After each screenshot is captured, the compare task will run, this will output a
 
 A gallery is available to view each of the images and the respective diff images located in the shots folder once all the images have been compared.
 
+## CasperJS
+
+There is an example [component config file](https://github.com/BBC-News/wraith/blob/master/configs/component.yaml) which indicates how to target a specific selector on a page.  Pass in a label for the shot, path and selector.  This will be handed to CasperJS and will only screenshot that component on the page.  This is faster way to verify smaller changes to specific components during development.  You must install [CasperJS](http://casperjs.org/) to use.
+
+For a quick setup for CasperJS, you can run :
+
+```sh
+wraith setup_casper
+```
+
 ## History usage
 
 In Wraith 2.0 we introduced a new way for using Wraith in development and testing, historical shots.  Rather than capture 2 domains, you capture 1 domain, probably your local copy of the latest code, then later on after development is in progress, run Wraith again to compare.  This makes working against an isolated dev environment much easier as you wont need an internet connection.  
 
-The usage is different in that you need 1 domain in your config and you will need to set a historical shots folder.  An example of this can be found on Github.  The way this works is that shots are captured as normal with the history command below.  This will create 2 folders with the labels you have specified in the config file, for example, shots and shots_history.  The original shots will be copied into your 'history' folder, then copied back into the shots folder once you have run your latest job.  This workflow will essentially mean your history folder is your baseline, being copied back into the shots folder every time you run the 'latest command'
+The usage is different in that you need 1 domain in your config and you will need to set a historical shots folder.  You will need to specify a `history_dir` in addition to the `directory` key in your `config.yml` file. An example of this can be found in the [`history.yaml`](https://github.com/BBC-News/wraith/blob/31406956bfc465d087f1d40304630e18dc0f857e/configs/history.yaml#L9-L11) file of the `configs` directory of this repository.  The way this works is that shots are captured as normal with the history command below.  This will create 2 folders with the labels you have specified in the config file, for example, shots and shots_history.  The original shots will be copied into your 'history' folder, then copied back into the shots folder once you have run your latest job.  This workflow will essentially mean your history folder is your baseline, being copied back into the shots folder every time you run the 'latest command'
 
 ```sh
 wraith history history.yaml
@@ -95,9 +111,18 @@ wraith latest history.yaml
 ```
 You will now be able to run the latest command over and over without having to do clear up.
 
-## Changelog - updated 2014-09-25
-Wraith 2.0 with new history support, this is a big change for the usage of Wraith, with less dependency on having an Internet connection and capturing two domains.
-A large change in the way file names are made has been introduced into 2.0, with the label of the engine now being used instead of the engine string itself.  This has been updated in all the included configs for reference, but will mean a change to the filenames and urls.  We have also changed the way that folders are loaded from the config, dropping the use of arrays.  This is backward compatible.  
+## Docker
+At BBC, we use Docker and AWS in our workflow.  The Dockerfile is in the repo, but you can pull from the registry here`docker pull bbcnews/wraith`.  There is no quick way to get up and running with OSX and no way to use it on Windows.  For a CI environment, it has a really good use case though.  To run, specify your workspace and the command you want.  If you want to use the Ruby AWS-SDK gem to upload your images to s3, it is built into the container.  I recommend writing a simple ruby script that runs once you have completed a Wraith run.
+
+```sh
+docker run -d bbcnews/wraith -w /wraith -v path/to/dir:/wraith capture configs/config.yaml
+```
+
+## Changelog - updated 2014-10-20
+We have combined CasperJS with Wraith to enable component screen shots and comparison.  This allows for developers to check only a small part of a page for regressions allowing for quicker and smaller screenshots.
+
+
+Notice : We have deprecated the ability to not use labels on URLs in config files and have Wraith create them for you.  Ensure that you update your config with labels before running again.
 
 ## Contributing
 

data/configs/component.yaml

@@ -0,0 +1,45 @@
+#Headless browser option
+browser:
+  phantomjs: "casperjs"
+  # slimerjs: "slimerjs"
+
+#If you want to have multiple snapping files, set the file name here
+snap_file: "lib/wraith/javascript/casper.js"
+
+# Type the name of the directory that shots will be stored in
+directory: 'shots'
+
+# Add only 2 domains, key will act as a label
+domains:
+  russian: "http://www.bbc.co.uk/russian"
+  arabic: "http://www.bbc.co.uk/arabic"
+
+#Type screen widths below, here are a couple of examples
+screen_widths:
+  - 320
+  - 600
+  - 768
+  - 1024
+  - 1280
+
+#Type page URL paths below, here are a couple of examples
+paths:
+  brand:
+    path: /
+    selector: '.site-brand'
+
+#Amount of fuzz ImageMagick will use
+fuzz: '20%'
+
+#Set the filename of the spider file to use, if not specified it will fallback to spider.txt
+# spider_file: bbc_co_uk_spider.txt
+
+#Set the number of days to keep the site spider file
+spider_days:
+  - 10
+
+#Choose how results are displayed, by default alphanumeric. Different screen widths are always grouped.
+#alphanumeric - all paths (with, and without, a difference) are shown, sorted by path
+#diffs_first - all paths (with, and without, a difference) are shown, sorted by difference size (largest first)
+#diffs_only - only paths with a difference are shown, sorted by difference size (largest first)
+mode: diffs_first

data/lib/wraith/cli.rb

@@ -23,6 +23,12 @@ class Wraith::CLI < Thor
     template('javascript/snap.js', 'javascript/snap.js')
   end
 
+  desc 'setup_casper', 'creates config folder and default config for casper'
+  def setup_casper
+    template('configs/component.yaml', 'configs/component.yaml')
+    template('javascript/casper.js', 'javascript/casper.js')
+  end
+
   desc 'reset_shots [config_name]', 'removes all the files in the shots folder'
   def reset_shots(config_name)
     reset = Wraith::FolderManager.new(config_name)

data/lib/wraith/javascript/casper.js

@@ -0,0 +1,20 @@
+var system = require('system');
+var page = require('webpage').create();
+var fs = require('fs');
+var casper = require("casper").create();
+
+var url = casper.cli.get(0);
+var view_port_width = casper.cli.get(1);
+var image_name = casper.cli.get(2);
+var selector = casper.cli.get(3);
+
+casper.start(url, function() {
+  this.viewport(view_port_width, 1500).then(function(){
+    this.wait(2000, function() {
+      this.captureSelector(image_name, selector);
+      console.log('Snapping ' + url + ' at width ' + view_port_width);
+    });
+  });
+});
+
+casper.run();

data/lib/wraith/save_images.rb

@@ -46,9 +46,9 @@ class Wraith::SaveImages
     "#{directory}/#{label}/#{width}_#{engine_label}_#{domain_label}.png"
   end
 
-  def attempt_image_capture(width, url, filename, max_attempts)
+  def attempt_image_capture(width, url, filename, selector, max_attempts)
     max_attempts.times do |i|
-      capture_page_image engine, url, width, filename
+      capture_page_image engine, url, width, filename, selector
 
       return if File.exist? filename
 
@@ -58,13 +58,19 @@ class Wraith::SaveImages
     fail "Unable to capture image #{filename} after #{max_attempts} attempt(s)"
   end
 
+  def has_casper(options)
+    options['path'] ? options['path'] : options
+  end
+
+  def casper_selector(options)
+    options['selector'] ? options['selector'] : ' '
+  end
+
   def save_images
     jobs = []
-    check_paths.each do |label, path|
-      unless path
-        path = label
-        label = path.gsub('/', '__')
-      end
+    check_paths.each do |label, options|
+      path = has_casper(options)
+      selector = casper_selector(options)
 
       base_url = base_urls(path)
       compare_url = compare_urls(path)
@@ -73,17 +79,17 @@ class Wraith::SaveImages
         base_file_name    = file_names(width, label, "#{wraith.base_domain_label}#{history_label}")
         compare_file_name = file_names(width, label, "#{wraith.comp_domain_label}#{history_label}")
 
-        jobs << [label, path, width, base_url,    base_file_name]
-        jobs << [label, path, width, compare_url, compare_file_name] unless compare_url.nil?
+        jobs << [label, path, width, base_url,    base_file_name, selector]
+        jobs << [label, path, width, compare_url, compare_file_name, selector] unless compare_url.nil?
       end
     end
     parallel_task(jobs)
   end
 
   def parallel_task(jobs)
-    Parallel.each(jobs, in_threads: 8) do |_label, _path, width, url, filename|
+    Parallel.each(jobs, in_threads: 8) do |_label, _path, width, url, filename, selector|
       begin
-        attempt_image_capture(width, url, filename, 5)
+        attempt_image_capture(width, url, filename, selector, 5)
       rescue => e
         puts e
 
@@ -101,7 +107,7 @@ class Wraith::SaveImages
     `convert #{image} -background none -extent #{width}x0 #{image}`
   end
 
-  def capture_page_image(browser, url, width, file_name)
-    puts `"#{browser}" "#{wraith.phantomjs_options}" "#{wraith.snap_file}" "#{url}" "#{width}" "#{file_name}"`
+  def capture_page_image(browser, url, width, file_name, selector)
+    puts `"#{browser}" "#{wraith.phantomjs_options}" "#{wraith.snap_file}" "#{url}" "#{width}" "#{file_name}" "#{selector}"`
   end
 end

data/lib/wraith/spider.rb

@@ -57,6 +57,7 @@ class Wraith::Crawler < Wraith::Spider
   def spider
     if File.exist?(@wraith.spider_file) && modified_since(@wraith.spider_file, @wraith.spider_days[0])
       puts 'using existing spider file'
+      @paths = eval(File.read(@wraith.spider_file))
     else
       puts 'creating new spider file'
       spider_list = []

data/lib/wraith/version.rb

@@ -1,3 +1,3 @@
 module Wraith
-  VERSION = '2.0.1'
+  VERSION = '2.1.0'
 end

data/spec/wraith_spec.rb

@@ -3,16 +3,17 @@ require 'image_size'
 require './lib/wraith/cli'
 
 describe Wraith do
-  Given(:config_name) { 'test_config' }
   Given { Wraith::FolderManager.new(config_name).clear_shots_folder }
-  Given(:test_url1) { 'http://www.live.bbc.co.uk/news' }
-  Given(:test_url2) { 'http://www.live.bbc.co.uk/russian' }
   Given { Dir.mkdir('shots/test') }
-  Given(:test_image1) { 'shots/test/test1.png' }
-  Given(:test_image2) { 'shots/test/test2.png' }
-  Given(:diff_image) { 'shots/test/test_diff.png' }
-  Given(:data_txt) { 'shots/test/test.txt' }
-  Given(:saving) { Wraith::SaveImages.new(config_name) }
+  let(:config_name) { 'test_config' }
+  let(:test_url1) { 'http://www.live.bbc.co.uk/news' }
+  let(:test_url2) { 'http://www.live.bbc.co.uk/russian' }
+  let(:test_image1) { 'shots/test/test1.png' }
+  let(:test_image2) { 'shots/test/test2.png' }
+  let(:diff_image) { 'shots/test/test_diff.png' }
+  let(:data_txt) { 'shots/test/test.txt' }
+  let(:selector) { ''}
+  let(:saving) { Wraith::SaveImages.new(config_name) }
 
   When(:wraith) { Wraith::Wraith.new(config_name) }
   Then { wraith.is_a? Wraith::Wraith }
@@ -32,7 +33,7 @@ describe Wraith do
     # capture_page_image
     When do
       wraith.engine.each do |_type, engine|
-        saving.capture_page_image(engine, test_url1, 320, test_image1)
+        saving.capture_page_image(engine, test_url1, 320, test_image1, selector)
       end
     end
     When(:image_size) { ImageSize.path(test_image1).size }
@@ -42,8 +43,8 @@ describe Wraith do
   context 'When comparing images' do
     When(:diff_image_size) do
       wraith.engine.each do |_type, engine|
-        saving.capture_page_image(engine, test_url1, 320, test_image1)
-        saving.capture_page_image(engine, test_url2, 320, test_image2)
+        saving.capture_page_image(engine, test_url1, 320, test_image1, selector)
+        saving.capture_page_image(engine, test_url2, 320, test_image2, selector)
       end
       Wraith::CropImages.new(config_name).crop_images
       Wraith::CompareImages.new(config_name).compare_task(test_image1, test_image2, diff_image, data_txt)
@@ -55,8 +56,8 @@ describe Wraith do
   context 'When generating tumbnails' do
     When do
       wraith.engine.each do |_type, engine|
-        saving.capture_page_image(engine, test_url1, 320, test_image1)
-        saving.capture_page_image(engine, test_url2, 320, test_image2)
+        saving.capture_page_image(engine, test_url1, 320, test_image1, selector)
+        saving.capture_page_image(engine, test_url2, 320, test_image2, selector)
       end
       Wraith::CropImages.new(config_name).crop_images
       Wraith::CompareImages.new(config_name).compare_task(test_image1, test_image2, diff_image, data_txt)

data/templates/configs/component.yaml

@@ -0,0 +1,45 @@
+#Headless browser option
+browser:
+  phantomjs: "casperjs"
+  # slimerjs: "slimerjs"
+
+#If you want to have multiple snapping files, set the file name here
+snap_file: "lib/wraith/javascript/casper.js"
+
+# Type the name of the directory that shots will be stored in
+directory: 'shots'
+
+# Add only 2 domains, key will act as a label
+domains:
+  russian: "http://www.bbc.co.uk/russian"
+  arabic: "http://www.bbc.co.uk/arabic"
+
+#Type screen widths below, here are a couple of examples
+screen_widths:
+  - 320
+  - 600
+  - 768
+  - 1024
+  - 1280
+
+#Type page URL paths below, here are a couple of examples
+paths:
+  brand:
+    path: /
+    selector: '.site-brand'
+
+#Amount of fuzz ImageMagick will use
+fuzz: '20%'
+
+#Set the filename of the spider file to use, if not specified it will fallback to spider.txt
+# spider_file: bbc_co_uk_spider.txt
+
+#Set the number of days to keep the site spider file
+spider_days:
+  - 10
+
+#Choose how results are displayed, by default alphanumeric. Different screen widths are always grouped.
+#alphanumeric - all paths (with, and without, a difference) are shown, sorted by path
+#diffs_first - all paths (with, and without, a difference) are shown, sorted by difference size (largest first)
+#diffs_only - only paths with a difference are shown, sorted by difference size (largest first)
+mode: diffs_first

data/templates/javascript/casper.js

@@ -0,0 +1,20 @@
+var system = require('system');
+var page = require('webpage').create();
+var fs = require('fs');
+var casper = require("casper").create();
+
+var url = casper.cli.get(0);
+var view_port_width = casper.cli.get(1);
+var image_name = casper.cli.get(2);
+var selector = casper.cli.get(3);
+
+casper.start(url, function() {
+  this.viewport(view_port_width, 1500).then(function(){
+    this.wait(2000, function() {
+      this.captureSelector(image_name, selector);
+      console.log('Snapping ' + url + ' at width ' + view_port_width);
+    });
+  });
+});
+
+casper.run();

data/wraith.gemspec

@@ -29,4 +29,5 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'log4r'
   spec.add_runtime_dependency 'thor'
   spec.add_runtime_dependency 'parallel'
+  spec.add_runtime_dependency 'casperjs'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wraith
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Dave Blooman
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-26 00:00:00.000000000 Z
+date: 2014-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pry
@@ -151,6 +151,20 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: casperjs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Wraith is a screenshot comparison tool, created by developers at BBC
   News.
 email:
@@ -165,12 +179,14 @@ files:
 - .gitignore
 - .ruby-version
 - .travis.yml
+- Dockerfile
 - Gemfile
 - LICENSE
 - README.md
 - Rakefile
 - assets/invalid.jpg
 - bin/wraith
+- configs/component.yaml
 - configs/config.yaml
 - configs/config_nojs.yaml
 - configs/history.yaml
@@ -183,6 +199,7 @@ files:
 - lib/wraith/gallery.rb
 - lib/wraith/gallery_template/bootstrap.min.css
 - lib/wraith/gallery_template/gallery_template.erb
+- lib/wraith/javascript/casper.js
 - lib/wraith/javascript/nojs.js
 - lib/wraith/javascript/snap.js
 - lib/wraith/save_images.rb
@@ -191,7 +208,9 @@ files:
 - lib/wraith/version.rb
 - lib/wraith/wraith.rb
 - spec/wraith_spec.rb
+- templates/configs/component.yaml
 - templates/configs/config.yaml
+- templates/javascript/casper.js
 - templates/javascript/snap.js
 - wraith.gemspec
 homepage: https://github.com/BBC-News/wraith