rspec-rails-api 0.3.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9090792ade8b44f18851585ce025a354fab47ff9cb7903ae61982507c34302bf
-  data.tar.gz: 26551e11739758d40987f7026cc556e475952f79419cb24abf5df4207ba40364
+  metadata.gz: 232e1ea8b43dd1e3b5258f0029d28a54d886156634e87d4a6854a3543752fb0f
+  data.tar.gz: 71828ab75d08ff900cbe9f018af219bc79b98231118712d127e35c274690d7ad
 SHA512:
-  metadata.gz: 4bc1803ab38dc596f0fbf3993da2f860e22849f1d2e9c68be91e860b36684ee3bf0129a98972afca1d7f65869531c6cc8aa0f36d66aa91d97f92ebbad69cfff1
-  data.tar.gz: b96392b596dd83d1de832b62a72d54afbed0f0a556c36bbf7627ed2fbec7c36d59c4d1d935186e3de62f72524243bf75f92a6429bc492cf559ebb22751e74dcc
+  metadata.gz: dbb37718158f52e0a2056bbe9b8ccde44782cafe915cc146f05333532484b10ae8260e7abbd3f571e657c778b8d8ac37c731adfa452d3e94af253dcf6849aede
+  data.tar.gz: 731f623490f7e15b3f0acb8851955835083249b60e62f722ab9870c6658d3e690ed0b6aca8ac4edcdc3f6b1c892517511937d190459b8020fcb2b3c2ef99047a

data/.gitignore

@@ -10,9 +10,4 @@
 # rspec failure tracking
 .rspec_status
 
-# Ignore lockfile for Gemfile
-Gemfile.lock
-# Keep the dummy one
-!dummy/Gemfile.lock
-
 .byebug_history

data/.gitlab-ci.yml

@@ -1,5 +1,5 @@
 ---
-image: ruby:2.5
+image: ruby:2.7
 
 stages:
   - prepare

data/.rubocop.yml

@@ -1,9 +1,11 @@
 ---
 require:
   - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
 
 AllCops:
-  TargetRubyVersion: 2.5
+  TargetRubyVersion: 2.7
   Exclude:
     - dummy/**/*
     - vendor/bundle/**/*
@@ -33,3 +35,5 @@ Style/TrailingCommaInArrayLiteral:
 Style/TrailingCommaInHashLiteral:
   EnforcedStyleForMultiline: comma
 
+RSpec/NestedGroups:
+  Max: 4

data/.ruby-version

@@ -0,0 +1 @@
+2.7.0

data/CHANGELOG.md

@@ -2,6 +2,57 @@
 All notable changes to this project will be documented in this file.
 
 ## Not released
+
+## 0.5.0 - 2023-01-02
+
+- Improved error messages
+- Improved usage of primitive types: use `:string` instead of `:type_string`, and  more generally, remove the `type_`
+  prefix
+- Fixed an error when an object is defined with an attribute named `type`.
+
+## 0.4.0 - 2021-12-19
+
+- All parameters attributes are considered required unless specified
+- Fix object `attributes` key in spec and documentation.
+  When defining object attributes, documentation and tests used `properties` key
+  while the code was waiting for an `attributes` key. The later makes more sense
+  so the spec and documentation were fixed.
+- Check for arrays of primitives is now a thing:
+  ```rb
+  # In entities, when attribute is an array of primitives
+  entity :user,
+         aliases: { type: :array, description: 'Pseudonyms', of: :type_string }
+
+  # In examples, when response is an array of primitives
+  for_code 200, expect_many: :type_string do |url|
+    #...
+  end
+  ```
+- RSpec metadata is now stored in `rra` instead of `rrad` (the gem's first name
+  was RSpec Rails API Doc at the time). Update RSpec configuration accordingly.
+- OpenApi:
+  - Responses now includes the schema
+  - `on_xxx` methods second parameter is now used as summary instead of description.
+    Description can be defined on the third parameter.
+- DSL changes:
+  - `visit` is renamed to `test_response_of`
+  - Support for `doc_only` is removed 
+  - Response expectations _should_ now be declared with `for_code`, and should be
+    removed from example bodies:
+    ```rb
+    # Before:
+    for_code 200 do |url|
+      visit url
+      expect(response).to have_many defined: :post
+    end
+    
+    # Now:
+    for_code 200, expect_many: :post do |url|
+      test_response_of url
+    end
+    ```
+
+
 ## 0.3.4 - 2021-10-20
 - Add the "required" attribute in parameters
 

