hypercuke 0.4.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2df7dbaea6ea4f5665a5f0e698e677f27fa3d9fd
+  data.tar.gz: 1334aa38a72f29866cff7c844808b59454809a00
+SHA512:
+  metadata.gz: 8e8ac55bd1d0e6773d148aa7e949904a1c90b171ce6b01e26e48dc40969386b46e317a69fc8ea2f5fe0922304576884ce99dd9ef334fcc289b2edddf2e8c0111
+  data.tar.gz: ee444352aaef8664bd45206b3485c60402cbb31754033446d8f9526805b1e1d9597952383c7267ef4b5a4feb450ee9fed452542ee76c4ed2308b32f7f1afa7f2

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+private_tasks.rake

data/.rspec

@@ -0,0 +1 @@
+--color --order random

data/.ruby-gemset

@@ -0,0 +1 @@
+hypercuke

data/.ruby-version

@@ -0,0 +1 @@
+ruby-1.9.3-p484

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Sam Livingston-Gray
+
+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,142 @@
+# Hypercuke
+
+Hypercuke helps you use Cucumber to do BDD at multiple layers of your
+application, and gently nudges you into writing your scenarios in
+high-level terms that your users can understand.
+
+## Why?
+
+Because TATFT.
+
+### Okay, But Why Cucumber?
+
+Cucumber is a great way to write acceptance tests that are also, by
+definition, integration tests.  Each scenario defines a "walking
+skeleton" (I've also heard "tracer bullet") -- one complete path through
+the system from top to bottom, describing one feature that an end user
+actually cares about.
+
+### So Why Doesn't Everyone Do This Already?
+
+The traditional Rails approach of using Cucumber to test an app from a
+browser has some pitfalls:
+
+* In the short term, sometimes there's a LOT of new functionality to
+  define, and you spend days or weeks just getting one scenario to pass.
+  This can suck the morale right out of you.
+
+More importantly, Cucumber has some long-term pitfalls:
+
+* Having all your tests fire up a web browser and exercise the web
+  application gets really really slow (especially when every! single!
+  test! starts with "Given I am logged in as a normal user").
+
+* More subtly, the implicit assumption that "Cucumber ==> web browser"
+  makes it too easy for knowledge of the web UI to creep into tests --
+  and, as the Cucumber community has already learned (see <a
+  href="http://aslakhellesoy.com/post/11055981222/the-training-wheels-came-off">The
+  Training Wheels Came Off</a>), this can lead to slow, brittle tests.
+
+* Cucumber tutorials tend to show you step definitions that combine a
+  regular expression with an associated block of code.  Then they say
+  "TADA!" and wander off, leaving users with the impression that *that's
+  where all their code is supposed to go*.  Because everything is in a
+  flat namespace, this tends to turn into... well, PHP.  I've seen
+  projects with thousands of lines of horrible procedural code in deeply
+  interdependent step definitions that resist refactoring.  In one
+  particularly memorable instance, I actually helped write a 50-line
+  step definitions with a parameter named "destroy_the_earth".
+
+### Why Hypercuke?
+
+Hypercuke's core idea is a clever way of using Cucumber tags.  By
+swapping out different adapters for your step definitions, you can write
+a scenario once, tag it appropriately, and then execute that scenario to
+test any or all of:
+
+* a fast core layer of plain old Ruby objects,
+* ActiveRecord models,
+* some <a
+  href="http://brewhouse.io/blog/2014/04/30/gourmet-service-objects.html">Gourmet
+  Service Objects</a>,
+* an API if you have one,
+* the UI,
+* or any other layer that's meaningful to you.
+
+Hypercuke directly addresses each of the pain points described above:
+
+* By starting off at a low layer, you can use your Cucumber scenario as
+  a short-span integration test that's just wrapped around a few simple
+  objects.  Once you're satisfied with how that works, you can move up
+  to a higher level of abstraction.  If a scenario is a "walking
+  skeleton", Hypercuke lets you start by building the skeleton just up
+  to the knees, then up to the spine, and so on.
+
+* Just because your tests are in Cucumber doesn't mean they have to be
+  slow.  I originally developed Cucumber because I wanted to describe
+  all of my features using Gherkin, but only test one or two scenarios
+  through a web browser.  Scenarios to describe boundary cases,
+  exceptions, or variations can run against a lower layer of the
+  application, which can have as much or as little overhead as makes
+  sense for each scenario.
+
+* Because my scenarios might run at varying levels of abstraction, I
+  write them in interface-agnostic language.  (For example, I'll write
+  "I view the list of widgets" instead of "I go to /widgets".)  And if I
+  forget, the cognitive dissonance when I write the step definitions
+  very quickly reminds me to use more generic language.  This helps me
+  write tests at a high level of abstraction, and it also helps keep me
+  focused on *why* I'm writing this feature, so I don't get lost
+  building a gold-plated automated yak-shaving factory.
+
+* Finally, Hypercuke provides *just enough* structure for you to write
+  reusable step definitions.  Inside the regular-expression-plus-block
+  that Cucumber gives you, you write the bare minimum amount of code you
+  need to translate from Gherkin into a Ruby message, and then you send
+  that message to a step adapter that does the work.  Step adapters are
+  Ruby objects, which means you can use all of your Ruby fu to keep your
+  code organized.
+
+## How?
+
+TODO: continue here :D
+
+## About the Name
+
+I started out with the concept of "layers", so this gem was originally
+going to be called "cucumber-parfait".  But as I worked through it, I
+kept visualizing things using two-dimensional matrices, which kept
+moving around in my brain as I thought about them... and that reminded
+me of visualizations of a hypercube.  Ergo, Hypercuke.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'hypercuke'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hypercuke
+
+## Usage
+
+Obviously I have some more writing to do, but you'll need to add this
+line somewhere in your application's Cucumber environment (this is
+usually somewhere in /features/support/):
+
+    require 'hypercuke/cucumber_integration'
+
+TODO: Write more detailed usage instructions
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/hypercuke/fork )
+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 a new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc 'Run specs'
+RSpec::Core::RakeTask.new do |t|
+  # Put spec opts in a file named .rspec in root
+end
+

