rspec-stepwise 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5a90ad69a86866bac6f5cd8d5c163f9cad892df41a20639bf4424c2fc05e621f
+  data.tar.gz: b7f440c808536c92caaaa466412b394193c16d393c9a74b3cc473da342f080b0
+SHA512:
+  metadata.gz: dc3bce1e9aa483eac641b691d509fa38792140e29ce32508ae091a315f087e64ad443a17b425c9355232adc0341dd9ad1c80bf94b484888c5addade74bf18b14
+  data.tar.gz: 995132c1190c4fcbed1cc74a2b5dba44b8cb22c6ad0c41b87420b92885598c16b8b800ef3d40a0aeeafaec95f48ad806975bd05b927fa3380584d672a8a0e934

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.0
+before_install: gem install bundler -v 2.0.1

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Nikita Afanasenko
+
+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,127 @@
+# RSpec Stepwise Executor
+
+Provides a simple DSL on top of RSpec for defining a series of spec execution steps. Particularly useful for describing of human-readable integration testing scenarios.
+
+RSpec Stepwise provides the following guarantees within the same steps group:
+
+- Strict step execution order, even if RSpec is configured to run examples randomly.
+- All steps share the same execution context, thus share instances defined in `let` etc.
+- All steps after the failed one will be skipped.
+
+## Usage
+
+Configure RSpec to use stepwise DSL:
+
+```ruby
+require 'rspec/stepwise'
+
+RSpec.configure do |config|
+  config.extend RSpec::Stepwise
+  # ...
+end
+```
+
+This adds `stepwise` method for creating ordered example groups and `step` method for describing particular step in a chain. See full usage example:
+
+```ruby
+RSpec.describe 'User Scenarios' do
+  # Defines example group for account confirmation scenario.
+  # All steps within this group will run in an order.
+  stepwise 'Account Confirmation' do
+    # All RSpec APIs works as usual inside both group and steps.
+    let(:api) { ClientApi.new }
+    let(:mailbox) { Mailbox.new }
+    let(:user) { User.new }
+
+    step 'register' do
+      api.register(user)
+    end
+
+    step 'unable to sign in' do
+      response = api.sign_in(user)
+      expect(response).to be_forbidden
+    end
+
+    step 'confirm' do
+      mailbox.confirm(user)
+      fail 'Email not found in mailbox'
+    end
+
+    # This step will not be executed because previous one failed.
+    step 'successfully sign in' do
+      response = api.sign_in(user)
+      expect(response).to be_successfull
+    end
+
+    # Called after all steps, even if one failed.
+    after do
+      mailbox.clear
+    end
+
+    # Called only when a step failed.
+    on_fail do
+      puts api.logs
+    end
+  end
+end
+```
+
+## Known Limitations
+
+RSpec doubles should not be used in a shared stepwise context, otherwise it leads to:
+
+_#<Double ...> was originally created in one example but has leaked into another example and can no longer be used. rspec-mocks' doubles are designed to only last for one example, and you need to create a new one in each example you wish to use it for._
+
+So this will not work:
+
+```ruby
+stepwise do
+  let(:api) { double(:api, call: nil) }
+
+  step 'one' do
+    api.call
+  end
+
+  step 'another' do
+    api.call
+  end
+end
+```
+
+Instead you have to do something like:
+
+```ruby
+stepwise do
+  step 'one' do
+    api = double(:api, call: nil)
+    api.call
+  end
+
+  step 'another' do
+    api = double(:api, call: nil)
+    api.call
+  end
+end
+```
+
+## Installation
+
+Using Bundler:
+
+```ruby
+gem 'rspec-stepwise', '~> 0.1.0'
+```
+
+Or using rubygems:
+
+```bash
+gem install rspec-stepwise
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nikitug/rspec-stepwise.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/rspec/stepwise/version.rb

@@ -0,0 +1,5 @@
+module RSpec
+  module Stepwise
+    VERSION = '0.1.0'
+  end
+end

data/lib/rspec/stepwise.rb

@@ -0,0 +1,135 @@
+require 'rspec/stepwise/version'
+
+module RSpec
+  # Provides DSL for defining a series of steps.
+  #
+  # @example
+  #   RSpec.describe 'user registration and sign in' do
+  #     stepwise do
+  #       step 'register' do
+  #         api.register(user)
+  #         mailbox.confirm(user)
+  #       end
+  #
+  #       step 'sign in' do
+  #         token = api.sign_in(user)
+  #         expect(token).not_to be expired
+  #       end
+  #     end
+  #   end
+  #
+  module Stepwise
+    # Defines new series of steps. Supports the same arguments as `RSpec.describe`.
+    # @see RSpec.describe
+    def stepwise(name = nil, *args, &block)
+      if args.last.is_a?(Hash)
+        args.last[:order] = :defined
+      else
+        args << { order: :defined }
+      end
+      describe(name, *args) do
+        Builder.new(self).instance_eval(&block)
+      end
+    end
+
+    # Provides DSL for steps definition and builds execution context.
+    class Builder
+      # @param klass [RSpec::Core::ExampleGroup]
+      def initialize(klass)
+        @klass = klass
+        @steps_context = Context.new(klass)
+        @fail_callbacks = []
+      end
+
+      # Defines new step in a series. Supports the same arguments as `RSpec::Core::ExampleGroup.it`.
+      # @see RSpec::Core::ExampleGroup.it
+      def step(*args, &block)
+        # `it` defines method within `klass`, so Builder's
+        # instance variable will not be visible there,
+        # so we use local var.
+        steps_context = @steps_context
+        fail_callbacks = @fail_callbacks
+        @klass.it(*args) do
+          if steps_context.previous_failed?
+            pending 'Previous step failed'
+            fail
+          else
+            begin
+              steps_context.run_step(&block)
+            rescue
+              fail_callbacks.each do |callback|
+                steps_context.run(&callback)
+              end
+              raise
+            end
+          end
+        end
+      end
+
+      # Runs if any step failed. Can be executed multiple times.
+      # Execution will happen in the same order as definition order.
+      #
+      # @example
+      #   # Outputs API logs in case of failure.
+      #   on_fail do
+      #     puts api.execution_logs
+      #   end
+      #
+      def on_fail(&block)
+        @fail_callbacks << block
+      end
+
+      # Runs after all steps finished.
+      #
+      # @example
+      #   # Clears virtual mailbox after all steps.
+      #   after do
+      #     mailbox.clear
+      #   end
+      #
+      def after(&block)
+        steps_context = @steps_context
+        @klass.after(:all) do
+          steps_context.run(&block)
+        end
+      end
+
+      private
+
+      def method_missing(name, *args, &block)
+        if @klass.respond_to?(name)
+          @klass.public_send(name, *args, &block)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @klass.respond_to?(name, include_private) || super
+      end
+    end
+
+    # @api private
+    class Context
+      def initialize(klass)
+        @context = klass.new
+        @previous_failed = false
+      end
+
+      def run_step(&block)
+        run(&block)
+      rescue
+        @previous_failed = true
+        raise
+      end
+
+      def run(&block)
+        @context.instance_eval(&block)
+      end
+
+      def previous_failed?
+        @previous_failed
+      end
+    end
+  end
+end

data/rspec-stepwise.gemspec

@@ -0,0 +1,22 @@
+require_relative "lib/rspec/stepwise/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "rspec-stepwise"
+  spec.version       = RSpec::Stepwise::VERSION
+  spec.authors       = ["Nikita Afanasenko"]
+  spec.email         = ["nikita@afanasenko.name"]
+
+  spec.summary       = "Stepwise execution for RSpec."
+  spec.description   = "Stepwise execution for RSpec."
+  spec.homepage      = "https://github.com/nikitug/rspec-stepwise"
+  spec.license       = "MIT"
+
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: rspec-stepwise
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nikita Afanasenko
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-06-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Stepwise execution for RSpec.
+email:
+- nikita@afanasenko.name
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/rspec/stepwise.rb
+- lib/rspec/stepwise/version.rb
+- rspec-stepwise.gemspec
+homepage: https://github.com/nikitug/rspec-stepwise
+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: []
+rubygems_version: 3.0.1
+signing_key: 
+specification_version: 4
+summary: Stepwise execution for RSpec.
+test_files: []