specify 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6bd52074c94486ea349b2b8a64811cbe1407ffcc
-  data.tar.gz: 4ca92a95cf2169533e5aed1abee1afd6fa4d01a6
+  metadata.gz: 0e886dff9cb121d9b139f79b7bbfbe0fbfb015d6
+  data.tar.gz: ba3900c1895de6e1e3c42d0709ce770fa708bdce
 SHA512:
-  metadata.gz: c0ce369f131e8fbfcee0a790a9e803345935fa54cc0c0486a9f7ffb37ebb00c35c682c735ddd00067fc7610a0ab02d5ced9175792ef8dab4004de8e287f98aac
-  data.tar.gz: 50bde5b576fb61613173952fc1b2bd90d868832b784354b71fa70e988243e88e6f39153ca45c0643fc205e0099667fd7c22d9cfb9df2802cb90854c97a3c41b8
+  metadata.gz: 11d8a7eacd4b0d70047d270d1153cab8700bca9a40419e7930ff9a49bf684af953d0bd7cf3bb3095cf1150189768d320c6a74043a09a4b533ef24f783f0725cd
+  data.tar.gz: dd1977da7b7b94864500fa533eb859c6cd731d5eac70a9609513273fd85f8f0c571bd367c19299e94deb5c0accb8aae0fa6eca3c7a20acbe459049d955e190eb

data/.gitignore

@@ -13,3 +13,4 @@
 *.o
 *.a
 mkmf.log
+.DS_Store

data/README.md

@@ -1,8 +1,8 @@
 # Specify
 
-Specify parses test specifications written in Gherkin format and runs them via RSpec.
+Specify is a BDD-style micro-framework.
 
-The goal of Specify is to separate the concepts behind tools like Cucumber and Lucid from their implementation. The latter has been weak in some cases but the former has been strong.
+Specify is a very thin wrapper around RSpec that provides a Gherkin-style syntax for use with test examples.
 
 ## Installation
 
@@ -22,7 +22,119 @@ Or install it yourself as:
 
 ## Usage
 
