vivisector 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cd1749784defc5a1e9d266f8facd3423f42b4a5e
+  data.tar.gz: ca695ab523abff57b7fd7f2d1673c2b3579245ff
+SHA512:
+  metadata.gz: 6f89aa97f267fc8552d9be9aa2a993a90f896636be4d1831d21fba09ed78b9080146da12c2fa6629c35b3712c0560a07a95bdc96e1ca4697efaeb3029842d31e
+  data.tar.gz: c02b5c7656672f41bbde11059a0f393e786ed249bd68fc30b189ba0d33ad2d37ba2f9d3b595ca05607c2d4cb7789ecdac66d07c5d9b6b82f91dbca3ce94b0e11

data/gem/lib/vivisector/exceptions.rb

@@ -0,0 +1,15 @@
+
+# Vivisector exceptions
+
+module Vivisector
+
+  # For enforcing the use of certain classes even though they may share a base class
+  class IncompatibilityError < TypeError; end
+
+  # For reporting improper extension of the Vivisector base classes (developer error)
+  class ImplementationError < NotImplementedError; end
+
+  # For reporting assertions that fail at runtime (logic errors in extender's code)
+  class OperationalError < RuntimeError; end
+
+end

data/gem/lib/vivisector/filesystem.rb

@@ -0,0 +1,22 @@
+require 'pathname'
+require_relative 'exceptions'
+
+# return true if the other_path is deeper than or equal to the base path
+# http://stackoverflow.com/a/26878510/2063546
+def ancestor?(base, other_path)
+  base_parts = File.expand_path(base).split('/')
+  path_parts = File.expand_path(other_path).split('/')
+  path_parts[0..base_parts.size-1] == base_parts
+end
+
+# return the relative path from a document in a web root to a media element, given full paths to each
+def web_relative_path(web_root, base_document, child_element)
+  c = File.expand_path(child_element)
+  r = File.expand_path(web_root)
+  unless ancestor?(r, c)
+    raise Vivisector::OperationalError, "Child element '#{c}' is not an ancestor of the web root '#{r}'"
+  end
+  base = Pathname.new (File.dirname(File.expand_path(base_document)))
+  elem = Pathname.new c
+  (elem.relative_path_from base).to_s
+end

data/gem/lib/vivisector/image.rb

@@ -0,0 +1,19 @@
+
+module Vivisector
+
+  # A simple container for image information
+  class Image
+    attr_accessor :path         # the location on disk
+    attr_accessor :id           # an application-specific unique identifier
+    attr_accessor :description  # a friendly description
+  end
+
+
+  # Design images may optionally specify an attribute
+  class DesignImage < Image
+    attr_accessor :attribute
+  end
+
+  # App images are the same as images, but create this alias for symmetry / clarity
+  class AppImage < Image; end
+end

data/gem/lib/vivisector/imageloader.rb

@@ -0,0 +1,60 @@
+
+class ImageLoader
+
+  attr_reader :image_set
+
+  def initialize
+    @image_set = nil  # the image set for this loader
+
+  end
+
+  def load
+    image_set = self.fetch_image_set
+    self.allow_image_set image_set
+    @image_set = image_set
+  end
+
+  # implementation-specific: return a filled ImageSet
+  def fetch_image_set
+    puts "  +++ If you're seeing this, #{self.class.name}.#{__method__} was not overridden"
+  end
+
+  # implementation-specific: verify that an ImageSet is appropriate
+  def allow_image_set image_set
+    puts "  +++ If you're seeing this, #{self.class.name}.#{__method__} was not overridden"
+  end
+
+end
+
+
+module Vivisector
+
+  class Anatomy < ImageLoader
+
+    def initialize
+      super
+      @order = []      # will hold the sorted indexes into the image set array
+    end
+
+    def allow_image_set image_set
+      raise ImplementationError, "Got a nil DesignImageSet object; was #{self.class.name} properly extended?" if image_set.nil?
+
+      # Ensure that we are only looking at design images
+      raise IncompatibilityError, "Tried to add a non- DesignImageSet object to Anatomy" unless image_set.is_a? DesignImageSet
+    end
+
+  end
+
+
+  class Appography < ImageLoader
+
+    def allow_image_set image_set
+      raise ImplementationError, "Got a nil DesignImageSet object; was #{self.class.name} properly extended?" if image_set.nil?
+
+      # Ensure that we are only looking at implementation images
+      raise IncompatibiltyError, "Tried to add a DesignImageSet object to Appography" if image_set.is_a? DesignImageSet
+    end
+
+  end
+
+end

data/gem/lib/vivisector/imageset.rb

