webspicy 0.16.3 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cbfb644d2ae34f2e2e87aa2d69b50b762299770b9c0109fbc5281fdd3b80d22
-  data.tar.gz: 6bf17b7423bb6ff33b53d8f12dc761094e613961487c146c66a87ce84b792bc7
+  metadata.gz: 63c15addd49634a62ba637d18cfee736f405dc0e144ec688e2fda6861764a09c
+  data.tar.gz: 903d3a0ca2f20a5dbac1fafc4a1a89981736d527cb69668a06b41acb5ef04696
 SHA512:
-  metadata.gz: 403ddeb22ffccd059d8450a6290f7f190d97bc45ef12a04a43a97059d733085ce4fe2865f31a5452d43c18e4244a53129ac280cd37db09b8a6ce50e76506f8f6
-  data.tar.gz: '095210fda4e1b4e903c1803a2cd75420a905894b06d4403e8f1019df0c43eeec10eb3952b8d06397bdb0d8a753361c01f1577f85f09ca34258386020276dcdaa'
+  metadata.gz: d54f59f003313e38dd37104e56038b6ede06c7339718498e6dda9730de97acdd0fae5499d45463ef790f78332eb0d337a3f068e3dd08bfec901edb8125a710c2
+  data.tar.gz: c43077a9023045856e726c0d2dbe39abc83abbd198df4a765758e6578664bcc6ec44ec7df75e164b436ae6a89cb6fe0ee89b4fc995afd3fe068bef2e5e484144

data/README.md

@@ -1,11 +1,12 @@
 # Webspicy
 
 A specification and test framework for web services seen as black-box software
-operations. Webspicy yields a better test coverage for a smaller testing effort,
-because software quality matters.
+operations. Webspicy yields a better test coverage for a smaller testing effort.
 
 See webspicy in action and make the tutorial on https://yourbackendisbroken.dev
 
+Have a look at `doc/*.md` for vocabulary and vision as well as `ROADMAP.md`.
+
 ## Features
 
 * Declarative specification of HTTP web services + their tests
@@ -19,7 +20,7 @@ See webspicy in action and make the tutorial on https://yourbackendisbroken.dev
   your API design better.
 
 * Formal and human-friendly data schema with strong data matching semantics,