-Further details on usage will be coming as Specify evolves.
+To use Specify you simply have to require it within your `spec_helper` file.
+
+While Specify does provide a Gherkin-like syntax, there is no parsing of a Gherkin feature and step definition matching. Just as in RSpec, everything is in one place: the Ruby file. The benefit here is that you don't have to change the text in two places (feature file and step definition file) every time you change something. Further, there are no more matchers to sync up with natural language. Specify uses plain Ruby helper methods coupled with various patterns.
+
+### Integration Tests
+
+RSpec's mode of action is that all examples should be completely independent. This is in line with its focus as primarily a unit-based testing framework. For integration purposes, this means if you want to use RSpec you have to write a sequence of examples, each of which repeats the behavior of all previous examples. Another alternative is that you could write one single large example that performs the entire set of actions. The problem in that case is that there is no independent reporting of each step.
+
+This is why tools like Cucumber end up being used.
+
+However the only benefit there is the ability to execute some examples in sequence and skip subsequent steps after a failure.
+
+So that's the goal of Specify: provide just the good parts of Cucumber and skipping all the questionable parts. At minimum this means the ability to chain examples into a series of steps that run in sequence and which stop when a step fails. The idea is to assemble a series of tests that should all pass, but where completely isolating them is not sensible. Hooking this into RSpec, this would make RSpec less unit and more integration.
+
+### Example
+
+Consider this example of a standard RSpec example group:
+
+```ruby
+describe 'Basic Spec Structure' do
+  context 'when simple logic tests are applied' do
+    it 'will agree that true almost certainly not false' do
+      expect(true).to_not be false
+    end
+
+    it 'will agree that true is pretty definitely true' do
+      expect(true).to be true
+    end
+  end
+end
+
+describe 'Simple Scenarios' do
+  context 'with an instance variable' do
+    it 'will establish a variable' do
+      @active = 'testing'
+      expect(@active).to eq 'testing'
+    end
+
+    it 'will reference the instance variable' do
+      puts "@active = #{@active}"
+      expect(@active).to eq 'testing'
+    end
+  end
+end
+```
+
+Now consider how this can work with Specify. You will have a "steps" block. Within that, all examples run in order of specification. State is preserved between examples within the "steps" block. If any example inside the "steps" block fails, all remaining steps will be marked as pending and thus skipped.
+
+```ruby
+context 'when simple logic tests are applied' do
+  steps do
+    Given 'true is almost certainly not false' do
+      expect(true).to_not be false
+    end
+
+    Given 'true is pretty definitely true' do
+      expect(true).to be true
+    end
+  end
+end
+
+context 'Simple Scenarios' do
+  steps 'with an instance variable' do
+    When 'it establishes an instance variable' do
+      @active = 'testing'
+      expect(@active).to eq 'testing'
+    end
+
+    Then 'that instance variable can be referenced' do
+      puts "@active = #{@active}"
+      expect(@active).to eq 'testing'
+    end
+  end
+end
+```
+
+### Shared Steps
+
+You can use `shared_steps` to define a block that will be evaluated in the context of an example. The example must use the `include_steps` directive. Here is an example of some shared steps:
+
+```ruby
+shared_steps 'login' do |email, password|
+  When 'I go to login page' do
+    puts 'Go to the login page'
+  end
+  
+  When 'I put credentials' do
+    puts "Email: #{email}, Password: #{password}"
+  end
+end
+
+shared_steps 'invalid login' do
+  Then 'I should see login error' do
+    puts 'Expect a login error'
+  end
+end
+```
+
+Here is how those steps can be used:
+
+```ruby
+context 'action' do
+  steps 'User provides wrong email' do
+    include_steps 'login', 'jeff', 'invalid'
+    include_steps 'invalid login'
+  end
+
+  steps 'User provides wrong password' do
+    include_steps 'login', 'jeff@example.com', 'testing'
+    include_steps 'invalid login'
+  end
+end
+```
 
 ## Contributing
 