data/Gemfile.lock

@@ -0,0 +1,98 @@
+PATH
+  remote: .
+  specs:
+    rspec-rails-api (0.5.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (6.1.7)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    ast (2.4.2)
+    byebug (11.1.3)
+    concurrent-ruby (1.1.10)
+    diff-lcs (1.5.0)
+    docile (1.4.0)
+    i18n (1.12.0)
+      concurrent-ruby (~> 1.0)
+    json (2.6.3)
+    minitest (5.16.3)
+    parallel (1.22.1)
+    parser (3.1.3.0)
+      ast (~> 2.4.1)
+    rack (3.0.3)
+    rainbow (3.1.1)
+    rake (10.5.0)
+    regexp_parser (2.6.1)
+    rexml (3.2.5)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.0)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+    rubocop (1.41.1)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.1.2.1)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.23.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.24.1)
+      parser (>= 3.1.1.0)
+    rubocop-performance (1.15.2)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    rubocop-rspec (2.16.0)
+      rubocop (~> 1.33)
+    ruby-progressbar (1.11.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+    tzinfo (2.0.5)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.3.0)
+    webrick (1.7.0)
+    yard (0.9.28)
+      webrick (~> 1.7.0)
+    zeitwerk (2.6.6)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  activesupport (~> 6.0)
+  bundler
+  byebug
+  rack
+  rake (~> 10.0)
+  rspec (~> 3.0)
+  rspec-rails-api!
+  rubocop
+  rubocop-performance
+  rubocop-rake
+  rubocop-rspec
+  simplecov
+  yard
+
+BUNDLED WITH
+   2.4.1

data/README.md

