rspec_approvals 0.8.0.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bf7766ed4c1e6890d248ccabf8e6cd02c6656f07f702e95b95c06a89ef1b7fd2
+  data.tar.gz: ec5c8219a4129d2bcfc8a3ebfa4bdcf5cdf658a0a08a677906e0bffa8cd8e4c1
+SHA512:
+  metadata.gz: 7d3fb8aa6519c178621967564338eb822973660034511bf753156fbffa88468aaad58bc0c5e7367d56c2a7759d788b2b40f539576483ea16c9a5cada7f7f2c90
+  data.tar.gz: 5e503b9463bc9ed88de91e98a1e72e91be4a987241acda2a6673a63f6dd2b32a5e2639016864637dc4faa7902789132c9e28b64c3cf3781f6f3a0e0fb99bf9c3

data/README.md

@@ -0,0 +1,247 @@
+# RSpec Approvals
+
+[![Gem Version](https://badge.fury.io/rb/rspec_approvals.svg)](https://badge.fury.io/rb/rspec_approvals)
+[![Build Status](https://github.com/DannyBen/rspec_approvals/workflows/Test/badge.svg)](https://github.com/DannyBen/rspec_approvals/actions?query=workflow%3ATest)
+[![Maintainability](https://api.codeclimate.com/v1/badges/a06ed5e30412062c454c/maintainability)](https://codeclimate.com/github/DannyBen/rspec_approvals/maintainability)
+
+---
+
+RSpec Approvals allows you to interactively review and approve testable
+content. 
+
+![Demo](demo/cast.svg)
+
+---
+
+## Install
+
+```
+$ gem install rspec_approvals
+```
+
+Or with bundler:
+
+```ruby
+gem 'rspec_approvals'
+```
+
+## Usage
+
+Require the gem in your spec helper:
+
+```ruby
+# spec/spec_helper.rb
+require 'rspec_approvals'
+```
+
+And use any of the matchers in your specs.
+
+```ruby
+describe 'ls' do
+  it "works" do
+    expect(`ls`).to match_approval('ls_approval')
+  end
+end
+```
+
+## Matchers
+
+### `match_approval` - Compare Strings
+
+Compare a string with a pre-approved approval.
+
+```ruby
+expect('some string').to match_approval('approval_filename')
+```
+
+
+### `output_approval` - Compare STDOUT/STDERR
+
+Compare an output (stdout or stderr) with a pre-approved approval.
+
+```ruby
+expect { puts "hello" }.to output_approval('approval_filename')
+expect { puts "hello" }.to output_approval('approval_filename').to_stdout
+expect { $stderr.puts "hello" }.to output_approval('approval_filename').to_stderr
+
+# The first two are the same, as the default stream is stdout.
+```
+
+
+### `raise_approval` - Compare raised exceptions
+
+Compare a raised exception with a pre-approved approval.
+
+```ruby
+expect { raise 'some error' }.to raise_approval('approval_filename')
+```
+
+## Modifiers
+
+### `diff` - String similarity
+
+Adding `diff(distance)` to either `match_approval` or `output_approval` will
+change the matching behavior. Instead of expecting the strings to be exactly
+the same, using `diff` compares the strings using the 
+[Levenshtein distance][levenshtein] algorithm.
+
+In the below example, we allow up to 5 characters to be different.
+
+```ruby
+expect ('some string').to match_approval('approval_filename').diff(5)
+expect { puts 'some string' }.to output_approval('approval_filename').diff(5)
+```
+
+### `except` - Exclude by regular expression
+
+Adding `except(regex)` to either `match_approval` or `output_approval` will
+modify the string under test before running. By default, the regular
+expression will be replaced with `...`.
+
+In the below example, we ignore the full path of the file.
+
+```ruby
+expect('path: /path/to/file').to match_approval('approval_filename').except(/path: .*file/)
+```
+
+You may provide a second argument, which will be used as an alternative
+replace string:
+
+In the below example, all time strings will be replaced with `HH:MM`:
+
+```ruby
+expect('22:30').to match_approval('approval_filename').except(/\d2:\d2/, 'HH:MM')
+```
+
+### `before` - Alter the string before testing
+
+The `before(proc)` method is a low level method and should normally not be 
+used directly (as it is used by the `except` modifier).
+
+Adding `before(proc)` to either `match_approval` or `output_approval` will
+call the block and supply the actual string. The proc is expected to return
+the new actual string.
+
+In the below example, we replace all email addresses in a string.
+
+```ruby
+expect('hello rspec@approvals.com').to match_approval('approval_filename').before ->(actual) do
+  actual.gsub /\w+@\w+\.\w+/, 'some@email.com'
+end
+
+```
+
+## Configuration
+
+### `interactive_approvals`
+
+By default, interactive approvals are enabled in any environment that 
+does not define the `CI` or the `GITHUB_ACTIONS` environment variables.
+You can change this by adding this to your `spec_helper`
+
+```ruby
+RSpec.configure do |config|
+  config.interactive_approvals = false # or any logic
+end
+```
+
+### `approvals_path`
+
+By default, approvals are stored in `spec/approvals`. To change the path,
+add this to your `spec_helper`.
+
+```ruby
+RSpec.configure do |config|
+  config.approvals_path = 'spec/anywhere/else'
+end
+```
+
+### `auto_approve`
+
+If you wish to automatically approve all new or changed approvals, you can
+set the `auto_approve` configuration option to `true`. By default, 
+auto approval is enabled if the environment variable `AUTO_APPROVE` is set.
+
+```ruby
+RSpec.configure do |config|
+  config.auto_approve = true # or any logic
+end
+```
+
+This feature is intended to help clean up the approvals folder from old, no
+longer used files. Simply run the specs once, to ensure they all oass, 
+delete the approvals folder, and run the specs again with:
+
+```
+$ AUTO_APPROVE=1 rspec
+```
+
+### `strip_ansi_escape`
+
+In case your output strings contain ANSI escape codes that you wish to avoid
+storing in your approvals, you can set the `strip_ansi_escape` to `true`.
+
+```ruby
+RSpec.configure do |config|
+  config.strip_ansi_escape = true
+end
+```
+
+### `before_approval`
+
+In case you need to alter the actual output globally, you can provide the
+`before_approval` option with a proc. The proc will receive the actual
+output - similarly to the `before` modifier - and is expectedd to return
+a modified actual string.
+
+```ruby
+RSpec.configure do |config|
+  config.before_approval = ->(actual) do
+    # return the actual string, without IP addresses
+    actual.gsub(/\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}/, '[IP REMOVED]')
+  end
+end
+```
+
+## Advanced Usage Tips
+
+### Sending output directly to RSpecApprovals
+
+In some cases, you might need to send output directly to the `RSpecApproval`
+stream capturer.
+
+An example use case, is when you are testing `Logger` output.
+
+The `RSpecApproval#stdout` and `RSpecApproval#stderr` can be used as an
+alternative to `$stdout` and `$stderr`. These methods both return the
+`StringIO` object that is used by `RSpecApprovals` to capture the output.
+
+For example, you can use this:
+
+```ruby
+logger = Logger.new(RSpecApprovals.stdout)
+```
+
+as an alternative to this:
+
+```
+logger = Logger.new($stdout)
+```
+
+### Consistent terminal width
+
+In case you are testing standard output with long lines, you may encounter inconsistencies when testing on different hosts, with varying terminal width. In order to ensure consistent output to stdout, you may want to set a known terminal size in your `spec_helper`:
+
+```ruby
+ENV['COLUMNS'] = '80'
+ENV['LINES'] = '24'
+```
+
+## Contributing / Support
+
+If you experience any issue, have a question or a suggestion, or if you wish
+to contribute, feel free to [open an issue][issues].
+
+
+[levenshtein]: https://en.wikipedia.org/wiki/Levenshtein_distance
+[issues]: https://github.com/DannyBen/rspec_approvals/issues

data/lib/rspec_approvals.rb

@@ -0,0 +1,12 @@
+require 'rspec_approvals/extensions/file'
+
+require 'rspec_approvals/module_functions'
+require 'rspec_approvals/stream'
+require 'rspec_approvals/approval_handler'
+require 'rspec_approvals/matchers/base'
+require 'rspec_approvals/matchers/match_approval'
+require 'rspec_approvals/matchers/output_approval'
+require 'rspec_approvals/matchers/raise_approval'
+
+require 'rspec_approvals/rspec_config'
+

data/lib/rspec_approvals/approval_handler.rb

@@ -0,0 +1,99 @@
+require 'io/console'
+require 'colsole'
+require 'tty-prompt'
+require 'diffy'
+
+module RSpecApprovals
+
+  # Handles user input and interactive approvals
+  class ApprovalHandler
+    include Colsole
+
+    attr_reader :expected, :actual, :approval_file
+
+    def run(expected, actual, approval_file)
+      @expected = expected
+      @actual = actual
+      @approval_file = approval_file
+
+      show expected.empty? ? actual : diff
+      prompt_user
+    end
+
+    private
+
+    def prompt_user
+      response = auto_approve? ? :approve : get_response
+
+      case response
+
+      when :approve, :reject
+        send response
+
+      when :actual, :expected, :diff
+        show send response
+        prompt_user
+
+      else
+        false
+
+      end
+    end
+
+    def auto_approve?
+      RSpec.configuration.auto_approve
+    end
+
+    def get_response
+      prompt.select "Please Choose:", menu_options, symbols: { marker: '>' }
+    rescue TTY::Reader::InputInterrupt
+      # :nocov:
+      return :reject
+      # :nocov:
+    end
+
+    def menu_options
+      base = {
+        'Reject (and fail test)' => :reject,
+        'Approve (and save)' => :approve,
+      }
+
+      extra = {
+        'Show actual output' => :actual,
+        'Show expected output' => :expected,
+        'Show diff' => :diff,
+      }
+
+      expected.empty? ? base : base.merge(extra) 
+    end
+
+    def approve
+      say "!txtgrn!Approved"
+      File.deep_write approval_file, actual
+      true
+    end
+
+    def reject
+      say "!txtred!Not Approved"
+      false
+    end
+
+    def separator
+      "!txtgrn!" + ('_' * terminal_width)
+    end
+
+    def diff
+      Diffy::Diff.new(expected, actual, context: 2).to_s :color
+    end
+
+    def show(what)
+      say separator
+      say what
+      say separator
+    end
+
+    def prompt
+      @prompt ||= TTY::Prompt.new
+    end
+  end
+end

data/lib/rspec_approvals/extensions/file.rb

@@ -0,0 +1,9 @@
+require 'fileutils'
+
+class File
+  def self.deep_write(file, content)
+    dir = File.dirname file
+    FileUtils.mkdir_p dir unless Dir.exist? dir
+    File.write file, content
+  end
+end

data/lib/rspec_approvals/matchers/base.rb

@@ -0,0 +1,148 @@
+module RSpecApprovals
+  module Matchers
+
+    # A base matcher for approvals
+    class Base
+      attr_reader :approval_name, :actual, :distance, :actual_distance
+
+      def initialize(approval_name=nil)
+        @before = nil
+        @approval_name = approval_name
+      end
+
+      # Called by RSpec. This will be overridden by child matchers.
+      def matches?(actual)
+        @actual ||= actual
+        return false if @actual.empty?
+
+        @actual = sanitize @actual
+        success = strings_match?
+
+        if success or !interactive?
+          success
+        else
+          approve_approval
+        end
+      end
+
+      # Enables the ability to do something like:
+      # `expect(string).to match_approval(file).diff(10)
+      # The distance argument is the max allowed Levenshtein Distance.
+      def diff(distance)
+        @distance = distance
+        self
+      end
+
+      # Enables the ability to do something like:
+      # `expect(string).to match_approval(file).except(/\d+/)
+      def except(regex, replace = '...')
+        before ->(str) do
+          str.gsub regex, replace
+        end
+      end
+
+      # Enables the ability to adjust the actual string before checking
+      # for matches:
+      # `expect(a).to match_approval(f).before ->(actual) { actual.gsub /one/, 'two' }`
+      def before(proc)
+        @before ||= []
+        @before << proc
+        self
+      end
+
+      # Returns the expected value, from an approval file
+      def expected
+        @expected ||= expected!
+      end
+
+      # Called by RSpec when there is a failure
+      def failure_message
+        return "actual string is empty" if actual.empty?
+
+        result = "expected: #{actual}\nto match: #{expected}"
+        
+        if distance
+          result = "#{result}\n(actual distance is #{actual_distance} instead of the expected #{distance})"
+        end
+
+        result
+      end
+
+      # Lets RSpec know these matchers support diffing
+      def diffable?
+        true
+      end
+
+      # Returns true if RSpec is configured to sanitize (remove ANSI escape
+      # codes) from the actual strings before proceeeding to comparing them.
+      def sanitize?
+        RSpec.configuration.strip_ansi_escape
+      end
+
+      # Returns true if RSpec is configured to allow interactivity.
+      # By default, interactivity is enabled unless the environment 
+      # variable `CI` is set.
+      def interactive?
+        RSpec.configuration.interactive_approvals
+      end
+
+      # Returns the path to the approvals directory.
+      # Default: `spec/approvals`
+      def approvals_dir
+        RSpec.configuration.approvals_path
+      end
+
+      # Returns the path to the approval file
+      def approval_file
+        "#{approvals_dir}/#{approval_name}"
+      end
+      
+    protected
+
+      # Asks for user approval. Used by child classes.
+      def approve_approval
+        approval_handler = ApprovalHandler.new
+        approval_handler.run expected, actual, approval_file
+      end
+
+      # Returns the actual approval file content.
+      def expected!
+        File.exist?(approval_file) ? File.read(approval_file) : ''
+      end
+
+      # Do the actual test. 
+      # - If .before() was used, we foreward the actual output to the
+      #   proc for processing first.
+      # - If before_approval proc was configured, forward the acual output
+      #   to the proc for processing.
+      # - If .diff() was used, then distance will be set and then 
+      #   we "levenshtein it". 
+      # - Otherwise, compare with ==
+      def strings_match?
+        if @before
+          @before.each do |proc|
+            @actual = proc.call actual 
+          end
+        end
+        
+        if RSpec.configuration.before_approval.is_a? Proc
+          @actual = RSpec.configuration.before_approval.call actual
+        end
+
+        if distance
+          @actual_distance = String::Similarity.levenshtein_distance expected, actual
+          @actual_distance <= distance
+        else
+          actual == expected
+        end
+      end
+
+      # Returns the input string stripped of ANSI escape codes if the 
+      # strip_ansi_escape configuration setting was set to true
+      def sanitize(string)
+        sanitize? ? Strings::ANSI.sanitize(string) : string
+      end
+    end
+
+  end
+end

data/lib/rspec_approvals/matchers/match_approval.rb

@@ -0,0 +1,15 @@
+require 'string-similarity'
+
+module RSpecApprovals
+  module Matchers
+    # Adds the matcher to RSpec:
+    # `expect(string).to match_approval(file)`
+    def match_approval(expected)
+      MatchApproval.new expected
+    end
+    
+    class MatchApproval < Base
+    end
+    
+  end
+end

data/lib/rspec_approvals/matchers/output_approval.rb

@@ -0,0 +1,43 @@
+module RSpecApprovals
+  module Matchers
+    # Adds the matcher to RSpec:
+    # `expect { stream }.to output_approval(file)`
+    def output_approval(expected)
+      OutputApproval.new expected
+    end
+    
+    class OutputApproval < Base
+      # Called by RSpec
+      def matches?(block)
+        return false unless block.is_a? Proc
+        @actual = stream_capturer.capture block
+        super
+      end
+
+      # Lets RSpec know that this matcher requires a block.
+      def supports_block_expectations?
+        true
+      end
+
+      # Adds chained matcher, to allow:
+      # expect { stream }.to output_approval(file).to_stdout
+      # This is the default, and only provided for completeness.
+      def to_stdout
+        @stream_capturer = Stream::Stdout
+        self
+      end
+
+      # Adds chained matcher, to allow:
+      # expect { stream }.to output_approval(file).to_stderr
+      def to_stderr
+        @stream_capturer = Stream::Stderr
+        self
+      end
+
+      def stream_capturer
+        @stream_capturer ||= Stream::Stdout
+      end
+
+    end
+  end
+end

data/lib/rspec_approvals/matchers/raise_approval.rb

@@ -0,0 +1,30 @@
+module RSpecApprovals
+  module Matchers
+    # Adds the matcher to RSpec:
+    # `expect { something_that_errors }.to raise_approval(file)`
+    def raise_approval(expected)
+      RaiseApproval.new expected
+    end
+    
+    class RaiseApproval < Base
+      # Called by RSpec
+      def matches?(block)
+        return false unless block.is_a? Proc
+        @actual = 'Nothing raised'
+
+        begin
+          block.call
+        rescue => e
+          @actual = e.inspect
+        end
+
+        super
+      end
+
+      # Lets RSpec know that this matcher requires a block.
+      def supports_block_expectations?
+        true
+      end
+    end
+  end
+end

data/lib/rspec_approvals/module_functions.rb

@@ -0,0 +1,11 @@
+module RSpecApprovals
+  class << self
+    def stdout
+      @stdout ||= StringIO.new
+    end
+
+    def stderr
+      @stderr ||= StringIO.new
+    end
+  end
+end

data/lib/rspec_approvals/rspec_config.rb

@@ -0,0 +1,14 @@
+# Add our custom matchers and configuration options to RSpec
+if defined? RSpec
+  # Fix for rails
+  require 'rspec/core' unless RSpec.respond_to? :configure
+
+  RSpec.configure do |config|
+    config.include RSpecApprovals::Matchers
+    config.add_setting :approvals_path, default: File.expand_path('spec/approvals')
+    config.add_setting :interactive_approvals, default: (!ENV['CI'] and !ENV['GITHUB_ACTIONS'])
+    config.add_setting :auto_approve, default: ENV['AUTO_APPROVE']
+    config.add_setting :strip_ansi_escape, default: false
+    config.add_setting :before_approval, default: nil
+  end
+end

data/lib/rspec_approvals/stream.rb

@@ -0,0 +1,41 @@
+require 'strings-ansi'
+
+module RSpecApprovals
+  # Capture stdout and stderr
+  #
+  # These methods are borrowed from rspec's built in matchers
+  # https://github.com/rspec/rspec-expectations/blob/add9b271ecb1d65f7da5bc8a9dd8c64d81d92303/lib/rspec/matchers/built_in/output.rb
+  module Stream
+    module Stdout
+      def self.capture(block)
+        RSpecApprovals.stdout.truncate 0
+        RSpecApprovals.stdout.rewind
+
+        original_stream = $stdout
+        $stdout = RSpecApprovals.stdout
+        block.call
+        RSpecApprovals.stdout.string.dup
+
+      ensure
+        $stdout = original_stream
+
+      end
+    end
+
+    module Stderr
+      def self.capture(block)
+        RSpecApprovals.stderr.truncate 0
+        RSpecApprovals.stderr.rewind
+
+        original_stream = $stderr
+        $stderr = RSpecApprovals.stderr
+        block.call
+        RSpecApprovals.stderr.string.dup
+
+      ensure
+        $stderr = original_stream
+
+      end
+    end
+  end
+end

data/lib/rspec_approvals/version.rb

@@ -0,0 +1,3 @@
+module RSpecApprovals
+  VERSION = "0.8.0.rc1"
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: rspec_approvals
+version: !ruby/object:Gem::Version
+  version: 0.8.0.rc1
+platform: ruby
+authors:
+- Danny Ben Shitrit
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-05-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: colsole
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: string-similarity
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: diffy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: tty-prompt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+- !ruby/object:Gem::Dependency
+  name: strings-ansi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: Automatic interactive approvals for rspec
+email: db@dannyben.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/rspec_approvals.rb
+- lib/rspec_approvals/approval_handler.rb
+- lib/rspec_approvals/extensions/file.rb
+- lib/rspec_approvals/matchers/base.rb
+- lib/rspec_approvals/matchers/match_approval.rb
+- lib/rspec_approvals/matchers/output_approval.rb
+- lib/rspec_approvals/matchers/raise_approval.rb
+- lib/rspec_approvals/module_functions.rb
+- lib/rspec_approvals/rspec_config.rb
+- lib/rspec_approvals/stream.rb
+- lib/rspec_approvals/version.rb
+homepage: https://github.com/DannyBen/rspec_approvals
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: Interactive RSpec Approvals
+test_files: []