rspec-apib 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5289265f76974beae58b1b06e3007f80ab8675e9fc90adfb0d990f92b73497a2
-  data.tar.gz: f5c304a0910a7b1e2ae167eae8d376669b8ca4e21015abadd6803d277de432b2
+  metadata.gz: 0e706322f5f6c369d0d71d2609b80eaed15bb8280f0607900a3e24954a9c09dd
+  data.tar.gz: 36b29966f316c3d8a72ace8ef7535e9cbebb14f05c19e9967d49461f56735b4b
 SHA512:
-  metadata.gz: c144150644f21b7e6eb41278eb97ffdc98294900b8fbf049e848832e49af0f95ce68eed76e1675d438f2fa858640ca93b516d8b7e885e7b755ddb76ac6709888
-  data.tar.gz: 182decedd6be6989b09519ba8aa75f0ffeae867b1abe24c52b5e8e7fb421fb9fe54a0b26348acfe09de285ff22f9cf01c859b9ac01b4135c050e48f795f4425d
+  metadata.gz: 3e28a021e3424fc5f52fccfae50acc27e878251dff387c0c3eb22648644e3d69f147bc442cf5704b41eefe49f0bb2e1a9e731ea131ff7c9ea2577ad983c9d8b5
+  data.tar.gz: 2cdd2a0ddc010c144a84b4fec591d642eed2587649c1b02635307bfe4a9b3d3f81848010646da5ffa56e539b7a5c4af5d514772100cc3276880a2d8bdb34f1cd

data/.gitignore

@@ -1,6 +1,5 @@
 /.bundle/
 /.yardoc
-/Gemfile.lock
 /_yardoc/
 /coverage/
 /doc/

data/Dockerfile

@@ -1,4 +1,4 @@
-FROM ruby:2.2
+FROM ruby:2.6
 
 # Install dependencies
 RUN apt-get update -qq && \

data/Gemfile.lock

@@ -0,0 +1,201 @@
+PATH
+  remote: .
+  specs:
+    rspec-apib (0.4.0)
+      rails (>= 4.2)
+      rspec-rails (~> 3.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (6.0.1)
+      actionpack (= 6.0.1)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailbox (6.0.1)
+      actionpack (= 6.0.1)
+      activejob (= 6.0.1)
+      activerecord (= 6.0.1)
+      activestorage (= 6.0.1)
+      activesupport (= 6.0.1)
+      mail (>= 2.7.1)
+    actionmailer (6.0.1)
+      actionpack (= 6.0.1)
+      actionview (= 6.0.1)
+      activejob (= 6.0.1)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (6.0.1)
+      actionview (= 6.0.1)
+      activesupport (= 6.0.1)
+      rack (~> 2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actiontext (6.0.1)
+      actionpack (= 6.0.1)
+      activerecord (= 6.0.1)
+      activestorage (= 6.0.1)
+      activesupport (= 6.0.1)
+      nokogiri (>= 1.8.5)
+    actionview (6.0.1)
+      activesupport (= 6.0.1)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activejob (6.0.1)
+      activesupport (= 6.0.1)
+      globalid (>= 0.3.6)
+    activemodel (6.0.1)
+      activesupport (= 6.0.1)
+    activerecord (6.0.1)
+      activemodel (= 6.0.1)
+      activesupport (= 6.0.1)
+    activestorage (6.0.1)
+      actionpack (= 6.0.1)
+      activejob (= 6.0.1)
+      activerecord (= 6.0.1)
+      marcel (~> 0.3.1)
+    activesupport (6.0.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2)
+    builder (3.2.3)
+    coderay (1.1.2)
+    concurrent-ruby (1.1.5)
+    crass (1.0.5)
+    diff-lcs (1.3)
+    erubi (1.9.0)
+    ffi (1.11.1)
+    formatador (0.2.5)
+    globalid (0.4.2)
+      activesupport (>= 4.2.0)
+    guard (2.13.0)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, <= 4.0)
+      lumberjack (~> 1.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.9.12)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.6.5)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    i18n (1.7.0)
+      concurrent-ruby (~> 1.0)
+    listen (3.2.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    loofah (2.3.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    lumberjack (1.0.13)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (0.3.3)
+      mimemagic (~> 0.3.2)
+    method_source (0.9.2)
+    mimemagic (0.3.3)
+    mini_mime (1.0.2)
+    mini_portile2 (2.4.0)
+    minitest (5.13.0)
+    nenv (0.3.0)
+    nio4r (2.5.2)
+    nokogiri (1.10.5)
+      mini_portile2 (~> 2.4.0)
+    notiffany (0.1.3)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    rack (2.0.7)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails (6.0.1)
+      actioncable (= 6.0.1)
+      actionmailbox (= 6.0.1)
+      actionmailer (= 6.0.1)
+      actionpack (= 6.0.1)
+      actiontext (= 6.0.1)
+      actionview (= 6.0.1)
+      activejob (= 6.0.1)
+      activemodel (= 6.0.1)
+      activerecord (= 6.0.1)
+      activestorage (= 6.0.1)
+      activesupport (= 6.0.1)
+      bundler (>= 1.3.0)
+      railties (= 6.0.1)
+      sprockets-rails (>= 2.0.0)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.3.0)
+      loofah (~> 2.3)
+    railties (6.0.1)
+      actionpack (= 6.0.1)
+      activesupport (= 6.0.1)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.20.3, < 2.0)
+    rake (10.5.0)
+    rb-fsevent (0.10.3)
+    rb-inotify (0.10.0)
+      ffi (~> 1.0)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.0)
+      rspec-support (~> 3.9.0)
+    rspec-expectations (3.9.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-rails (3.9.0)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.0)
+    shellany (0.0.1)
+    sprockets (4.0.0)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.1)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    thor (0.20.3)
+    thread_safe (0.3.6)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+    websocket-driver (0.7.1)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.4)
+    zeitwerk (2.2.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.10)
+  guard (~> 2.13.0)
+  guard-rspec (~> 4.6.4)
+  pry
+  rake (~> 10.0)
+  rspec-apib!
+
+BUNDLED WITH
+   1.17.2