@@ -0,0 +1,119 @@
+
+module Vivisector
+
+  # Container class for sets of images
+  class ImageSet
+
+    attr_reader :images  # the container for all the images in the set
+
+    def initialize
+      @images = []
+      @cache_valid = false  # cache invalidation is so easy
+    end
+
+    # Safe way to add images to the container
+    def add image
+      self.allow image
+      # fix relative paths
+      image.path = File.expand_path(image.path)
+      @images << image
+      @cache_valid = false
+      nil
+    end
+
+    # Raise an error if the image is not appropriate for this type of set
+    def allow image
+      puts "  +++ If you're seeing this, #{self.class.name}.#{__method__} was not overridden"
+    end
+  end
+
+
+  # Design image sets need to be able to report on the images they contain
+  class DesignImageSet < ImageSet
+
+    def allow image
+      # Ensure that image objects have an "attribute" field, among other things
+      raise IncompatibilityError, "Tried to add a non- DesignImage object to a DesignImageSet" unless image.is_a? DesignImage
+
+      # no duplicates allowed
+      if (@images.map { |i| [i.id, i.attribute] }).include? [image.id, image.attribute]
+        raise OperationalError, "Tried to add an image with duplicate ID and attribute"
+      end
+    end
+
+    # Get the list of unique attributes contained by the images within
+    def contained_attributes
+      (@images.map { |i| i.attribute}).uniq
+    end
+
+    # cache the image attributes
+    def cache_image_attributes
+      return if @cache_valid
+
+      # make a hash -- hash[image id] = list of attributes defined for this image id
+      # we use this for convenience later
+      @attributes_by_id = {}
+      @images.each do |img|
+        proper_key = img.id.to_s
+        @attributes_by_id[proper_key] = [] unless @attributes_by_id.has_key? proper_key
+        @attributes_by_id[proper_key] << img.attribute
+      end
+
+      @cache_valid = true
+    end
+
+    # get the list of images that are valid for a particular attribute
+    def images_for_attribute attribute
+      self.cache_image_attributes
+
+      # return the pared-down list
+      @images.select do |img|
+        # this covers nil == nil and attribute == attribute
+        next true if img.attribute == attribute
+
+        # if there is no attribute for this image, it should be pulled in
+        #        ... unless there's an exact match elsewhere in the set.
+        next true if img.attribute.nil? unless @attributes_by_id[img.id.to_s].include? attribute
+
+        false
+      end
+    end
+
+  end
+
+
+  # App image sets are tied to a target
+  class AppImageSet < ImageSet
+
+    attr_accessor :target
+
+    def allow image
+      # no duplicates
+      if (@images.map { |i| i.id}).include? image.id
+        raise OperationalError, "Tried to add an image with duplicate ID"
+      end
+
+      # App image sets don't need to worry about specific fields, but we keep it clean and symmetric.
+      raise IncompatibilityError, "Tried to add a DesignImage object to a non- DesignImageSet" if image.is_a? DesignImage
+    end
+
+    def cache_image_lookups
+      return if @cache_valid
+
+      @image_lookup = {}
+      @images.each do |img|
+        @image_lookup[img.id.to_s] = img
+      end
+
+      @cache_valid = true
+    end
+
+    def best_image_for(id)
+      self.cache_image_lookups
+      @image_lookup.fetch(id.to_s, nil)
+    end
+
+  end
+
+
+end

data/gem/lib/vivisector/report.rb