data/bin/hcu

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+# Make sure we can get to hypercuke on the load path
+unless $:.any? {|path| path =~ /hypercuke\/lib/ }
+  lib_path = File.expand_path( File.join( File.dirname(__FILE__), *%w[.. lib] ) )
+  $:.unshift(lib_path) 
+end
+
+# Load the gem
+begin
+  require 'hypercuke'
+rescue LoadError
+  require 'rubygems' # worth a shot before just dying
+  require 'hypercuke'
+end
+
+# Hand the Hypercuke command off to the CLI, which will parse and
+# Kernel#exec the appropriate Cucumber command
+Hypercuke::CLI.exec ARGV, output_to: STDOUT

data/hypercuke.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hypercuke/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "hypercuke"
+  spec.version       = Hypercuke::VERSION
+  spec.authors       = ["Sam Livingston-Gray"]
+  spec.email         = ["sam.livingstongray@livingsocial.com"]
+  spec.summary       = %q{Run Cucumber scenarios at multiple layers of your application.}
+  spec.description   = %q{Hypercuke helps you use Cucumber to do BDD at multiple layers of your application, and gently nudges you into writing your scenarios in high-level terms that your users can understand.}
+  spec.homepage      = "https://github.com/livingsocial/hypercuke"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  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_runtime_dependency "cucumber", "~> 1.3"
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 3.0.0"
+
+  spec.add_development_dependency 'geminabox' # TODO: remove this when publishing
+end

data/lib/hypercuke.rb

@@ -0,0 +1,43 @@
+require 'hypercuke/version'
+require 'hypercuke/cli'
+require 'hypercuke/context'
+require 'hypercuke/config'
+require 'hypercuke/exceptions'
+require 'hypercuke/mini_inflector'
+require 'hypercuke/name_list'
+require 'hypercuke/step_driver'
+require 'hypercuke/step_adapter'
+require 'hypercuke/step_adapters'
+require 'hypercuke/adapter_definition'
+
+module Hypercuke
+  LAYER_NAME_ENV_VAR = 'HYPERCUKE_LAYER'
+
+  def self.reset!
+    @config = nil
+    @current_layer = nil
+    StepAdapters.clear
+  end
+
+  def self.current_layer=(layer_name)
+    @current_layer = layer_name ? layer_name.to_sym : nil
+  end
+  def self.current_layer
+    layer_name = (@current_layer || ENV[LAYER_NAME_ENV_VAR])
+    layer_name && layer_name.to_sym
+  end
+
+
+  def self.config
+    @config ||= Config.new
+  end
+
+  class << self
+    extend Forwardable
+    def_delegators :config, *[
+      :layers, :layer_names,
+      :topics, :topic_names,
+    ]
+  end
+
+end