data/README.md

@@ -40,6 +40,14 @@ RSpec::Apib.configure do |config|
 
   # Example types to record
   config.record_types = [:request]
+
+  # Recording policy
+
+  # The default recording policy is `true`. This results in a recording of
+  # all matching specs. By changing this policy to `false`, you can selectively
+  # include certain specs by adding `apib: true` to your example options.
+  #
+  # config.default_recording_policy = false
 end
 # ...
 RSpec::Apib.start
@@ -51,18 +59,42 @@ By default, request specs get recorded and written to a `.apib` file afterwards.
 Rspec-apib is trying to make sense of the test run and generates a meaningful
 documentation out of it.
 
-* **Disable single examples:** Add `apib: false` to the examples meta data
+- **Disable single examples:** Add `apib: false` to the examples meta data
+
   ```ruby
   it 'does something', apib: false do
     # ...
   end
   ```
 
-* **Custom example description:** Add an *apib* comment above the example
-  ```ruby
+- **Custom example description:** Add an _apib_ comment above the example
+  You can add a description for the request, response or both.
+
+  Description only for the request
+
+  ````ruby
+  # Not contained in the description
+  #
+  # --- apib:request
+  # Some awesome description of the request
+  #
+  # ```json
+  # {}
+  # ```
+  # ---
+  #
   # Not contained in the description
   #
-  # --- apib
+  it 'has a custom description' do
+    # ...
+  end
+  ````
+
+  Description only for the response
+
+  ````ruby
+  # Not contained in the description
+  # -- apib:response
   # Some awesome description of the response
   #
   # ```json
@@ -75,7 +107,30 @@ documentation out of it.
   it 'has a custom description' do
     # ...
   end
-  ```
+  ````
+
+  Description for both request and response
+
+  ````ruby
+  # Not contained in the description
+  #
+  # --- apib:request
+  # Some awesome description of the request
+  #
+  # -- apib:response
+  # Some awesome description of the response
+  #
+  # ```json
+  # {}
+  # ```
+  # ---
+  #
+  # Not contained in the description
+  #
+  it 'has a custom description' do
+    # ...
+  end
+  ````
 
 ## Development
 
@@ -88,7 +143,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 To do continuous testing during development `guard` can be used. In order to
 test against multiple versions of Rails, the environment variable
 `RAILS_VERSION` can be used to choose a different dependency pattern then the