-  thanks to finitio.io
+  thanks to [http://finitio.io](http://finitio.io)
 
 * Test instrumentation and generation, based on PRE & POST contracts.
 
@@ -30,6 +31,10 @@ See webspicy in action and make the tutorial on https://yourbackendisbroken.dev
 * Extra goodies: when a specification is written, it can also be used for
   mocking the API, generating an openapi file, etc.
 
+## Is this used on real-world cases?
+
+Yes, `webspicy` is currently used on a dozen production components. Our biggest specification has 324 specification files for thousands of tests, 35% of them being generated.
+
 ## Getting started with the commandline
 
 To install webspicy on your developer computer, install ruby then:

data/examples/restful/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../..
   specs:
-    webspicy (0.16.3)
+    webspicy (0.17.0)
       colorize (~> 0.8.1)
       finitio (~> 0.9.0)
       http (>= 2)
@@ -11,7 +11,7 @@ PATH
       path (~> 2.0)
       rack-robustness (~> 1.1, >= 1.1.0)
       rack-test (~> 0.6.3)
-      rspec (~> 3.7)
+      rspec (~> 3.10)
       rspec_junit_formatter (~> 0.4.1)
 
 GEM
@@ -27,11 +27,11 @@ GEM
     diff-lcs (1.4.4)
     domain_name (0.5.20190701)
       unf (>= 0.0.5, < 1.0.0)
-    ffi (1.13.1)
+    ffi (1.14.2)
     ffi-compiler (1.0.1)
       ffi (>= 1.0.0)
       rake
-    finitio (0.9.0)
+    finitio (0.9.1)
       citrus (>= 2.4, < 4.0)
     hansi (0.2.0)
     http (4.4.1)
@@ -42,9 +42,9 @@ GEM
     http-cookie (1.0.3)
       domain_name (~> 0.5)
     http-form_data (2.3.0)
-    http-parser (1.2.2)
-      ffi-compiler
-    i18n (1.8.5)
+    http-parser (1.2.3)
+      ffi-compiler (>= 1.0, < 2.0)
+    i18n (1.8.7)
       concurrent-ruby (~> 1.0)
     mustermann (1.1.1)
       ruby2_keywords (~> 0.0.1)
@@ -55,7 +55,7 @@ GEM
       commonmarker (~> 0.17)
       psych (~> 3.1)
     path (2.0.1)
-    psych (3.2.1)
+    psych (3.3.0)
     public_suffix (4.0.6)
     rack (2.2.3)
     rack-protection (2.1.0)
@@ -68,15 +68,15 @@ GEM
       rspec-core (~> 3.10.0)
       rspec-expectations (~> 3.10.0)
       rspec-mocks (~> 3.10.0)
-    rspec-core (3.10.0)
+    rspec-core (3.10.1)
       rspec-support (~> 3.10.0)
-    rspec-expectations (3.10.0)
+    rspec-expectations (3.10.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
-    rspec-mocks (3.10.0)
+    rspec-mocks (3.10.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
-    rspec-support (3.10.0)
+    rspec-support (3.10.1)
     rspec_junit_formatter (0.4.1)
       rspec-core (>= 2, < 4, != 2.12.0)
     ruby-enum (0.8.0)
@@ -95,6 +95,7 @@ GEM
 PLATFORMS
   ruby
   x86_64-darwin-15
+  x86_64-darwin-18
 
 DEPENDENCIES
   rake (~> 12)
@@ -102,4 +103,4 @@ DEPENDENCIES
   webspicy!
 
 BUNDLED WITH
-   2.2.1
+   2.2.2

data/examples/restful/webspicy/config.rb

@@ -11,6 +11,7 @@ def webspicy_config(&bl)
     c.precondition Webspicy::Specification::Precondition::RobustToInvalidInput.new
 
     c.postcondition TodoRemoved
+    c.errcondition  TodoNotRemoved
 
     c.instrument do |tc, client|
       role = tc.metadata[:role]

data/examples/restful/webspicy/{todo/deleteTodo.yml → formaldef/todo/_one/delete.yml}

@@ -18,6 +18,9 @@ services:
   postconditions:
     - The todo has been removed
 
+  errconditions:
+    - If it existed, the todo has not been removed
+
   input_schema: |-
     {
       id: Integer

data/examples/restful/webspicy/support/todo_not_removed.rb

@@ -0,0 +1,21 @@
+class TodoNotRemoved
+  include Webspicy::Specification::Postcondition
+
+  def self.match(service, descr)
+    return TodoNotRemoved.new if descr =~ /If it existed, the todo has not been removed/
+  end
+
+  def check(invocation)
+    client, scope, test_case = invocation.client,
+                               invocation.client.scope,
+                               invocation.test_case
+    return if invocation.response.status == 404
+    id = test_case.params['id']
+    url = scope.to_real_url("/todo/#{id}", test_case){|url| url }
+    response = client.api.get(url, {}, {
+      "Accept" => "application/json"
+    })
+    return nil if response.status == 200
+    "Todo `#{id}` was not supposed to be deleted, it was not found"
+  end
+end

data/examples/restful/webspicy/support/todo_removed.rb

@@ -6,9 +6,11 @@ class TodoRemoved
   end
 
   def check(invocation)
-    client = invocation.client
-    id = invocation.test_case.params['id']
-    url = "/todo/#{id}"
+    client, scope, test_case = invocation.client,
+                               invocation.client.scope,
+                               invocation.test_case
+    id = test_case.params['id']
+    url = scope.to_real_url("/todo/#{id}", test_case){|url| url }
     response = client.api.get(url, {}, {
       "Accept" => "application/json"
     })

data/lib/webspicy.rb

@@ -62,6 +62,7 @@ module Webspicy
     raw = YAML.load(raw) if raw.is_a?(String)
     with_scope(scope) do
       r = FORMALDOC["Specification"].dress(raw)
+      r.config = scope.config
       r.located_at!(file) if file
       r
     end

data/lib/webspicy/checker.rb

@@ -1,25 +1,10 @@
 module Webspicy
   class Checker
 
-    def initialize(config)
-      @config = Configuration.dress(config)
+    def self.new(*args, &bl)
+      require_relative 'rspec/checker'
+      RSpecChecker.new(*args, &bl)
     end
-    attr_reader :config
 
-    def call
-      config.each_scope do |scope|
-        scope.each_specification_file do |file, folder|
-          RSpec.describe file.relative_to(folder).to_s do
-
-            it 'meets the formal doc data schema' do
-              Webspicy.specification(file.load, file, scope)
-            end
-
-          end
-        end
-      end
-      RSpec::Core::Runner.run config.rspec_options
-    end
-
-  end
-end
+  end # class Checker
+end # module Webspicy

data/lib/webspicy/configuration.rb

@@ -9,6 +9,7 @@ module Webspicy
       @children = []
       @preconditions = []
       @postconditions = []
+      @errconditions = []
       @listeners = Hash.new{|h,k| h[k] = [] }
       @rspec_options = default_rspec_options
       @run_examples = default_run_examples
@@ -126,6 +127,13 @@ module Webspicy
     attr_accessor :postconditions
     protected :postconditions=
 
+    # Registers an errcondition matcher
+    def errcondition(clazz)
+      errconditions << clazz
+    end
+    attr_accessor :errconditions
+    protected :errconditions=
+
     # Returns whether this configuration has children configurations or not
     def has_children?
       !children.empty?
@@ -422,6 +430,7 @@ module Webspicy
         d.children = []
         d.preconditions = self.preconditions.dup
         d.postconditions = self.postconditions.dup
+        d.errconditions = self.errconditions.dup
         d.rspec_options = self.rspec_options.dup
         d.listeners = LISTENER_KINDS.inject({}){|ls,kind|
           ls.merge(kind => self.listeners(kind).dup)

data/lib/webspicy/configuration/scope.rb

@@ -7,14 +7,6 @@ module Webspicy
       end
       attr_reader :config
 
-      def preconditions
-        config.preconditions
-      end
-
-      def postconditions
-        config.postconditions
-      end
-
       ###
       ### Eachers -- Allow navigating the web service definitions
       ###

data/lib/webspicy/formaldoc.fio

@@ -25,6 +25,7 @@ Specification = .Webspicy::Specification
     description     :  String
     preconditions   :? [String]|String
     postconditions  :? [String]|String
+    errconditions   :? [String]|String
     input_schema    :  Schema
     output_schema   :  Schema
     error_schema    :  Schema
@@ -45,6 +46,7 @@ Service =
         description     :  String
         preconditions   :? [String]|String
         postconditions  :? [String]|String
+        errconditions   :? [String]|String
         input_schema    :  Schema
         output_schema   :  Schema
         error_schema    :  Schema

data/lib/webspicy/rspec/checker.rb

@@ -0,0 +1,2 @@
+require_relative 'support/rspec_runnable'
+require_relative 'checker/rspec_checker'

data/lib/webspicy/rspec/checker/rspec_checker.rb

@@ -0,0 +1,24 @@
+module Webspicy
+  class Checker
+    class RSpecChecker
+      include Webspicy::Support::RSpecRunnable
+
+    protected
+
+      def load_rspec_examples
+        config.each_scope do |scope|
+          scope.each_specification_file do |file, folder|
+            RSpec.describe file.relative_to(folder).to_s do
+
+              it 'meets the formal doc data schema' do
+                Webspicy.specification(file.load, file, scope)
+              end
+
+            end
+          end
+        end
+      end
+
+    end # class RSpecChecker
+  end # class Checker
+end # module Webspicy

data/lib/webspicy/rspec/support/rspec_runnable.rb

@@ -0,0 +1,27 @@
+module Webspicy
+  module Support
+    module RSpecRunnable
+
+      def initialize(config)
+        @config = Configuration.dress(config)
+      end
+      attr_reader :config
+
+      def reset_rspec!
+        RSpec.reset
+        RSpec.configure do |c|
+          c.filter_gems_from_backtrace "rake"
+        end
+        load_rspec_examples
+      end
+
+      def call(err=$stderr, out=$stdout)
+        reset_rspec!
+        options = RSpec::Core::ConfigurationOptions.new(config.rspec_options)
+        conf = RSpec::Core::Configuration.new
+        RSpec::Core::Runner.new(options, conf).run(err, out)
+      end
+
+    end # module RSpecRunnable
+  end # module Support
+end # module Webspicy

data/lib/webspicy/rspec/tester.rb

@@ -0,0 +1,4 @@
+require_relative 'support/rspec_runnable'
+require_relative 'tester/rspec_matchers'
+require_relative 'tester/rspec_asserter'
+require_relative 'tester/rspec_tester'

data/lib/webspicy/{tester → rspec/tester}/rspec_asserter.rb

@@ -8,6 +8,10 @@ module Webspicy
       end
       attr_reader :rspec,  :invocation
 
+      def self.call(rspec, invocation)
+        new(rspec, invocation).send(:assert!)
+      end
+
       def response
         invocation.response
       end
@@ -20,15 +24,20 @@ module Webspicy
         test_case.service
       end
 
+    protected
+
       def assert!
-        assert_status_met
-        assert_content_type_met
-        assert_expected_headers
+        rspec.aggregate_failures do
+          assert_status_met
+          assert_content_type_met
+          assert_expected_headers
+        end
         assert_output_schema_met
-        assert_assertions_met
-        assert_postconditions_met
-
-        assert_no_other_errors
+        rspec.aggregate_failures do
+          assert_assertions_met
+          assert_postconditions_met
+          assert_errconditions_met
+        end
       end
 
       def assert_status_met
@@ -98,9 +107,13 @@ module Webspicy
         end
       end
 
-      def assert_no_other_errors
-        errors = invocation.errors
-        rspec.expect(errors).to rspec.be_an_empty_errors_array
+      def assert_errconditions_met
+        return unless service.has_errconditions?
+        return unless test_case.counterexample?
+        service.errconditions.each do |post|
+          msg = post.check(invocation)
+          rspec.expect(msg).to rspec.meet_errcondition(post)
+        end
       end
 
     end # class RSpecAsserter

data/lib/webspicy/{tester → rspec/tester}/rspec_matchers.rb

@@ -94,6 +94,16 @@ RSpec::Matchers.define :meet_postcondition do |post|
   end
 end
 
+RSpec::Matchers.define :meet_errcondition do |post|
+  match do |actual|
+    actual.nil?
+  end
+  failure_message_for_should do |actual|
+    "expected errcondition `#{post.class.name}` to be met, got following error:\n" + \
+    "    #{actual}"
+  end
+end
+
 RSpec::Matchers.define :be_an_empty_errors_array do
   match do |actual|
     actual.empty?