@@ -48,7 +48,7 @@ renderer.api_contact = { name: 'Admin', email: 'admin@example.com', url: 'http:/
 renderer.api_license = { name: 'Apache', url: 'https://opensource.org/licenses/Apache-2.0' }
 
 RSpec.configuration.after(:context, type: :acceptance) do |context|
-  renderer.merge_context context.class.metadata[:rrad].to_h
+  renderer.merge_context context.class.metadata[:rra].to_h
 end
 
 RSpec.configuration.after(:suite) do
@@ -125,7 +125,7 @@ end
 #...
   for_code 200, 'Success' do |url|
     sing_in #...
-    visit url
+    test_response_of url
 
     #...
   end
@@ -139,14 +139,6 @@ by Arne Hartherz (MIT license).
 
 Write some spec files and run RSpec as you would usually do.
 
-If you want to generate the documentation without testing the endpoints
-(and thus, without examples in generated files), use the `DOC_ONLY`
-environment variable:
-
-```sh
-DOC_ONLY=true bundle exec rails spec
-```
-
 ## Writing specs
 
 There is a [commented example](dummy/spec/acceptance/posts_spec.rb) available in
@@ -171,9 +163,8 @@ RSpec.describe 'Users', type: :acceptance do
          url:        { type: :string, description: 'URL to this category' }
 
   on_get '/api/users/', 'Users list' do
-    for_code 200, 'Success response' do |url|
-      visit url
-      expect(response).to have_many defined :user
+    for_code 200, 'Success response', expect_many: :user do |url|
+      test_response_of url
     end
   end
 
@@ -181,16 +172,15 @@ RSpec.describe 'Users', type: :acceptance do
     path_param id: { type: :integer, description: 'User Id' }
 
     request_params user: {
-      type: :object, required: true, properties: {
+      type: :object, attributes: {
         name:  { type: :string, required: false, description: 'New name' },
         email: { type: :string, required: false, description: 'New email' },
         role:  { type: :string, required: false, description: 'New role' },
       }
     }
 
-    for_code 200, 'Success response' do |url|
-      visit url
-      expect(response).to have_one defined :user
+    for_code 200, 'Success response', expect_one: :user do |url|
+      test_response_of url
     end
   end
 end
@@ -273,6 +263,16 @@ inline.
 Both `:of` and `attributes` may be a hash of fields or a symbol. If they
 are omitted, they will be documented, but responses won't be validated.
 
+Arrays of primitives are supported; refer to the [documentation](https://swagger.io/specification/#data-types) for the 
+list. Usage:
+
+```rb
+entity :user,
+       favorite_numbers: { type: :array, of: :int32 }
+```
+
+Check `lib/rspec_rails_api.rb` for the full list.
+
 ##### `parameters(type, fields)`
 Describe path or request parameters. The type is only a reference,
 use whatever makes sense. These parameters will be present in
@@ -282,16 +282,16 @@ documentation, only if they are referenced by a `request_params` or
 Fields have the structure of the hash you would give to `request_params`
 or `path_params` (see each method later in this documentation).
 
-##### `on_<xxx>(url, description, &block)`
+##### `on_<xxx>(url, summary = nil, description = nil, &block)`
 
 Defines an URL.
 
 - `url` should be a relative URL to an existing endpoint (i.e.:
   `/api/users`)
-- `description` should be some valid
-  [CommonMark](https://commonmark.org/)
+- `summary` is a one line description of the endpoint
+- `description` should be some valid [CommonMark](https://commonmark.org/)
 
-For now, only these methods are available:
+These methods are available:
 
 - `on_get`
 - `on_post`
@@ -341,7 +341,7 @@ nested elements can be described:
 ```ruby
 on_post '/api/items' do
   request_params attributes: {
-                   item: { type: :object, required: true, properties: {
+                   item: { type: :object, attributes: {
                      name: { type: integer, description: 'The name of the new item', required: true },
                      notes: { type: string, description: 'Additional notes' }
                      } }
@@ -353,21 +353,21 @@ end
 An attribute should have the following form:
 
 ```
-<attr_name>: {type: <type>, desc: <description>, required: <required>, properties: <another_hash>, of: <another_hash> }
+<attr_name>: {type: <type>, desc: <description>, required: <required>, attributes: <another_hash>, of: <another_hash> }
 ```
 
 - `attr_name` is the attribute name (sic)
 - `type` is the field type (check _entity definition_ for a list).
   `type` can be `:object` if the attribute contains other attributes.
 - `required` is optional an defaults to `false`.
-- `properties` is a hash of params and is only used if `type: :object`
+- `attributes` is a hash of params and is only used if `type: :object`
 - `of` is a hash of params and is only used if `type: :array`
 
 Alternative with defined parameters:
 
 ```ruby
 parameters :item_form_params,
-           item: { type: :object, required: true, properties: {
+           item: { type: :object, attributes: {
               name: { type: integer, description: 'The name of the new item', required: true },
               notes: { type: string, description: 'Additional notes' }
              }
@@ -380,12 +380,12 @@ on_post '/api/items' do
 end
 ```
 
-##### `for_code(http_status, description = nil, doc_only: false, test_only: false &block)`
+##### `for_code(http_status, description = nil, test_only: false &block)`
 
 Describes the desired output for a precedently defined URL.
 
-Block takes one required argument, that should be passed to `visit`.
-This argument will contain the block context and allow `visit` to access
+Block takes one required argument, that should be passed to `test_response_of`.
+This argument will contain the block context and allow `test_response_of` to access
 the metadatas.
 
 You can have only one documented code per action/url, unless you use
@@ -396,11 +396,9 @@ You can have only one documented code per action/url, unless you use
 - `description` should be some valid
   [CommonMark](https://commonmark.org/). If not defined, a human readable
   translation of the `http_status` will be used.
-- `doc_only` can be set to true to temporarily disable block execution
-  and only create the documentation (without examples).
 - `test_only` will omit the test from the documentation. Useful when you
   need to test things _around_ the call (response content, db,...)
-- `block` where additional tests can be performed. If `visit()` is
+- `block` where additional tests can be performed. If `test_response_of` is
   called within the block, its output will be used in documentation
   examples, and the response type and code will actually be tested.
 
@@ -409,17 +407,17 @@ examples. This can be useful to document endpoints that are impossible
 to test.
 
 Once again, you have to pass an argument to the block if you use
-`visit`.
+`test_response_of`.
 
 ```ruby
 # ...
   for_code 200, 'A successful response' do |url|
-    visit url
+    test_response_of url
     # ...
   end
   
   for_code 200, 'Side test', test_only: true do |url|
-    visit url
+    test_response_of url
     # ...
   end
 # ...
@@ -429,7 +427,7 @@ Once again, you have to pass an argument to the block if you use
 
 Example methods are available in `for_code` blocks
 
-##### `visit(example, path_params: {}, payload: {}, headers: {})`
+##### `test_response_of(example, path_params: {}, payload: {}, headers: {})`
 
 Visits the described URL and:
 
@@ -446,12 +444,17 @@ Visits the described URL and:
 
 ```ruby
 for_code 200, 'Success' do |url|
-  visit url
+  test_response_of url
 end
 ```
 
 #### Matchers
 
+The matchers _should not_ be used in acceptance specs unless the default DSL is
+not adapted for a particular use case (and I can't imagine one now).
+
+For the sake of comprehension, the two custom matchers still described.
+
 ##### `have_one(type)`
 
 Expects the compared content to be a hash with the same keys as a

data/Rakefile

@@ -2,7 +2,10 @@
 
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'yard'
 
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
+
+YARD::Rake::YardocTask.new

data/lib/rspec/rails/api/dsl/example.rb

@@ -6,7 +6,16 @@ module RSpec
       module DSL
         # These methods will be available in examples (i.e.: 'for_code')
         module Example
-          def visit(example, path_params: {}, payload: {}, headers: {}) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          ##
+          # Visits the current example and tests the response
+          #
+          # @param example     [Hash] Current example
+          # @param path_params [Hash] Path parameters definition
+          # @param payload     [Hash] Request body
+          # @param headers     [Hash] Custom headers
+          #
+          # @return [void]
+          def test_response_of(example, path_params: {}, payload: {}, headers: {}) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
             raise 'Missing context. Call visit with for_code context.' unless example
 
             status_code = prepare_status_code example.class.description
@@ -23,37 +32,70 @@ module RSpec
 
             return if example.class.description.match?(/-> test (\d+)(.*)/)
 
-            set_request_example example.class.metadata[:rrad], request_params, status_code, response.body
+            set_request_example example.class.metadata[:rra], request_params, status_code, response.body
           end
 
+          private
+
+          ##
+          # Searches for a defined entity in metadata
+          #
+          # @param entity [Symbol] Entity reference
+          #
+          # @return [RSpec::Rails::Api::EntityConfig, Hash] Defined entity
           def defined(entity)
-            current_resource = self.class.metadata[:rrad].current_resource
-            raise '@current_resource is unset' unless current_resource
+            return { type: entity } if PRIMITIVES.include? entity
 
-            entities = self.class.metadata[:rrad].resources[current_resource][:entities]
+            current_resource = rra_metadata.current_resource
+            raise '@current_resource is unset' unless current_resource
 
-            out = entities[entity]
-            raise "Unkown entity '#{entity}' in resource '#{current_resource}'" unless out
+            entities = rra_metadata.resources[current_resource][:entities]
+            raise "Unknown entity '#{entity}' in resource '#{current_resource}'" unless entities.key? entity.to_sym
 
-            out.expand_with(entities)
+            entities[entity.to_sym].expand_with(entities)
           end
 
-          private
-
-          def check_response(response, expected_code)
+          ##
+          # Performs various tests on the response
+          #
+          # @param response      [ActionDispatch::TestResponse] The response
+          # @param expected_code [Number]                       Code to test for
+          def check_response(response, expected_code) # rubocop:disable Metrics/AbcSize
             expect(response.status).to eq expected_code
             expect(response.headers['Content-Type']).to eq 'application/json; charset=utf-8' if expected_code != 204
+            expectations = rra_current_example[:expectations]
+            expect(response).to have_many defined(expectations[:many]) if expectations[:many]
+            expect(response).to have_one defined(expectations[:one]) if expectations[:one]
+            expect(response.body).to eq '' if expectations[:none]
           end
 
-          def set_request_example(rrad_metadata, request_params, status_code = nil, response = nil)
-            rrad_metadata.add_request_example(url:         request_params[:example_url],
-                                              action:      request_params[:action],
-                                              status_code: status_code,
-                                              response:    response,
-                                              path_params: request_params[:path_params],
-                                              params:      request_params[:params])
+          ##
+          # Adds a request example information to metadata
+          #
+          # @param rra_metadata  [RSpec::Rails::Api::Metadata]
+          # @param request_params [Hash]
+          # @param status_code    [Integer, nil]
+          # @param response       [String, nil]
+          #
+          # @return [void]
+          def set_request_example(rra_metadata, request_params, status_code = nil, response = nil)
+            rra_metadata.add_request_example(url:         request_params[:example_url],
+                                             action:      request_params[:action],
+                                             status_code: status_code,
+                                             response:    response,
+                                             path_params: request_params[:path_params],
+                                             params:      request_params[:params])
           end
 
+          ##
+          # Prepares the options for a request
+          #
+          # @param description     [String] RSpec example description
+          # @param request_params  [Hash]   Request parameters
+          # @param payload         [Hash]   Request body
+          # @param request_headers [Hash]   Custom headers
+          #
+          # @return [Hash] Options for the request
           def prepare_request_params(description, request_params = {}, payload = {}, request_headers = {})
             example_params = description.split
 
@@ -66,7 +108,13 @@ module RSpec
             }
           end
 
+          ##
           # Replace path params by values
+          #
+          # @param url            [String] Url definition
+          # @param request_params [Hash]   Request parameters
+          #
+          # @return [String] Actual path to visit
           def prepare_request_url(url, request_params)
             url.gsub(/(?::(\w*))/) do |e|
               symbol = e.sub(':', '').to_sym
@@ -80,6 +128,12 @@ module RSpec
             end
           end
 
+          ##
+          # Prepares request headers
+          #
+          # @param headers [Hash] Custom headers
+          #
+          # @return [Hash] Headers to use in request
           def prepare_request_headers(headers = {})
             {
               'Accept'       => 'application/json',
@@ -87,6 +141,12 @@ module RSpec
             }.merge headers
           end
 
+          ##
+          # Extracts status code from RSpec example description
+          #
+          # @param description [String] RSpec example description
+          #
+          # @return [Integer] Status code
           def prepare_status_code(description)
             code_match = /->(?: test)? (\d+) - .*/.match description
 
@@ -94,6 +154,22 @@ module RSpec
 
             code_match[1].to_i
           end
+
+          ##
+          # Returns the current example configuration from metadata
+          #
+          # @return [Hash] Current example configuration
+          def rra_current_example
+            self.class.metadata[:rra_current_example]
+          end
+
+          ##
+          # Returns the whole Rspec-rails-API metadata object
+          #
+          # @return [RSpec::Rails::Api::Metadata] Rspec-rails-API metadata object
+          def rra_metadata
+            self.class.metadata[:rra]
+          end
         end
       end
     end