-default one specified in the *.gemspec* file.
+default one specified in the _.gemspec_ file.
 
 ```
 RAILS_VERSION='~> 4.0' bundle install; bundle exec rspec

data/lib/rspec/apib.rb

@@ -1,6 +1,7 @@
 require 'rails'
 require 'rspec/apib/version'
 require 'rspec/apib/configuration'
+require 'rspec/apib/comments_parser'
 require 'rspec/apib/recorder'
 require 'rspec/apib/writer'
 
@@ -22,11 +23,9 @@ module RSpec
       end
 
       def start
-        types = config.record_types
         RSpec.configure do |config|
           config.after :each do |example|
-            if types.include?(example.metadata[:type]) &&
-              !(example.metadata[:apib] === false)
+            if RSpec::Apib.record?(example)
               RSpec::Apib.record(example, request, response, @routes)
             end
           end
@@ -47,6 +46,15 @@ module RSpec
         writer = Writer.new(@_doc || {})
         writer.write
       end
+
+      def record?(example)
+        default_recording_policy = config.default_recording_policy
+        config.record_types.include?(example.metadata[:type]) &&
+          (
+            default_recording_policy && !(example.metadata[:apib] === false) ||
+            !default_recording_policy && (example.metadata[:apib] === true)
+          )
+      end
     end
   end
 end

data/lib/rspec/apib/comments_parser.rb

@@ -0,0 +1,60 @@
+module RSpec
+  module Apib
+    class CommentsParser
+      attr_reader :example
+
+      def initialize(example)
+        @example = example
+      end
+
+      def full_comment
+        line = example.metadata[:line_number]
+        return if line.nil? || line <= 0
+
+        lines = read_example_file
+        return if lines.count < line
+
+        i = line -2
+        result = []
+
+        while (i >= 0 && match = lines[i].match(/\A\s*#\s*(.*)/)) do
+          result.unshift(match[1])
+          i -= 1
+        end
+
+        result
+      end
+
+      def description(namespace = nil)
+        matcher = start_matcher(namespace)
+        comment = full_comment()
+        in_comment = false
+        return nil if comment.blank?
+
+        comment.select do |elem|
+          if elem == matcher
+            in_comment = true
+          elsif elem.match?(/\A---($|[^-])/)
+            in_comment = false
+          end
+
+          in_comment && elem != matcher
+        end.join("\n")
+      end
+
+      private
+
+      def read_example_file
+        file = example.metadata[:absolute_file_path]
+        return [] if file.nil? || file.empty?
+        return [] unless File.exists?(file)
+        IO.readlines(file)
+      end
+
+      def start_matcher(namespace)
+        return "--- apib" if namespace.blank?
+        "--- apib:#{namespace}"
+      end
+    end
+  end
+end

data/lib/rspec/apib/configuration.rb

@@ -2,7 +2,7 @@ module RSpec
   module Apib
     class Configuration < Struct.new(
       :dest_file, :pre_docs, :post_docs, :request_header_blacklist,
-      :request_param_blacklist, :record_types
+      :request_param_blacklist, :record_types, :default_recording_policy
     )
       def initialize
         self.pre_docs   = []
@@ -10,6 +10,7 @@ module RSpec
         self.request_header_blacklist = %w(host accept cookie)
         self.request_param_blacklist  = %i(controller action)
         self.record_types = %i(request)
+        self.default_recording_policy = true
       end
 
       def dest_file

data/lib/rspec/apib/recorder.rb

@@ -19,6 +19,10 @@ module RSpec
         document_response
       end
 
+      def comments_parser
+        @comments_parser ||= CommentsParser.new(example)
+      end
+
       private
 
       # Request headers contained in the blacklist will not be included in the
@@ -102,6 +106,7 @@ module RSpec
       def document_request
         document_request_params
         return if response.status >= action[:request][:_status]
+        action[:request][:description] = comments_parser.description("request")
         action[:request][:_status] = response.status
         action[:request][:path]    = request.path
         action[:request][:body]    = request.body.read
@@ -136,7 +141,7 @@ module RSpec
       def document_response
         data = {}
         return if response_exists?
-        data[:description]  = document_extended_description || example.description
+        data[:description]  = comments_parser.description("response") || example.description
         data[:status]       = response.status
         data[:content_type] = response.content_type.to_s
         data[:body]         = response.body
@@ -144,35 +149,6 @@ module RSpec
         action[:response] << data
       end
 
-      def document_extended_description
-        file = example.metadata[:absolute_file_path]
-        line = example.metadata[:line_number]
-        return if file.nil? || file.empty?
-        return if line.nil? || line <= 0
-        return unless File.exists?(file)
-        lines = IO.readlines(file)
-        return if lines.count < line
-        i = line -2
-        m = false
-        while (i >= 0 && lines[i].match(/\A\s*#/)) do
-          if lines[i - 1].match(/\A\s*# --- apib/)
-            m = true
-            break
-          end
-          i -= 1
-        end
-        return unless m
-        result = []
-        while (i < line && lines[i].match(/\A\s*#/)) do
-          if lines[i].match(/\A\s*# ---\s*\z/)
-            break
-          end
-          result << lines[i].sub(/^\s*#( |)/, '').rstrip
-          i += 1
-        end
-        return result.join("\n")
-      end
-
       def response_exists?
         action[:response].any? { |r| r[:status] == response.status }
       end

data/lib/rspec/apib/version.rb

@@ -1,5 +1,5 @@
 module RSpec
   module Apib
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/rspec/apib/writer.rb

@@ -52,6 +52,7 @@ module RSpec
             end
 
             apib += "+ Request\n\n"
+            apib += "#{data[:request][:description].indent(2, '  ')}\n\n" if data[:request][:description]
             apib += "    + Headers\n\n"
             data[:request][:headers].each do |header, value|
               apib += "            #{header}: #{value}\n"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-apib
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Paul Spieker
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-11-05 00:00:00.000000000 Z
+date: 2019-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -127,6 +127,7 @@ files:
 - CODE_OF_CONDUCT.md
 - Dockerfile
 - Gemfile
+- Gemfile.lock
 - Guardfile
 - LICENSE.txt
 - README.md
@@ -135,6 +136,7 @@ files:
 - bin/setup
 - docker-compose.yml
 - lib/rspec/apib.rb
+- lib/rspec/apib/comments_parser.rb
 - lib/rspec/apib/configuration.rb
 - lib/rspec/apib/recorder.rb
 - lib/rspec/apib/version.rb