dmc_kanye 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8221b03c8ffdc2903f174bdf1e1a2c52634d4546
+  data.tar.gz: 4c776783243f78b3d149af99cd99affd4160bee4
+SHA512:
+  metadata.gz: 3e96f9ec2901df52ad84db94536150545cab9115ce3f07c3fb95b0ad935e9fe4e5ed1947faa0d2cd0ec0cb95dc5b34a766e626c494846ccea8bb1e6a10fd5795
+  data.tar.gz: b7cdc5e08ec2ca3dc166415924f1aa73a1c9d226cd14d511fde51b5444a5bfb5a373a5d7fd207570ea51df288e72571d304852e537c54c6e60621ead7fc69de6

data/.gitignore

@@ -0,0 +1,35 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing
+
+If you want to contribute to Dmc_Kanye, the usual steps apply:
+
+* Fork the repo
+* Start a new branch (we favor branch names with your name or initials, e.g. `pjm/my_feature_branch`)
+* Make your changes (tested changes are much appreciated)
+* Open a pull request
+
+Regular contributors may be given "commit bit".

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,17 @@
+PATH
+  remote: .
+  specs:
+    dmc_kanye (0.0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    rake (10.4.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.9)
+  dmc_kanye!
+  rake (~> 10.0)

data/README.md

@@ -0,0 +1,120 @@
+# Kanye
+
+Kanye improves Capybara's synchronization algorithm by letting the browser finish before the test keeps going.  By doing this, Kanye also helps you tailor the swiftness of your feature specs.
+
+
+
+## How Kanye Works
+
+When a Capybara test is run with a JavaScript driver, the two processes can easily get out of sync which causes intermittent, difficult-to-reproduce test failures.
+
+### How Timing Failures Happen
+
+For example, imagine a feature where a user clicks a "details" button, which causes a pane to slide down containing the extra information.  The Capybara test may want to:
+
+  * click the details button
+  * expect that "foo bar baz" is showing in the details pane
+
+The Ruby process will apply the expectation immediately after clicking the button; however, the browser may need some time to:
+
+  * send an ajax request to the server to fetch the details
+  * do a fancy slide-down animation
+
+Since the details wouldn't be visible yet, the Cabybara test will fail.
+
+### A Stupid Way to Solve Timing Failures
+
+You could simply `sleep 20` after every single command you send to the browser, which should give it plenty of time to finish whatever it is doing and catch up to the Ruby process.
+
+Obviously, this would make the tests unbearably slow, so a good solution to timing failures should balance speed and robustness well.
+
+### Capybara's Approach to Timing Issues
+
+Capybara's way of solving timing issues, [which can be found here in its code](https://github.com/jnicklas/capybara/blob/2.4.4/lib/capybara/node/base.rb#L43), is basically this:
+
+  * Just do everything as if timing issues don't exist.
+  * If we do X and  get a `Capybara::ElementNotFound` error, it could be because the browser has not caught up to the Ruby process.  In this case, wait for the browser to catch up like so:
+    * Sleep for 0.05 seconds.
+    * Do X again.
+    * If X succeeds you are done.
+    * If X fails, try again.
+    * Repeat until `Capybara.default_wait_time` seconds have passed.
+
+### Some Problems with Capybara's Approach
+
+**The "Does Not Exist" Gotcha** -- `!page.has_css?('.error-notice')`, while intuitive to write, will lead to an incorrectly written test. [Read more here.](https://github.com/jnicklas/capybara#asynchronous-javascript-ajax-and-friends)
+
+**JavaScript Bleeding** -- it's possible that the browser is still executing some leftover ajax or other JavaScript after one test example has ended and during the execution of a new test example.  While this rarely happens, when it does, it is very hard to troubleshoot the cause.
+
+**Slower Specs** -- every time we have an example that expects an element to *not* be present, it is forced to wait the entire `Capybara.default_wait_time`.  As the number of spec examples grow, this adds up.  You can't simply choose a very small `Capybara.default_wait_time`, because this will lead to instability of test results.
+
+### Kanye's Approach to Timing Issues
+
+Kanye's strategy is, instead of sleeping and waiting for things to happen, to take more control.  This will lead to tests that are *both* faster and more robust.
+
+It's easiest to think of Kanye as a wrapper.  Every single time the browser is asked to do X, it is wrapped like this:
+
+  * Imma let you finish
+  * now do X
+  * Imma let you finish
+
+"Imma let you finish" means that Kanye closely watches the browser for indications that it is busy, waiting until it is finished before allowing the Capybara process to continue.
+
+More specifically, Kanye does the following:
+
+  * waits for all ajax to complete
+  * if the browser URL has changed, triggers some JavaScript code that disables all transitions on the page
+
+That last point is important to note.  Transitions (CSS transitions, jQuery transitions, etc.) take time, which causes the Capybara process to get ahead of the browser process.  There is no reliable way to know whether the browser is currently running any transitions, so the strategy is to disable them.  Take note of two things:
+
+  * you have to supply the JavaScript code snippet that disables transitions
+  * this means the test is not totally "pure" since it is disabling some production code (transitions)
+
+
+
+## Basic Usage
+
+### Setup
+
+Kanye requires poltergeist and jQuery.
+
+Add Kanye to your gemfile (if you have a test group, you can put it there):
+
+    gem 'dmc_kanye'
+
+Require Kanye in your spec_helper.rb:
+
+    require 'dmc_kanye'
+
+Configure Kanye with JavaScript that will disable transitions:
+
+    DmcKanye::Config.script_to_disable_transitions = "(typeof jQuery === 'undefined') ? false : jQuery('.fade').removeClass('fade')"
+
+Kanye can't predict which kind of transitions you will use or how to disable them, so you have to supply the JavaScript that will disable transitions.  This transition-disabling JavaScript is executed on the browser every time the browser URL changes.
+
+Set Capybara's wait time lower to speed up your specs:
+
+    Capybara.default_wait_time = 0.5
+
+Configure Kanye's default wait time:
+
+    DmcKanye::Config.default_wait_time = 0.5
+
+The Kanye default wait time will be used when poltergeist is active (meaning :js => true for that spec).  Otherwise, you will be using the Rack::Test driver which will use the Capybara default wait time.  Because Kanye keeps a more controlled watch on what the browser is doing, there is less guess-work and so Kanye's default wait time can be lower than Capybara's.
+
+### Usage in Specs
+
+You generally don't have to think about timing issues as you write your specs.  Even if you are writing a spec that makes sure an error message does not appear, Kanye will be waiting for the ajax to finish so you don't have to do anything special in your spec.
+
+However, there are a couple of situations that may confuse Kanye:
+
+  * you have a complex JavaScript chain of events started by an ajax completion event (for example, ajax that reloads the current page when completing)
+  * anytime the browser is busy for longer than `Capybara.default_wait_time` and the page has already finished loading and all ajax has completed (for example, you have a JavaScript function that walks the dom and does something very time-consuming to each element)
+
+In those (hopefully rare) situations, it is recommended that you write your own code into that test to deal with the timing issue, even if it ends up being a dumb `sleep` statement.  Kanye provides some [helper methods](driver_helpers.rb) to make your job easier and help you avoid those `sleep` statements.
+
+## A note about the name
+
+There are more than a few "Kanye" gems in the world already, but the name was just too good to pass up. For open-source release, Kanye has been "namespaced" with the company where it was originally developed, [The District Management Council][1].
+
+[1]: http://dmcouncil.org/

data/Rakefile

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

data/TODO.md

@@ -0,0 +1,4 @@
+# DMC-Kanye TODO
+
+* [ ] Tests! (How meta...)
+* [ ] Publish to Rubygems

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "dmc_kanye"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/dmc_kanye.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'dmc_kanye/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "dmc_kanye"
+  spec.version       = DmcKanye::VERSION
+  spec.authors       = ["Wyatt Greene", "Parker Morse"]
+  spec.email         = ["pmorse@dmcouncil.org"]
+  spec.licenses      = ['MIT']
+  spec.homepage      = 'https://github.com/dmcouncil/dmc_kanye'
+
+  spec.summary       = %q{Imma let your AJAX finish, but these are the best feature tests of ALL TIME.}
+  spec.description   = %q{Kanye improves Capybara's synchronization algorithm by letting the browser finish before the test keeps going. By doing this, Kanye also helps you tailor the swiftness of your feature specs.}
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.9"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/lib/dmc_kanye/config.rb

@@ -0,0 +1,6 @@
+module DmcKanye
+  class Config
+    class_attribute :script_to_disable_transitions
+    class_attribute :default_wait_time
+  end
+end

data/lib/dmc_kanye/driver_helpers.rb

@@ -0,0 +1,79 @@
+module DmcKanye
+
+  class TimeoutException < RuntimeError; end
+
+  module DriverHelpers
+
+    # If the browser is waiting for ajax or loading a page, Kanye is smart
+    # enough to deal with this.  However, if the browser is busy doing something
+    # else for a significant period of time (such as long-running JavaScript),
+    # Kanye is not smart enough to know that there is something that needs
+    # finishing.
+    #
+    # So basically, in the very rare cases that Kanye cannot detect that something
+    # needs to be waited for, you can explicitly wait for a DOM element to
+    # appear, for example:
+    #
+    #   wait_to_appear(:css, '.ui-autocomplete.ui-menu')
+    #
+    # This will wait up to the poltergeist timeout value (which is probably
+    # 30 seconds) for this DOM element to appear before moving on.  If the
+    # DOM element does not appear, an error is thrown.
+    #
+    def wait_to_appear(method, selector)
+      seconds = 0
+      while find(method, selector).nil?
+        seconds += 0.2
+        raise TimeoutException if seconds > timeout
+        sleep 0.2
+      end
+    end
+
+    def open_ajax_requests?
+      !evaluate_script("(typeof jQuery === 'undefined') ? 0 : jQuery.active").zero?
+    rescue Capybara::NotSupportedByDriverError
+      false
+    end
+
+    def page_loaded?
+      evaluate_script("document.readyState") == "complete"
+    rescue Capybara::NotSupportedByDriverError
+      true
+    end
+
+    def wait_for_page_to_finish_loading
+      seconds = 0
+      while !page_loaded?
+        seconds += 0.02
+        raise TimeoutException if seconds > timeout
+        sleep 0.02
+      end
+    end
+
+    def wait_for_in_progress_ajax_to_finish
+      seconds = 0
+      while open_ajax_requests?
+        seconds += 0.05
+        raise TimeoutException if seconds > timeout
+        sleep 0.05
+      end
+    end
+
+    def wait_for_page_to_settle
+      if !page_loaded?
+        wait_for_page_to_finish_loading
+        wait_for_page_to_settle
+      end
+      if open_ajax_requests?
+        wait_for_in_progress_ajax_to_finish
+        wait_for_page_to_settle
+      end
+    end
+  end
+end
+
+module Capybara::Poltergeist
+  class Driver < Capybara::Driver::Base
+    include DmcKanye::DriverHelpers
+  end
+end

data/lib/dmc_kanye/duck_punching_insurance.rb

@@ -0,0 +1,15 @@
+require 'capybara'
+require 'capybara/poltergeist'
+require 'capybara/poltergeist/version'
+
+unless Capybara::VERSION == "2.4.4"
+  raise "Kanye specifically monkey-patched version 2.4.4 of Capybara. "\
+        "You have version #{Capybara::VERSION}. "\
+        "Please upgrade the monkey patches along with the gem."
+end
+
+unless Capybara::Poltergeist::VERSION == "1.5.1"
+  raise "Kanye specifically monkey-patched version 1.5.1 of Poltergeist. "\
+        "You have version #{Capybara::Poltergeist::VERSION}. "\
+        "Please upgrade the monkey patches along with the gem."
+end

data/lib/dmc_kanye/imma_let_you_finish.rb

@@ -0,0 +1,101 @@
+module Capybara::Poltergeist
+  class Driver < Capybara::Driver::Base
+
+    # allows Capybara to have different behaviors depending on whether
+    # the current driver includes Kanye's algorithm
+    def kanye_invited?
+      true
+    end
+
+  private
+
+    def imma_let_you_finish
+      wait_for_in_progress_ajax_to_finish
+      disable_transitions_if_new_page
+    end
+
+    def remove_transitions
+      if DmcKanye::Config.script_to_disable_transitions.present?
+        evaluate_script DmcKanye::Config.script_to_disable_transitions
+      end
+    rescue Capybara::NotSupportedByDriverError
+      false
+    end
+
+    # if we are on a new page, run some JavaScript that attempts to disable
+    # any JS/CSS transitions that would cause the browser process to get out of
+    # sync with the Capbyara test process
+    def disable_transitions_if_new_page
+      @__current_url = current_url
+      if @__current_url != @__previous_url
+        wait_for_page_to_finish_loading
+        remove_transitions
+      end
+      @__previous_url = @__current_url
+    end
+
+  end
+end
+
+##### VIOLENT DUCK PUNCHING AHEAD
+#
+# Here we have overridden the behavior of a method in Capybara.  The part
+# that we added is highlighted below to make it easier when upgrading
+# to a future version of Capybara.
+
+##### THIS CODE IS ORIGINAL
+module Capybara
+  module Node
+    class Base
+##### START PUNCHING DUCKS
+# orig code:
+#       def synchronize(seconds=Capybara.default_wait_time, options = {})
+# new code:
+      def synchronize(seconds = nil, options = {})
+        kanye_in_the_house = session.driver.respond_to?(:kanye_invited?) && session.driver.kanye_invited?
+        if seconds
+          seconds_to_wait = seconds
+        elsif kanye_in_the_house
+          seconds_to_wait = DmcKanye::Config.default_wait_time || Capybara.default_wait_time
+        else
+          seconds_to_wait = Capybara.default_wait_time
+        end
+##### STOP PUNCHING DUCKS, BACK TO ORIGINAL CODE
+        start_time = Time.now
+
+        if session.synchronized
+          yield
+        else
+          session.synchronized = true
+          begin
+##### START PUNCHING DUCKS
+# orig code:
+#            yield
+# new code:
+            session.driver.send(:imma_let_you_finish) if kanye_in_the_house
+            result = yield
+            session.driver.send(:imma_let_you_finish) if kanye_in_the_house
+            result
+##### STOP PUNCHING DUCKS, BACK TO ORIGINAL CODE
+          rescue => e
+            session.raise_server_error!
+            raise e unless driver.wait?
+            raise e unless catch_error?(e, options[:errors])
+##### START PUNCHING DUCKS
+# orig code:
+#            raise e if (Time.now - start_time) >= seconds
+# new code:
+            raise e if (Time.now - start_time) >= seconds_to_wait
+##### STOP PUNCHING DUCKS, BACK TO ORIGINAL CODE
+            sleep(0.05)
+            raise Capybara::FrozenInTime, "time appears to be frozen, Capybara does not work with libraries which freeze time, consider using time travelling instead" if Time.now == start_time
+            reload if Capybara.automatic_reload
+            retry
+          ensure
+            session.synchronized = false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dmc_kanye/version.rb

@@ -0,0 +1,3 @@
+module DmcKanye
+  VERSION = "0.0.1"
+end

data/lib/dmc_kanye.rb

@@ -0,0 +1,8 @@
+raise "Kanye is not allowed in this environment." unless Rails.env.test?
+
+require "dmc_kanye/version"
+
+require_relative 'dmc_kanye/duck_punching_insurance'
+require_relative 'dmc_kanye/config'
+require_relative 'dmc_kanye/driver_helpers'
+require_relative 'dmc_kanye/imma_let_you_finish'

data/license.txt

@@ -0,0 +1,8 @@
+The MIT License (MIT)
+Copyright (c) 2016 The District Management Council
+
+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.

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: dmc_kanye
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Wyatt Greene
+- Parker Morse
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-01-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !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'
+description: Kanye improves Capybara's synchronization algorithm by letting the browser
+  finish before the test keeps going. By doing this, Kanye also helps you tailor the
+  swiftness of your feature specs.
+email:
+- pmorse@dmcouncil.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- CONTRIBUTING.md
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- TODO.md
+- bin/console
+- bin/setup
+- dmc_kanye.gemspec
+- lib/dmc_kanye.rb
+- lib/dmc_kanye/config.rb
+- lib/dmc_kanye/driver_helpers.rb
+- lib/dmc_kanye/duck_punching_insurance.rb
+- lib/dmc_kanye/imma_let_you_finish.rb
+- lib/dmc_kanye/version.rb
+- license.txt
+homepage: https://github.com/dmcouncil/dmc_kanye
+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.2.2
+signing_key: 
+specification_version: 4
+summary: Imma let your AJAX finish, but these are the best feature tests of ALL TIME.
+test_files: []