webspicy 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70bfa6517173d1f121b9ebe968ac5970e41b2f6846384b152d288eb2f4913cb7
-  data.tar.gz: 0e5b728db6ecd9eb3ccb42d166317911a03092d41cf4778f1058960aa0e92bab
+  metadata.gz: 2eaf855f36546e0f538b47c50d6cb612a741807057f82172a93bff42542b326f
+  data.tar.gz: b2e892ebf4d30e04d843df175d01ac77e8e65e145b7e6a88b4eccc0c24614ea5
 SHA512:
-  metadata.gz: 51e6fbe8ad57cb2795435a3c194e142d1f5e822289be923aeebfd9c89ef9440a6fd7dea2fb58bb9e8d8bdd490b1025201dfb12b4d000d7d6604e422de1007dcf
-  data.tar.gz: 3fe5b84bd684564321712412c2bc0f918944d22dbe665ea119d0a478d181a6ac9483de2c1352e8b0f98b484e1cd361f0193afcf42c6ee6c0095811feec86c555
+  metadata.gz: e6c77544f40a49028508709e8be6e7f7b95d979212416bcde782cdb5dd361f0091433d68e38c8908800851c629053c34f2c102ae41be8dea660f5ee51a839177
+  data.tar.gz: 8fb1d33bf31723292d39a2451a79fcca4e67c5fc57f37ade00e40290fbe12e3ebbd718fc619e7c2128fdae34e7c8e44a087649fb4199d8d3505d42ae3b0e982f

data/README.md

@@ -1,11 +1,13 @@
+[![Build Status](https://travis-ci.com/enspirit/webspicy.svg?branch=master)](https://travis-ci.com/enspirit/webspicy)
 # 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 +21,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 +32,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:
@@ -60,7 +66,7 @@ to use our `:tester` docker image. Just mount your test suite as a volume
 in `/home/app` and you are good to go:
 
 ```
-docker run -v path/to/tests:/formalspec enspirit/webspicy-tester
+docker run -v path/to/tests:/formalspec enspirit/webspicy:tester
 ```
 
 If your plan is to test a backend that runs on your own machine (vs.
@@ -69,7 +75,7 @@ you will need to add some networking option, as shown below. Please
 refer to Docker documentation.
 
 ```
-docker run -v path/to/tests:/formalspec --network=host enspirit/webspicy-tester
+docker run -v path/to/tests:/formalspec --network=host enspirit/webspicy:tester
 ```
 
 ## Contributing

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/examples/website/specification/get-http.yml

@@ -1,34 +1,30 @@
 ---
-name: |-
-  Your backend is broken website
-
 url: |-
   http://yourbackendisbroken.dev
 
-services:
-- method: |-
-    GET
+method: |-
+  GET
 
-  description: |-
-    Redirects to the https version
+description: |-
+  Redirects to the https version
 
-  input_schema: |-
-    Any
+input_schema: |-
+  Any
 
-  output_schema: |-
-    Any
+output_schema: |-
+  Any
 
-  error_schema: |-
-    Any
+error_schema: |-
+  Any
 
-  examples:
+examples:
 
-    - description: |-
-        it works
-      params:
-        id: 1
-      expected:
-        content_type: text/html
-        status: 3xx
-        headers:
-          Location: https://yourbackendisbroken.dev/?id=1
+  - description: |-
+      it works
+    params:
+      id: 1
+    expected:
+      content_type: text/html
+      status: 3xx
+      headers:
+        Location: https://yourbackendisbroken.dev/?id=1

data/examples/website/specification/get-https.yml

@@ -1,34 +1,30 @@
 ---
-name: |-
-  Your backend is broken website
-
 url: |-
   https://yourbackendisbroken.dev
 
-services:
-- method: |-
-    GET
+method: |-
+  GET
 
-  description: |-
-    Returns the web page
+description: |-
+  Returns the web page
 
-  input_schema: |-
-    Any
+input_schema: |-
+  Any
 
-  output_schema: |-
-    Any
+output_schema: |-
+  Any
 
-  error_schema: |-
-    Any
+error_schema: |-
+  Any
 
-  examples:
+examples:
 
-    - description: |-
-        it works
-      params:
-        id: 1
-      expected:
-        content_type: text/html
-        status: 200
-      assert:
-        - notEmpty
+  - description: |-
+      it works
+    params:
+      id: 1
+    expected:
+      content_type: text/html
+      status: 200
+    assert:
+      - notEmpty

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
@@ -89,9 +90,9 @@ module Webspicy
   module_function :test_case
 
   def handle_finitio_error(ex, scope)
-    # msg = "#{ex.message}:\n    #{ex.root_cause.message}"
-    # msg = Support::Colorize.colorize_error(msg, scope.config)
-    # fatal(msg)
+    msg = "#{ex.message}:\n    #{ex.root_cause.message}"
+    msg = Support::Colorize.colorize_error(msg, scope.config)
+    fatal(msg)
     raise
   end
   module_function :handle_finitio_error

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

@@ -18,18 +18,14 @@ FileUpload =
     }
 
 Specification = .Webspicy::Specification
-  <info> {
-    name: String
-    url: String
-    services: [Service]
-  }
   <singleservice> {
     name            :? String
-    url             : String
+    url             :  String
     method          :  Method
     description     :  String
     preconditions   :? [String]|String
     postconditions  :? [String]|String
+    errconditions   :? [String]|String
     input_schema    :  Schema
     output_schema   :  Schema
     error_schema    :  Schema
@@ -38,6 +34,11 @@ Specification = .Webspicy::Specification
     examples        :? [TestCase]
     counterexamples :? [TestCase]
   }
+  <info> {
+    name: String
+    url: String
+    services: [Service]
+  }
 
 Service =
     .Webspicy::Specification::Service <info> {
@@ -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/mocker/config.ru

@@ -0,0 +1,5 @@
+require "webspicy"
+require "webspicy/mocker"
+require 'rack'
+config = Webspicy::Configuration.dress(Path("/formalspec/"))
+run Webspicy::Mocker.new(config)

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