@@ -33,3 +145,11 @@ To work on Specify:
 3. Commit your changes. (`git commit -am 'new feature'`)
 4. Push the branch. (`git push origin my-new-feature`)
 5. Create a new [pull request](https://help.github.com/articles/using-pull-requests).
+
+## Authors
+
+* [Jeff Nyman](http://testerstories.com)
+
+## License
+
+Specify is distributed under the [MIT](http://www.opensource.org/licenses/MIT) license.

data/Rakefile

@@ -1,3 +1,2 @@
-#!/usr/bin/env rake
 require 'bundler/gem_tasks'
 

data/lib/specify/rspec/documentation_formatter.rb

@@ -0,0 +1,57 @@
+module RSpec
+  module Specify
+    module DocumentationFormatter
+      def self.included(base)
+        base.class_eval do
+          include InstanceMethods
+
+          alias :example_started_without_steps :example_started
+          alias :example_started :example_started_with_steps
+
+          alias :example_passed_without_steps :example_passed
+          alias :example_passed :example_passed_with_steps
+        end
+      end
+    end
+
+    module InstanceMethods
+      def example_started(notification)
+      end
+
+      def example_step_passed(notification)
+        full_message = "#{current_indentation}  #{notification.type.to_s.capitalize} #{notification.message}"
+        output.puts Core::Formatters::ConsoleCodes.wrap(full_message, :success)
+      end
+
+      def example_step_failed(notification)
+        full_message = "#{current_indentation}  #{notification.type.to_s.capitalize} #{notification.message} (FAILED)"
+        output.puts Core::Formatters::ConsoleCodes.wrap(full_message, :failure)
+      end
+
+      def example_step_pending(notification)
+        full_message = "#{current_indentation}  #{notification.type.to_s.capitalize} #{notification.message}"
+
+        if notification.options[:pending] && notification.options[:pending] != true
+          full_message << " (PENDING: #{notification.options[:pending]})"
+        else
+          full_message << ' (PENDING)'
+        end
+
+        output.puts Core::Formatters::ConsoleCodes.wrap(full_message, :pending)
+      end
+
+      def example_started_with_steps(notification)
+        example_started_without_steps(notification)
+
+        if notification.example.metadata[:with_steps]
+          full_message = "#{current_indentation}#{notification.example.description}"
+          output.puts Core::Formatters::ConsoleCodes.wrap(full_message, :default)
+        end
+      end
+
+      def example_passed_with_steps(notification)
+        example_passed_without_steps(notification) unless notification.example.metadata[:with_steps]
+      end
+    end
+  end
+end

data/lib/specify/rspec/example_group.rb

@@ -0,0 +1,32 @@
+module RSpec
+  module Specify
+    module ExampleGroup
+      def include_steps(*args)
+        name = args.shift
+        shared_block = RSpec.world.shared_example_steps[name]
+        shared_block or raise ArgumentError, "Could not find shared steps #{name.inspect}"
+        instance_exec(*args, &shared_block)
+      end
+
+      def Given(message, options={}, &block)
+        RSpec.world.reporter.process_example_step(self, :given, message, options, &block)
+      end
+
+      def When(message, options={}, &block)
+        RSpec.world.reporter.process_example_step(self, :when, message, options, &block)
+      end
+
+      def Then(message, options={}, &block)
+        RSpec.world.reporter.process_example_step(self, :then, message, options, &block)
+      end
+
+      def And(message, options = {}, &block)
+        RSpec.world.reporter.process_example_step(self, :and, message, options, &block)
+      end
+
+      def But(message, options = {}, &block)
+        RSpec.world.reporter.process_example_step(self, :but, message, options, &block)
+      end
+    end
+  end
+end

data/lib/specify/rspec/notification.rb

@@ -0,0 +1,6 @@
+module RSpec
+  module Specify
+    class Notification < Struct.new(:example, :type, :message, :options)
+    end
+  end
+end

data/lib/specify/rspec/reporter.rb

@@ -0,0 +1,45 @@
+module RSpec
+  module Specify
+    module Reporter
+      def process_example_step(example, type, message, options)
+        example_step_started(self, type, message, options)
+
+        if block_given? && !options[:pending]
+          begin
+            yield
+          rescue Exception => e
+            example_step_failed(self, type, message, options)
+            raise e
+          end
+          example_step_passed(self, type, message, options)
+        else
+          example_step_pending(self, type, message, options)
+        end
+      end
+
+      def example_step_started(example, type, message, options)
+        notify :example_step_started, Notification.new(example, type, message, options)
+      end
+
+      def example_step_passed(example, type, message, options)
+        notify :example_step_passed, Notification.new(example, type, message, options)
+      end
+
+      def example_step_failed(example, type, message, options)
+        notify :example_step_failed, Notification.new(example, type, message, options)
+      end
+
+      def example_step_pending(example, type, message, options)
+        notify :example_step_pending, Notification.new(example, type, message, options)
+      end
+
+      def registered_formatters
+        @listeners.values.map(&:to_a).flatten.uniq
+      end
+
+      def find_registered_formatter(cls)
+        registered_formatters.detect { |formatter| formatter.class == cls }
+      end
+    end
+  end
+end

data/lib/specify/rspec/shared_steps.rb

@@ -0,0 +1,18 @@
+module RSpec
+  module Specify
+    module SharedSteps
+      def shared_steps(name, &block)
+        ensure_shared_example_steps_name_not_taken(name)
+        RSpec.world.shared_example_steps[name] = block
+      end
+
+      private
+
+      def ensure_shared_example_steps_name_not_taken(name)
+        if RSpec.world.shared_example_steps.has_key?(name)
+          raise ArgumentError.new("Shared step '#{name}' already exists")
+        end
+      end
+    end
+  end
+end

data/lib/specify/rspec/world.rb

@@ -0,0 +1,9 @@
+module RSpec
+  module Specify
+    module World
+      def shared_example_steps
+        @shared_example_steps ||= {}
+      end
+    end
+  end
+end

data/lib/specify/version.rb

@@ -1,3 +1,3 @@
 module Specify
-  VERSION = '0.0.1'
+  VERSION = '0.1.0'
 end

data/lib/specify.rb

@@ -2,3 +2,40 @@ require 'specify/version'
 
 module Specify
 end
+
+require 'rspec/core'
+require 'rspec/core/example_group'
+require 'rspec/core/reporter'
+require 'rspec/core/world'
+require 'rspec/core/formatters'
+require 'rspec/core/formatters/console_codes'
+require 'rspec/core/formatters/documentation_formatter'
+
+require 'specify/rspec/example_group'
+require 'specify/rspec/notification'
+require 'specify/rspec/reporter'
+require 'specify/rspec/world'
+require 'specify/rspec/documentation_formatter'
+
+RSpec::Core::ExampleGroup.send :include, RSpec::Specify::ExampleGroup
+RSpec::Core::Reporter.send     :include, RSpec::Specify::Reporter
+RSpec::Core::World.send        :include, RSpec::Specify::World
+
+RSpec::Core::Formatters::DocumentationFormatter.send :include, RSpec::Specify::DocumentationFormatter
+
+if formatter = RSpec.world.reporter.find_registered_formatter(RSpec::Core::Formatters::DocumentationFormatter)
+  RSpec.world.reporter.register_listener(
+      formatter,
+      :example_started,
+      :example_step_passed,
+      :example_step_pending,
+      :example_step_failed
+  )
+end
+
+
+RSpec::Core::ExampleGroup.define_example_method :steps, with_steps: true
+RSpec::Core::ExampleGroup.define_example_method :Scenario, with_steps: true
+
+require 'specify/rspec/shared_steps'
+include RSpec::Specify::SharedSteps

data/specify.gemspec

@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
   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 = %w(lib)
+  spec.require_paths = ['lib']
 
   spec.required_ruby_version     = '>= 2.0.0'
   spec.required_rubygems_version = '>= 1.8.29'
@@ -29,8 +29,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 1.7'
   spec.add_development_dependency 'rake', '~> 10.0'
 
-  spec.add_runtime_dependency 'gherkin', '~> 2.12'
-  spec.add_runtime_dependency 'rspec', '~> 3.0'
+  spec.add_runtime_dependency 'rspec-core', '~> 3.0'
 
   spec.post_install_message = %{
 (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: specify
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Jeff Nyman
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-04 00:00:00.000000000 Z
+date: 2014-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -39,21 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
-  name: gherkin
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.12'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.12'
-- !ruby/object:Gem::Dependency
-  name: rspec
+  name: rspec-core
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -82,6 +68,12 @@ files:
 - README.md
 - Rakefile
 - lib/specify.rb
+- lib/specify/rspec/documentation_formatter.rb
+- lib/specify/rspec/example_group.rb
+- lib/specify/rspec/notification.rb
+- lib/specify/rspec/reporter.rb
+- lib/specify/rspec/shared_steps.rb
+- lib/specify/rspec/world.rb
 - lib/specify/version.rb
 - specify.gemspec
 homepage: https://github.com/jnyman/specify
@@ -89,7 +81,7 @@ licenses:
 - MIT
 metadata: {}
 post_install_message: "\n(::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::)\n\n
-  \ Specify 0.0.1 has been installed.\n\n(::) (::) (::) (::) (::) (::) (::) (::) (::)
+  \ Specify 0.1.0 has been installed.\n\n(::) (::) (::) (::) (::) (::) (::) (::) (::)
   (::) (::) (::)\n  "
 rdoc_options: []
 require_paths: