blood_contracts 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 234b795bf582f8978bd4ba789c388cbad2539e20
-  data.tar.gz: 46f86eb3b20f692d9fa948fb58e275a94d921012
+SHA256:
+  metadata.gz: 6a3374d5e7af34959e56cb4f31d22cd807fe84f3ee1f74e9446646b7d4b49f27
+  data.tar.gz: 48907e94554abde9079f25e8a657fc24dbda9fac02468f239c547031eff0df0e
 SHA512:
-  metadata.gz: a7bd966f422b0020d06d981680811c1466859214dbcb90ab346516b403e4216f4cb3355773f697482b75f2b8818c4f419571715d5ee0604aaf975978d31033f4
-  data.tar.gz: a400a28a9d84ab53321a1b13c134b1c0bfcfa40c09bde47b1666bac429461869fabb702ec72bf6222b9634d65398fd66f97c8bb750b51a65e4d7340630c1a380
+  metadata.gz: 9fc96fb5b769b22fb747573dd4ae5bf8da1cf2a40e429ddde58f82d78263aba3e9957d31183c0c5b0af3206abe0172e511d10e312d9624c0533cef030c502d84
+  data.tar.gz: c22e684f33f0d4f4ab37a5e08174c4dcefae73afa09079250eb1b158c2e03d572be92a40a202a2724f8bf0026e91fd8b89308cb1843de2f8f6ceff0d9fa4ff92

data/.gitignore

@@ -9,3 +9,4 @@
 
 # rspec failure tracking
 .rspec_status
+Gemfile.lock

data/Gemfile

@@ -1,6 +1,6 @@
 source "https://rubygems.org"
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in blood_contracts.gemspec
 gemspec

data/README.md

@@ -7,6 +7,8 @@ Possible use-cases:
 - Automated detection of unexpected external API behavior (Rack::request/response pairs that don't match contract);
 - Contract definition assistance tool (generate real-a-like requests and iterate through oddities of your system behavior)
 
+<a href="https://evilmartians.com/">
+<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
 
 ## Installation
 

data/Rakefile

@@ -3,4 +3,4 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/bin/console

@@ -7,8 +7,5 @@ require "blood_contracts"
 # 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(__FILE__)
+require "pry"
+Pry.start

data/blood_contracts.gemspec

@@ -5,12 +5,13 @@ require "blood_contracts/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "blood_contracts"
+
   spec.version       = BloodContracts::VERSION
   spec.authors       = ["Sergey Dolganov"]
   spec.email         = ["dolganov@evl.ms"]
 
-  spec.summary       = %q{Ruby gem to define and validate behavior of API using contracts.}
-  spec.description   = %q{Ruby gem to define and validate behavior of API using contracts.}
+  spec.summary       = "Ruby gem to define and validate behavior of API using contracts."
+  spec.description   = "Ruby gem to define and validate behavior of API using contracts."
   spec.homepage      = "https://github.com/sclinede/blood_contracts"
   spec.license       = "MIT"
 
@@ -23,12 +24,14 @@ Gem::Specification.new do |spec|
   # spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "dry-initializer", "~> 2.0"
+  spec.required_ruby_version = '>= 2.2.0'
 
-  # Will be removed soon
-  spec.add_runtime_dependency "activesupport", ">= 3.1"
+  spec.add_runtime_dependency "dry-initializer", "~> 2.0"
+  spec.add_runtime_dependency "nanoid", "~> 0.2"
+  spec.add_runtime_dependency "hashie", "~> 3.0"
 
   spec.add_development_dependency "bundler", "~> 1.16"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "pry", "~> 0.9"
 end

data/lib/blood_contracts/base_contract.rb

@@ -0,0 +1,42 @@
+module BloodContracts
+  class BaseContract
+    extend Dry::Initializer
+    option :action
+
+    class << self
+      def rules
+        @rules ||= Set.new
+      end
+
+      def contract_rule(name, &block)
+        define_method("_#{name}", block)
+        rules << name
+      end
+    end
+
+    def call(data)
+      return yield(data) if block_given?
+      action.call(data)
+    end
+
+    def contract
+      @contract ||= Hash[
+        self.class.rules.map { |name| [name, {check: method("_#{name}")}] }
+      ]
+    end
+
+    def build_storage(name)
+      s = Storage.new(contract_name: name)
+      s.input_writer  = method(:input_writer)  if defined? input_writer
+      s.output_writer = method(:output_writer) if defined? output_writer
+      s.input_serializer  = input_serializer   if defined? input_serializer
+      s.output_serializer = output_serializer  if defined? output_serializer
+      s.meta_serializer   = meta_serializer    if defined? meta_serializer
+      s
+    end
+
+    def to_contract_suite(name: self.class.to_s.pathize)
+      Suite.new(storage: build_storage(name), contract: contract)
+    end
+  end
+end

data/lib/blood_contracts/contracts/description.rb

@@ -0,0 +1,25 @@
+module BloodContracts
+  module Contracts
+    class Description
+      def self.call(contract_hash)
+        Hashie::Mash.new(contract_hash).map do |name, rule|
+          rule_description = " - '#{name}' "
+          if rule.threshold
+            rule_description << <<~TEXT
+              in more then #{(rule.threshold * 100).round(2)}% of cases;
+            TEXT
+          elsif rule.limit
+            rule_description << <<~TEXT
+              in less then #{(rule.limit * 100).round(2)}% of cases;
+            TEXT
+          else
+            rule_description << <<~TEXT
+              in any number of cases;
+            TEXT
+          end
+          rule_description
+        end.compact.join
+      end
+    end
+  end
+end

data/lib/blood_contracts/contracts/matcher.rb

@@ -0,0 +1,38 @@
+module BloodContracts
+  module Contracts
+    class Matcher
+      extend Dry::Initializer
+
+      param :contract_hash, ->(v) { Hashie::Mash.new(v) }
+
+      def call(input, output, meta = Hash.new, storage:)
+        options = Hashie::Mash.new(input: input, output: output, meta: meta)
+
+        rule_names = select_matched_rules!(options).keys
+        rule_names = [Storage::UNDEFINED_RULE] if rule_names.empty?
+        Array(rule_names).each(&storage.method(:store))
+
+        yield rule_names, options if block_given?
+
+        !storage.found_unexpected_behavior?
+      end
+
+      private
+
+      def with_rule_options(rule_name, options)
+        rule_options = options.shallow_merge(meta: {})
+        result = yield(rule_options)
+        options.meta.merge!(rule_name.to_sym => rule_options.meta)
+        result
+      end
+
+      def select_matched_rules!(options)
+        contract_hash.select do |name, rule|
+          with_rule_options(name, options) do |rule_options|
+            rule.check.call(rule_options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/blood_contracts/contracts/validator.rb

@@ -0,0 +1,47 @@
+module BloodContracts
+  module Contracts
+    class Validator
+      extend Dry::Initializer
+
+      param :contract_hash, ->(v) { Hashie::Mash.new(v) }
+
+      def valid?(statistics)
+        return if statistics.found_unexpected_behavior?
+
+        last_run_stats = statistics.to_h
+        expectations.all? do |rule, check|
+          percent = last_run_stats[rule.name]&.percent || 0.0
+          check.call(percent, rule)
+        end
+      end
+
+      private
+
+      def expectations
+        Hash[
+          contract_hash.map do |name, rule|
+            if rule.threshold
+              [rule.merge(name: name), method(:threshold_check)]
+            elsif rule.limit
+              [rule.merge(name: name), method(:limit_check)]
+            else
+              [rule.merge(name: name), method(:anyway)]
+            end
+          end.compact
+        ]
+      end
+
+      def threshold_check(value, rule)
+        value > rule.threshold
+      end
+
+      def limit_check(value, rule)
+        value <= rule.limit
+      end
+
+      def anyway(_value, _rule)
+        true
+      end
+    end
+  end
+end

data/lib/blood_contracts/debugger.rb

@@ -0,0 +1,39 @@
+module BloodContracts
+  class Debugger < Runner
+    def runs
+      @runs ||= storage.find_all_samples(ENV["debug"]).each
+    end
+
+    def iterations
+      runs.size
+    end
+
+    def call
+      return super if debugging_samples?
+      true
+    end
+
+    def description
+      return super if debugging_samples?
+      "be skipped in current debugging session"
+    end
+
+    private
+
+    def match_rules?(matches_storage:)
+      matcher.call(*storage.load_sample(runs.next), storage: matches_storage)
+    end
+
+    def unexpected_further_investigation
+      ENV["debug"]
+    end
+
+    def further_investigation
+      ENV["debug"]
+    end
+
+    def debugging_samples?
+      runs.size.positive?
+    end
+  end
+end

data/lib/blood_contracts/runner.rb

@@ -1,93 +1,89 @@
+require_relative "contracts/validator"
+require_relative "contracts/matcher"
+require_relative "contracts/description"
+
 module BloodContracts
   class Runner
     extend Dry::Initializer
 
     param :checking_proc
-    option :context, optional: true
 
     option :suite
+    option :storage, default: -> { suite.storage }
 
     option :iterations, ->(v) do
       v = ENV["iterations"] if ENV["iterations"]
       v.to_i.positive? ? v.to_i : 1
     end, default: -> { 1 }
-
-
     option :time_to_run, ->(v) do
       v = ENV["duration"] if ENV["duration"]
       v.to_f if v.to_f.positive?
     end, optional: true
 
+    option :context, optional: true
     option :stop_on_unexpected, default: -> { false }
 
+    option :statistics, default: -> { Statistics.new(iterations) }
+    option :matcher,   default: -> { Contracts::Matcher.new(suite.contract) }
+    option :validator, default: -> { Contracts::Validator.new(suite.contract) }
+    option :contract_description, default: -> do
+      Contracts::Description.call(suite.contract)
+    end
+
     def call
       iterate do
-        unexpected = match_rules(*run) do |input, output, rules|
-          suite.storage.save_run(
-            input: input, output: output, rules: rules, context: context,
-          )
-        end.empty?
-        throw :unexpected_behavior, :stop if stop_on_unexpected && unexpected
+        next if match_rules?(matches_storage: statistics) do
+          input = suite.data_generator.call
+          [input, checking_proc.call(input)]
+        end
+        throw :unexpected_behavior, :stop if stop_on_unexpected
       end
-      valid?
-    end
-
-    def valid?
       return if stopped_by_unexpected_behavior?
-      return if found_unexpected_behavior?
 
-      last_run_stats = run_stats
-      expectations_checks.all? do |rule, check|
-        percent = last_run_stats[rule.name]&.percent || 0.0
-        check.call(percent, rule)
-      end
-    end
-
-    def found_unexpected_behavior?
-      run_stats.key?(Storage::UNDEFINED_RULE)
+      validator.valid?(statistics)
     end
 
+    # FIXME: Move to locales
     def failure_message
       intro = "expected that given Proc would meet the contract:"
 
-      if found_unexpected_behavior?
+      if validator.expected_behavior?
         "#{intro}\n#{contract_description}\n"\
-        " during #{iterations} run(s) but got unexpected behavior.\n\n"\
-        "For further investigations open: #{unexpected_behavior_report_path}/"
+          " during #{iterations} run(s) but got:\n#{statistics}\n\n"\
+          "For further investigations open: #{storage.suggestion}"
       else
         "#{intro}\n#{contract_description}\n"\
-        " during #{iterations} run(s) but got:\n#{stats_description}\n\n"\
-        "For further investigations open: #{suite.storage.path}"
+        " during #{iterations} run(s) but got unexpected behavior.\n\n"\
+        "For further investigations open: #{storage.unexpected_suggestion}"
       end
     end
 
-    def unexpected_behavior_report_path
-      File.join(suite.storage.path, Storage::UNDEFINED_RULE.to_s)
-    end
-
+    # FIXME: Move to locales
     def description
       "meet the contract:\n#{contract_description} \n"\
-      " during #{iterations} run(s). Stats:\n#{stats_description}\n\n"\
-      "For further investigations open: #{suite.storage.path}\n"
+      " during #{iterations} run(s). Stats:\n#{statistics}\n\n"\
+      "For further investigations open: #{storage.suggestion}\n"
     end
 
-    private
+    protected
 
-    def run
-      input = suite.data_generator.call
-      [input, checking_proc.call(input)]
+    def match_rules?(matches_storage:)
+      matcher.call(*yield, storage: matches_storage) do |rules, options|
+        storage.store(options: options, rules: rules, context: context)
+      end
+    rescue StandardError => error
+      # FIXME: Possible recursion?
+      # Write test about error in the storage#store (e.g. writing error)
+      store_exception(error, input, output, context)
+      raise
     end
 
     def stopped_by_unexpected_behavior?
       @_stopped_by_unexpected_behavior == :stop
     end
 
-    def stats
-      suite.storage.stats
-    end
-
     def iterate
-      run_iterations = iterations
+      run_iterations ||= iterations
 
       if time_to_run
         run_iterations = iterations_count_from_time_to_run { yield }
@@ -104,80 +100,16 @@ module BloodContracts
       (time_to_run / time_per_action.real).ceil
     end
 
-    def match_rules(input, output)
-      matched_rules = suite.contract.select do |_name, rule|
-        rule.check.call(input, output)
-      end.keys
-      matched_rules = [Storage::UNDEFINED_RULE] if matched_rules.empty?
-      yield(input, output, matched_rules)
-
-      matched_rules
-      # FIXME: Possible recursion?
-      # Write test about error in the yield (e.g. writing error)
-    rescue => e
-      yield [Storage::UNDEFINED_RULE]
-      raise e
-    end
-
-    def threshold_check(value, rule)
-      value > rule.threshold
-    end
-
-    def limit_check(value, rule)
-      value <= rule.limit
-    end
-
-    def expectations_checks
-      Hash[
-        suite.contract.map do |name, rule|
-          if rule.threshold
-            [rule.merge(name: name), method(:threshold_check)]
-          elsif rule.limit
-            [rule.merge(name: name), method(:limit_check)]
-          else
-            nil
-          end
-        end.compact
-      ]
-    end
-
-    def contract_description
-      suite.contract.map do |name, rule|
-        rule_description = " - '#{name}' "
-        if rule.threshold
-          rule_description << <<~TEXT
-            in more then #{(rule.threshold * 100).round(2)}% of cases;
-          TEXT
-        elsif rule.limit
-          rule_description << <<~TEXT
-            in less then #{(rule.limit * 100).round(2)}% of cases;
-          TEXT
-        else
-          next
-        end
-        rule_description
-      end.compact.join
-    end
-
-    def stats_description
-      run_stats.map do |name, occasions|
-        " - '#{name}' happened #{occasions.times} time(s) "\
-        "(#{(occasions.percent * 100).round(2)}% of the time)"
-      end.join("; \n")
-    end
-
-    def run_stats
-      Hash[
-        stats.map do |rule_name, times|
-          [
-            rule_name,
-            Hashie::Mash.new(
-              times: times,
-              percent: (times.to_f / iterations),
-            ),
-          ]
-        end
-      ]
+    def store_exception(error, input, output, context)
+      storage.store(
+        options: {
+          input: input,
+          output: output || {},
+          meta: {exception: error},
+        },
+        rules: [Storage::EXCEPTION_CAUGHT],
+        context: context,
+      )
     end
   end
 end

data/lib/blood_contracts/statistics.rb

@@ -0,0 +1,32 @@
+module BloodContracts
+  class Statistics
+    extend Dry::Initializer
+    param :iterations
+    option :storage, default: -> { Hash.new(0) }
+
+    def store(rule)
+      storage[rule] += 1
+    end
+
+    def to_h
+      Hash[storage.map { |rule_name, times| [rule_name, rule_stats(times)] }]
+    end
+
+    def to_s
+      to_h.map do |name, occasions|
+        " - '#{name}' happened #{occasions.times} time(s) "\
+        "(#{(occasions.percent * 100).round(2)}% of the time)"
+      end.join("; \n")
+    end
+
+    def found_unexpected_behavior?
+      storage.key?(Storage::UNDEFINED_RULE)
+    end
+
+    private
+
+    def rule_stats(times)
+      Hashie::Mash.new(times: times, percent: (times.to_f / iterations))
+    end
+  end
+end

data/lib/blood_contracts/storage.rb

@@ -1,79 +1,79 @@
+require_relative "./storages/base_backend.rb"
+require_relative "./storages/file_backend.rb"
+require_relative "./storages/serializer.rb"
+
 module BloodContracts
   class Storage
     extend Dry::Initializer
+    extend Forwardable
 
-    # Split date and time, for more comfortable Dirs navigation
-    option :start_time, default: -> { Time.current.to_s(:number) }
-    option :custom_path, optional: true
-    option :root, default: -> { Rails.root.join(path) }
-    option :stats, default: -> { Hash.new(0) }
-    option :input_writer,  optional: true
-    option :output_writer, optional: true
+    Serializer = BloodContracts::Storages::Serializer
+    FileBackend = BloodContracts::Storages::FileBackend
 
-    UNDEFINED_RULE = :__no_tag_match__
+    option :contract_name
 
-    def default_path
-      "./tmp/contract_tests/"
+    DEFAULT_WRITER = -> (options) do
+      "INPUT:\n#{options.input}\n\n#{'=' * 90}\n\nOUTPUT:\n#{options.output}"
     end
 
-    def path
-      @path ||= File.join(default_path, custom_path.to_s, start_time)
+    option :input_writer,
+           ->(v) { valid_writer(v) }, default: -> { DEFAULT_WRITER }
+    option :output_writer,
+           ->(v) { valid_writer(v) }, default: -> { DEFAULT_WRITER }
+
+    option :input_serializer,
+           ->(v) { Serializer.call(v) }, default: -> { default_serializer }
+    option :output_serializer,
+           ->(v) { Serializer.call(v) }, default: -> { default_serializer }
+    option :meta_serializer,
+           ->(v) { Serializer.call(v) }, default: -> { default_serializer }
+
+    option :backend, default: -> { FileBackend.new(self, contract_name) }
+
+    def_delegators :@backend, :sample_exists?,
+                   :load_sample, :find_all_samples,
+                   :serialize_sample, :describe_sample,
+                   :suggestion, :unexpected_suggestion
+
+    def self.valid_writer(writer)
+      return writer if writer.respond_to?(:call) || writer.respond_to?(:to_sym)
+      raise ArgumentError
     end
 
-    def input_writer=(writer)
-      fail ArgumentError unless writer.respond_to?(:call) ||
-                                writer.respond_to?(:to_sym)
-      @input_writer = writer
+    def input_serializer=(serializer)
+      @input_serializer = Serializer.call(serializer)
     end
 
-    def output_writer=(writer)
-      fail ArgumentError unless writer.respond_to?(:call) ||
-                                writer.respond_to?(:to_sym)
-      @output_writer = writer
+    def output_serializer=(serializer)
+      @output_serializer = Serializer.call(serializer)
     end
 
-    def run_name(tag)
-      run_name = File.join(root, "#{tag}/#{Time.current.to_s(:number)}")
-      FileUtils.mkdir_p File.join(root, "#{tag}")
-      run_name
+    def meta_serializer=(serializer)
+      @meta_serializer = Serializer.call(serializer)
     end
 
-    def write(writer, context, input, output)
-      return default_write_pattern(input, output) unless writer
-      writer = context.method(writer) if context && writer.respond_to?(:to_sym)
-      writer.call(input, output)
+    def input_writer=(writer)
+      @input_writer = self.class.valid_writer(writer)
     end
 
-    def default_write_pattern(input, output)
-      [
-        "INPUT:",
-        input,
-        "\n#{'=' * 90}\n",
-        "OUTPUT:",
-        output
-      ].map(&:to_s).join("\n")
+    def output_writer=(writer)
+      @output_writer = self.class.valid_writer(writer)
+    end
 
+    UNDEFINED_RULE = :__no_tag_match__
+    EXCEPTION_CAUGHT = :__exception_raised__
+
+    def default_serializer
+      { load: Oj.method(:load), dump: Oj.method(:dump) }
     end
 
     # Quick open: `vim -O tmp/contract_tests/<tstamp>/<tag>/<tstamp>.*`
-    def save_run(input:, output:, rules:, context:)
+    def store(options:, rules:, context:)
+      options = Hashie::Mash.new(options)
+
       Array(rules).each do |rule_name|
-        stats[rule_name] += 1
-        run_name = run_name(rule_name)
-
-        # TODO: Write to HTML
-        input_fname = "#{run_name}.input"
-        output_fname = "#{run_name}.output"
-        File.open(input_fname, "w+") do |f|
-          f << write(input_writer, context, input, output).encode(
-            'UTF-8', invalid: :replace, undef: :replace, replace: '?'
-          )
-        end
-        File.open(output_fname, "w+") do |f|
-          f << write(output_writer, context, input, output).encode(
-            'UTF-8', invalid: :replace, undef: :replace, replace: '?'
-          )
-        end
+        describe_sample(rule_name, options, context)
+        serialize_sample(rule_name, options, context)
       end
     end
   end

data/lib/blood_contracts/storages/base_backend.rb

@@ -0,0 +1,59 @@
+require 'nanoid'
+
+module BloodContracts
+  module Storages
+    class BaseBackend
+      extend Dry::Initializer
+      extend Forwardable
+
+      param :storage
+      param :example_name
+      option :name, default: -> do
+        BloodContracts.run_name || ::Nanoid.generate(size: 10)
+      end
+      def_delegators :@storage, :input_writer, :output_writer,
+                     :input_serializer, :output_serializer, :meta_serializer
+
+
+      def sample_exists?(sample_name)
+        raise NotImplementedError
+      end
+
+      def find_all_samples(run, tag, sample)
+        raise NotImplementedError
+      end
+
+      def load_sample(_sample_name)
+        %i(input output meta).map do |type|
+          load_sample_chunk(type, _sample_name)
+        end
+      end
+
+      def load_sample_chunk(_dump_type, _sample_name)
+        raise NotImplementedError
+      end
+
+      def describe_sample(_tag, _options, _context)
+        raise NotImplementedError
+      end
+
+      def serialize_sample(tag, options, context)
+        %i(input output meta).each do |type|
+          serialize_sample_chunk(type, tag, options, context)
+        end
+      end
+
+      def serialize_sample_chunk(_type, _tag, _option, _context)
+        raise NotImplementedError
+      end
+
+      def suggestion
+        raise NotImplementedError
+      end
+
+      def unexpected_suggestion
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/blood_contracts/storages/file_backend.rb

@@ -0,0 +1,132 @@
+module BloodContracts
+  module Storages
+    class FileBackend < BaseBackend
+      option :root, default: -> { Rails.root.join(path) }
+
+      def suggestion
+        "#{path}/*/*"
+      end
+
+      def unexpected_suggestion
+        "#{path}/#{Storage::UNDEFINED_RULE}/*"
+      end
+
+      def default_path
+        "./tmp/contract_tests/"
+      end
+
+      def timestamp
+        @timestamp ||= Time.current.to_s(:usec)[8..-3]
+      end
+
+      def reset_timestamp!
+        @timestamp = nil
+      end
+
+      def parse_sample_name(sample_name)
+        path_items = sample_name.split("/")
+        sample = path_items.pop
+        tag = path_items.pop
+        path_str = path_items.join("/")
+        run_n_example_str = path_str.sub(default_path, '')
+        if run_n_example_str.end_with?('*')
+          [
+            run_n_example_str.chomp("*"),
+            tag,
+            sample
+          ]
+        elsif run_n_example_str.end_with?(example_name)
+          [
+            run_n_example_str.chomp(example_name),
+            tag,
+            sample
+          ]
+        else
+          %w(__no_match__ __no_match__ __no_match__)
+        end
+      end
+
+      def find_all_samples(sample_name)
+        run, tag, sample = parse_sample_name(sample_name)
+        run_path = path(run_name: run)
+        files = Dir.glob("#{run_path}/#{tag.to_s}/#{sample}*")
+        files.select { |f| f.end_with?(".output") }
+             .map { |f| f.chomp(".output") }
+      end
+
+      def path(run_name: name)
+        File.join(default_path, run_name, example_name.to_s)
+      end
+
+      def sample_name(tag, run_path: root, sample: timestamp)
+        File.join(run_path, tag.to_s, sample)
+      end
+
+      def sample_exists?(sample_name)
+        run, tag, sample = parse_sample_name(sample_name)
+        name = sample_name(tag, run_path: path(run_name: run), sample: sample)
+        File.exist?("#{name}.input")
+      end
+
+      def load_sample_chunk(dump_type, sample_name)
+        run, tag, sample = parse_sample_name(sample_name)
+        name = sample_name(tag, run_path: path(run_name: run), sample: sample)
+        send("#{dump_type}_serializer")[:load].call(
+          File.read("#{name}.#{dump_type}.dump")
+        )
+      end
+
+      def write(writer, cntxt, options)
+        writer = cntxt.method(writer) if cntxt && writer.respond_to?(:to_sym)
+        writer.call(options).encode(
+          "UTF-8", invalid: :replace, undef: :replace, replace: "?",
+        )
+      end
+
+      def describe_sample(tag, options, context)
+        FileUtils.mkdir_p File.join(root, tag.to_s)
+
+        reset_timestamp!
+        name = sample_name(tag)
+        File.open("#{name}.input", "w+") do |f|
+          f << write(input_writer, context, options)
+        end
+        File.open("#{name}.output", "w+") do |f|
+          f << write(output_writer, context, options)
+        end
+      end
+
+      def serialize_sample_chunk(type, tag, options, context)
+        return unless (dump_proc = send("#{type}_serializer")[:dump])
+        name, data = sample_name(tag), options.send(type)
+        File.open("#{name}.#{type}.dump", "w+") do |f|
+          f << write(dump_proc, context, data)
+        end
+      end
+      #
+      # def serialize_input(tag, options, context)
+      #   return unless (dump_proc = input_serializer[:dump])
+      #   name = sample_name(tag)
+      #   File.open("#{name}.input.dump", "w+") do |f|
+      #     f << write(dump_proc, context, options.input)
+      #   end
+      # end
+      #
+      # def serialize_output(tag, options, context)
+      #   return unless (dump_proc = output_serializer[:dump])
+      #   name = sample_name(tag)
+      #   File.open("#{name}.output.dump", "w+") do |f|
+      #     f << write(dump_proc, context, options.output)
+      #   end
+      # end
+      #
+      # def serialize_meta(tag, options, context)
+      #   return unless (dump_proc = meta_serializer[:dump])
+      #   name = sample_name(tag)
+      #   File.open("#{name}.meta.dump", "w+") do |f|
+      #     f << write(dump_proc, context, options.meta)
+      #   end
+      # end
+    end
+  end
+end

data/lib/blood_contracts/storages/serializer.rb

@@ -0,0 +1,38 @@
+module BloodContracts
+  module Storages
+    class Serializer
+      extend Dry::Initializer
+
+      param :serializer
+
+      def self.call(*args)
+        new(*args).call
+      end
+
+      def call
+        return object_serializer_to_hash if object_serializer?
+        return serializer.to_hash if hash_serializer?
+
+        raise "Both #dump and #load methods should be defined for serialization"
+      end
+
+      private
+
+      def object_serializer?
+        serializer.respond_to?(:dump) && serializer.respond_to?(:load)
+      end
+
+      def object_serializer_to_hash
+        {
+          load: serializer.method(:load),
+          dump: serializer.method(:dump),
+        }
+      end
+
+      def hash_serializer?
+        return unless serializer.respond_to?(:to_hash)
+        (%i[dump load] - serializer.to_hash.keys).empty?
+      end
+    end
+  end
+end

data/lib/blood_contracts/suite.rb

@@ -3,19 +3,24 @@ module BloodContracts
     extend Dry::Initializer
 
     option :data_generator, optional: true
-    option :contract, default: -> { Hashie::Mash.new }
-    option :input_writer, optional: true
+    option :contract, ->(v) { Hashie::Mash.new(v) }, default: -> { Hash.new }
+
+    option :input_writer,  optional: true
     option :output_writer, optional: true
+
+    option :input_serializer,  ->(v) { parse_serializer(v) }, optional: true
+    option :output_serializer, ->(v) { parse_serializer(v) }, optional: true
+
     option :storage_backend, optional: true
     option :storage, default: -> { default_storage }
 
     def data_generator=(generator)
-      fail ArgumentError unless generator.respond_to?(:call)
+      raise ArgumentError unless generator.respond_to?(:call)
       @data_generator = generator
     end
 
     def contract=(contract)
-      fail ArgumentError unless contract.respond_to?(:to_h)
+      raise ArgumentError unless contract.respond_to?(:to_h)
       @contract = Hashie::Mash.new(contract.to_h)
     end
 
@@ -28,7 +33,12 @@ module BloodContracts
     end
 
     def default_storage
-      Storage.new(input_writer: input_writer, output_writer: output_writer)
+      Storage.new(
+        input_writer: input_writer,
+        output_writer: output_writer,
+        input_serializer: input_serializer,
+        output_serializer: output_serializer,
+      )
     end
   end
 end

data/lib/blood_contracts/version.rb

@@ -1,3 +1,3 @@
 module BloodContracts
-  VERSION = "0.1.0"
+  VERSION = "0.2.0".freeze
 end

data/lib/blood_contracts.rb

@@ -1,88 +1,38 @@
 require "blood_contracts/version"
+
+require_relative "extensions/string.rb"
+require "dry-initializer"
+require "hashie/mash"
+
 require_relative "blood_contracts/suite"
 require_relative "blood_contracts/storage"
+require_relative "blood_contracts/statistics"
 require_relative "blood_contracts/runner"
+require_relative "blood_contracts/debugger"
+require_relative "blood_contracts/base_contract"
 
 module BloodContracts
+  def run_name
+    @__contracts_run_name
+  end
+  module_function :run_name
 
-  # Use https://github.com/razum2um/lurker/blob/master/lib/lurker/spec_helper/rspec.rb
-  if defined?(RSpec) && RSpec.respond_to?(:configure)
-    module MeetContractMatcher
-      extend RSpec::Matchers::DSL
-
-      matcher :meet_contract_rules do |options|
-        match do |actual|
-          raise ArgumentError unless actual.respond_to?(:call)
-
-          @_contract_runner = Runner.new(
-            actual,
-            context: self,
-            suite: build_suite(options),
-            iterations: @_iterations,
-            time_to_run: @_time_to_run,
-            stop_on_unexpected: @_halt_on_unexpected,
-          )
-          @_contract_runner.call
-        end
-
-        def build_suite(options)
-          storage = Storage.new(custom_path: _example_name_to_path)
-          storage.input_writer  = _input_writer  if _input_writer
-          storage.output_writer = _output_writer if _output_writer
-
-          suite = options[:contract_suite] || Suite.new(storage: storage)
-
-          suite.data_generator = @_generator        if @_generator
-          suite.contract       = options[:contract] if options[:contract]
-          suite
-        end
-
-        def _example_name_to_path
-          method_missing(:class).
-            name.
-            sub("RSpec::ExampleGroups::", "").
-            snakecase
-        end
-
-        def _input_writer
-          input_writer = @_writers.to_h[:input]
-          input_writer ||= :input_writer if defined? self.input_writer
-          input_writer
-        end
-
-        def _output_writer
-          output_writer = @_writers.to_h[:output]
-          output_writer ||= :output_writer if defined? self.output_writer
-          output_writer
-        end
-
-        supports_block_expectations
-
-        failure_message { @_contract_runner.failure_message }
-
-        description { @_contract_runner.description }
-
-        chain :using_generator do |generator|
-          if generator.respond_to?(:to_sym)
-            @_generator = method(generator.to_sym)
-          else
-            fail ArgumentError unless generator.respond_to?(:call)
-            @_generator = generator
-          end
-        end
-
-        chain :during_n_iterations_run do |iterations|
-          @_iterations = Integer(iterations)
-        end
-
-        chain :during_n_seconds_run do |time_to_run|
-          @_time_to_run = Float(time_to_run)
-        end
+  def run_name=(run_name)
+    @__contracts_run_name = run_name
+  end
+  module_function :run_name=
 
-        chain :halt_on_unexpected do
-          @_halt_on_unexpected = true
-        end
+  if defined?(RSpec) && RSpec.respond_to?(:configure)
+    require_relative "rspec/meet_contract_matcher"
 
+    RSpec.configure do |config|
+      config.include ::RSpec::MeetContractMatcher
+      config.filter_run_excluding contract: true
+      config.before(:suite) do
+        BloodContracts.run_name = ::Nanoid.generate(size: 10)
+      end
+      config.define_derived_metadata(file_path: %r{/spec/contracts/}) do |meta|
+        meta[:contract] = true
       end
     end
   end

data/lib/extensions/string.rb

@@ -0,0 +1,31 @@
+class String
+  # See gem Facets String#pathize
+
+  # Transforms a namespace, i.e. a class or module name, into a viable
+  # file path.
+  #
+  #   "ExamplePathize".pathize           #=> "example_pathize"
+  #   "ExamplePathize::Example".pathize  #=> "example_pathize/example"
+  #
+  # Compare this method to {String#modulize) and {String#methodize).
+  #
+  def pathize
+    gsub(/([A-Z]+)([A-Z])/,'\1_\2').
+    gsub(/([a-z])([A-Z])/,'\1_\2').
+    gsub('__','/').
+    gsub('::','/').
+    gsub(/\s+/, '').                # spaces are bad form
+    gsub(/[?%*:|"<>.]+/, '').   # reserved characters
+    downcase
+  end
+
+  # Compare to Rails definition:
+  #
+  #    gsub(/__/, '/').
+  #    gsub(/::/, '/').
+  #    gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+  #    gsub(/([a-z\d])([A-Z])/,'\1_\2').
+  #    tr("-", "_").
+  #    downcase
+  #
+end

data/lib/rspec/meet_contract_matcher.rb

@@ -0,0 +1,104 @@
+module RSpec
+  module MeetContractMatcher
+    extend RSpec::Matchers::DSL
+    Runner = ::BloodContracts::Runner
+    Debugger = ::BloodContracts::Debugger
+
+    matcher :meet_contract_rules do |args|
+      match do |subject|
+        runner = ENV["debug"] ? Debugger : Runner
+
+        @_contract_runner = runner.new(
+          subject,
+          context: self,
+          suite: build_suite(args || subject),
+          iterations: @_iterations,
+          time_to_run: @_time_to_run,
+          stop_on_unexpected: @_halt_on_unexpected,
+        )
+        @_contract_runner.call
+      end
+
+      def build_suite(args)
+        suite = nil
+        if args.respond_to?(:to_contract_suite)
+          suite = args.to_contract_suite(name: _example_name_to_path)
+        elsif args.respond_to?(:to_hash) && args.fetch(:contract) { false }
+          suite = ::BloodContracts::Suite.new(storage: new_storage)
+          suite.contract = args[:contract]
+        else
+          raise "Matcher arguments is not a Blood Contract"
+        end
+        suite.data_generator = @_generator if @_generator
+        suite
+      end
+
+      def new_storage
+        storage = Storage.new(contract_name: _example_name_to_path)
+        storage.input_writer  = _input_writer  if _input_writer
+        storage.output_writer = _output_writer if _output_writer
+        if @_input_serializer
+          storage.input_serializer  = @_input_serializer
+        end
+        if @_output_serializer
+          storage.output_serializer = @_output_serializer
+        end
+        storage
+      end
+
+      def _example_name_to_path
+        method_missing(:class)
+          .name
+          .sub("RSpec::ExampleGroups::", "")
+          .pathize
+      end
+
+      def _input_writer
+        input_writer = @_writers.to_h[:input]
+        input_writer ||= :input_writer if defined? self.input_writer
+        input_writer
+      end
+
+      def _output_writer
+        output_writer = @_writers.to_h[:output]
+        output_writer ||= :output_writer if defined? self.output_writer
+        output_writer
+      end
+
+      supports_block_expectations
+
+      failure_message { @_contract_runner.failure_message }
+
+      description { @_contract_runner.description }
+
+      chain :using_generator do |generator|
+        if generator.respond_to?(:to_sym)
+          @_generator = method(generator.to_sym)
+        else
+          raise ArgumentError unless generator.respond_to?(:call)
+          @_generator = generator
+        end
+      end
+
+      chain :during_n_iterations_run do |iterations|
+        @_iterations = Integer(iterations)
+      end
+
+      chain :during_n_seconds_run do |time_to_run|
+        @_time_to_run = Float(time_to_run)
+      end
+
+      chain :halt_on_unexpected do
+        @_halt_on_unexpected = true
+      end
+
+      chain :serialize_input do |serializer|
+        @_input_serializer = serializer
+      end
+
+      chain :serialize_output do |serializer|
+        @_output_serializer = serializer
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blood_contracts
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Sergey Dolganov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-22 00:00:00.000000000 Z
+date: 2018-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-initializer
@@ -25,19 +25,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: activesupport
+  name: nanoid
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +94,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: Ruby gem to define and validate behavior of API using contracts.
 email:
 - dolganov@evl.ms
@@ -98,10 +126,21 @@ files:
 - bin/setup
 - blood_contracts.gemspec
 - lib/blood_contracts.rb
+- lib/blood_contracts/base_contract.rb
+- lib/blood_contracts/contracts/description.rb
+- lib/blood_contracts/contracts/matcher.rb
+- lib/blood_contracts/contracts/validator.rb
+- lib/blood_contracts/debugger.rb
 - lib/blood_contracts/runner.rb
+- lib/blood_contracts/statistics.rb
 - lib/blood_contracts/storage.rb
+- lib/blood_contracts/storages/base_backend.rb
+- lib/blood_contracts/storages/file_backend.rb
+- lib/blood_contracts/storages/serializer.rb
 - lib/blood_contracts/suite.rb
 - lib/blood_contracts/version.rb
+- lib/extensions/string.rb
+- lib/rspec/meet_contract_matcher.rb
 homepage: https://github.com/sclinede/blood_contracts
 licenses:
 - MIT
@@ -114,7 +153,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -122,7 +161,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.14
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Ruby gem to define and validate behavior of API using contracts.