data/lib/hypercuke/adapter_definition.rb

@@ -0,0 +1,29 @@
+module Hypercuke
+  # Entry point for the adapter definition API
+  def self.topic(topic_name, &block)
+    AdapterDefinition.topic topic_name, &block
+  end
+
+  module AdapterDefinition
+    def self.topic(topic_name, &block)
+      Hypercuke.topics.define topic_name
+      tb = TopicBuilder.new(topic_name)
+      tb.instance_eval &block if block_given?
+    end
+
+    class TopicBuilder
+      attr_reader :topic_name
+      def initialize(topic_name)
+        @topic_name = topic_name.to_sym
+      end
+
+      # I know the name *says* "layer", but what it *means* is that we
+      # should define a step adapter for that layer.
+      def layer(layer_name, &block)
+        Hypercuke.layers.define layer_name
+        klass = Hypercuke::StepAdapters.define( topic_name, layer_name )
+        klass.module_eval &block if block_given?
+      end
+    end
+  end
+end

data/lib/hypercuke/cli.rb

@@ -0,0 +1,53 @@
+require 'hypercuke/cli/parser'
+require 'hypercuke/cli/builder'
+
+module Hypercuke
+  class CLI
+    def self.exec(argv, opts = {})
+      cli = new(argv, opts[:output_to])
+      cli.run!
+    end
+
+    # NB: .bundler_present? is not covered by tests, because I can't
+    # think of a reasonable way to test it.  PRs welcome.  :)
+    def self.bundler_present?
+      !! (`which bundle` =~ /\wbundle\w/) # parens are significant
+    end
+
+    def initialize(argv, output = nil, environment = ENV, kernel = Kernel)
+      @argv        = argv
+      @output      = output
+      @environment = environment
+      @kernel      = kernel
+    end
+
+    def run!
+      output && output.puts(cucumber_command_for_display)
+      new_env = environment.to_hash.merge({ Hypercuke::LAYER_NAME_ENV_VAR => layer_name })
+      kernel.exec new_env, cucumber_command
+    end
+
+    def layer_name
+      parser.layer_name
+    end
+
+    def cucumber_command
+      builder.cucumber_command_line(self.class.bundler_present?)
+    end
+
+    def cucumber_command_for_display
+      "HYPERCUKE_LAYER=#{layer_name} #{cucumber_command}"
+    end
+
+    private
+    attr_reader :argv, :output, :environment, :kernel
+
+    def parser
+      @parser ||= Hypercuke::CLI::Parser.new(argv)
+    end
+
+    def builder
+      @builder ||= Hypercuke::CLI::Builder.new(parser.options)
+    end
+  end
+end

data/lib/hypercuke/cli/builder.rb

@@ -0,0 +1,68 @@
+module Hypercuke
+  class CLI
+
+    # I take information extracted the Parser and use it to build a
+    # 'cucumber' command line
+    class Builder
+      def initialize(options)
+        @options   = options
+        @cuke_args = []
+        build_cuke_args
+      end
+
+      def cucumber_command_line(prepend_bundler = false)
+        cmd = prepend_bundler ? 'bundle exec ' : ''
+        cmd << cuke_args.join(' ')
+        cmd
+      end
+
+      private
+      attr_reader :options, :cuke_args
+
+      def build_cuke_args
+        add_base_command
+        add_layer_tag_for_mode
+        add_profile_unless_already_present
+        pass_through_all_other_args
+      end
+
+      def add_base_command
+        cuke_args << 'cucumber'
+      end
+
+      def add_layer_tag_for_mode
+        cuke_args << "--tags #{layer_tag_for_mode}"
+      end
+
+      def layer_tag_for_mode
+        layer = options[:layer_name]
+        mode  = options[:mode] || 'ok'
+        '@%s_%s' % [ layer, mode ]
+      end
+
+      def add_profile_unless_already_present
+        if profile_specified?
+          add_profile options[:profile]
+        else
+          if options[:mode] == 'wip'
+            add_profile 'wip'
+          end
+        end
+      end
+
+      def profile_specified?
+        options[:profile].to_s !~ /^\s*$/
+      end
+
+      def add_profile(profile_name)
+        cuke_args << '--profile'
+        cuke_args << profile_name
+      end
+
+      def pass_through_all_other_args
+        cuke_args.concat( options[:other_args] )
+      end
+    end
+
+  end
+end