@@ -0,0 +1,110 @@
+require 'markaby'
+require_relative 'filesystem'
+
+module Vivisector
+
+  class Report
+    attr_accessor :title
+    attr_accessor :attribute
+    attr_accessor :anatomy
+    attr_accessor :appographies
+    attr_accessor :web_document_root
+    attr_accessor :destination_path
+    attr_accessor :img_width_px
+
+    def css
+      width_string = ""
+      width_string = "width: #{@img_width_px}px;" unless img_width_px.nil?
+      %(
+        body {color:white; background-color:#333;}
+        table.comparison th {border-top: 1px solid #ccc;}
+        table.comparison td {padding-bottom:1ex; text-align:center;}
+        .masterimg, .appimg {background-color:white; #{width_string}}
+        .missing {white-space: pre; text-align:center;}
+       )
+    end
+
+    # if necessary, modify the path to be relative (for web-based reports)
+    def path_transform element_path
+      unless @web_document_root.nil?
+        element_path = web_relative_path(@web_document_root, @destination_path, element_path)
+      end
+      element_path
+    end
+
+    def to_s
+      # initial calculations
+      candidates = @appographies.select do |appog|
+        next true if @attribute.nil? # unless there is nothing in this candidate???? might be expensive to check.
+
+        appog.image_set.target.attribute == @attribute
+      end
+      design_images = @anatomy.image_set.images_for_attribute(@attribute)
+      columns = candidates.length + 1
+
+      me = self
+
+      # build html
+      mab = Markaby::Builder.new
+      mab.html do
+
+        head do
+          title "#{me.title} | Vivisector"
+          style :type => "text/css" do
+            me.css
+          end
+        end
+
+        body do
+          h1 me.title
+          if design_images.empty?
+            p "No input images were found."
+          else
+            table.comparison do
+              # print out the first row of the table -- the target names
+              tr do
+                td "Design"
+                candidates.each do |c|
+                  td c.image_set.target.name
+                end
+              end
+
+              # print out all the compared images
+              design_images.each do |design_image|
+                # title
+                tr do
+                  th :colspan => columns do
+                    a :name => design_image.description do
+                      design_image.description
+                    end
+                  end
+                end
+
+                # images
+                tr do
+                  td :align => "right", :valign => "top" do
+                    img.masterimg :src => me.path_transform(design_image.path), :alt => design_image.description
+                  end
+
+                  candidates.each do |candidate|
+                    app_image = candidate.image_set.best_image_for(design_image.id)
+                    if app_image.nil?
+                      td { div.missing "#{design_image.description} on #{candidate.image_set.target.name}" }
+                    else
+                      td :align => "left", :valign => "top" do
+                        div.holder { img.appimg :src => me.path_transform(app_image.path), :alt => app_image.description }
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+      return mab.to_s
+    end
+
+  end #Report
+
+end

data/gem/lib/vivisector/reportset.rb

@@ -0,0 +1,45 @@
+require_relative 'filesystem'
+
+module Vivisector
+
+  class ReportSet
+    attr_accessor :anatomy
+    attr_accessor :appographies
+    attr_accessor :title_for_attribute_fn
+    attr_accessor :path_for_attribute_fn
+    attr_accessor :web_document_root
+    attr_accessor :img_width_px
+
+    # Check whether the path is correct, particularly if we are making a web-based report
+    def allow_path path
+      unless @web_document_root.nil?
+        unless ancestor?(@web_document_root, path)
+          raise OperationalError, "Report #{path} is not an ancestor of the web root #{@web_document_root}"
+        end
+      end
+    end
+
+    def write
+      @anatomy.image_set.contained_attributes.map do |attr|
+
+        # first check whether the destination is ok
+        path = @path_for_attribute_fn.call(attr)
+        self.allow_path path
+
+        r = Report.new
+        r.title             = @title_for_attribute_fn.call(attr)
+        r.attribute         = attr
+        r.anatomy           = @anatomy
+        r.appographies      = @appographies
+        r.web_document_root = @web_document_root
+        r.destination_path  = path
+        r.img_width_px      = @img_width_px
+
+        File.open(path, 'w') {|f| f.write(r.to_s) }
+      end
+    end
+
+  end
+
+
+end #Vivisector

data/gem/lib/vivisector/target.rb

@@ -0,0 +1,9 @@
+
+module Vivisector
+
+  class Target
+    attr_accessor :name       # the friendly name of this target
+    attr_accessor :attribute  # the attribute that this target can have
+  end
+
+end

data/gem/lib/vivisector/version.rb

@@ -0,0 +1,3 @@
+module Vivisector
+  VERSION = "0.1.0"
+end

data/gem/lib/vivisector.rb

@@ -0,0 +1,40 @@
+require 'vivisector/version'
+
+require 'vivisector/exceptions'
+require 'vivisector/target'
+require 'vivisector/image'
+require 'vivisector/imageset'
+require 'vivisector/imageloader'
+require 'vivisector/report'
+require 'vivisector/reportset'
+
+
+module Vivisector
+
+  def self.report(anatomy, appographies, title_for_attribute_fn, path_for_attribute_fn, web_document_root, img_width_px)
+    # load source images
+    anatomy.load
+    appographies.each { |appog| appog.load }
+
+    unless web_document_root.nil?
+      appographies.each do |appog|
+        # if the path isn't within web_document_root, throw
+      end
+
+      # copy all images to an images/ directory inside web_document_root
+      # mangle all image sets to point to there
+      # use dirnames like "images/design", "images/target1", "images/target2", etc
+    end
+
+    rs = Vivisector::ReportSet.new
+    rs.anatomy                = anatomy
+    rs.appographies           = appographies
+    rs.title_for_attribute_fn = title_for_attribute_fn
+    rs.path_for_attribute_fn  = path_for_attribute_fn
+    rs.web_document_root      = web_document_root
+    rs.img_width_px           = img_width_px
+
+    rs.write
+  end
+
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: vivisector
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ian Katz
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-05-28 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'
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 1.3.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 1.3.6
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: markaby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+description: Vivisector helps you see inside your apps, specifically so that designers
+  can be part of a QA / Continuous Integration process. It's a framework to help you
+  compare design 'master' images to actual screenshots from various implementations.
+email:
+- ifreecarve@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- gem/lib/vivisector.rb
+- gem/lib/vivisector/exceptions.rb
+- gem/lib/vivisector/filesystem.rb
+- gem/lib/vivisector/image.rb
+- gem/lib/vivisector/imageloader.rb
+- gem/lib/vivisector/imageset.rb
+- gem/lib/vivisector/report.rb
+- gem/lib/vivisector/reportset.rb
+- gem/lib/vivisector/target.rb
+- gem/lib/vivisector/version.rb
+homepage: http://github.com/ifreecarve/vivisector
+licenses:
+- Apache 2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- gem/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.4.6
+signing_key: 
+specification_version: 4
+summary: Design QA tool
+test_files: []