pack_api 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f48730065ece9a8f8e18749b49d15d4f312c997148e86447f09ba8779bd5958d
-  data.tar.gz: 5670802d6da87396caf59e961240dd2bb2d4dcc5b7bf5dafcc4ba83a196add72
+  metadata.gz: 0f59a0e96b77d27b0c274c7bfbd3d02d58bf10139079f7e8f65f0f141700657a
+  data.tar.gz: 48f2caa082efe138a25ce949383e04959b07f2cc6e383fc277059b19c7edb489
 SHA512:
-  metadata.gz: 2aaf0603ed13870e685757e6f17d8e3e98db880bb2bf0c31785940b0333eb1720cd84c5e15eb54854e6dce2dceb3d5d8780b91ef0c361fa14a498701928ee72f
-  data.tar.gz: af308e82aee39b175b46e19c2ecaafab1a7eb12bb87cd072d2fd33bce808863c003f2b9796cf82329ebd3301cfb20ffd7b4f83145be72f6546a4d707d678037e
+  metadata.gz: 4b81ed5a8dd8536b534c18774efbdd21eb3d8799a9b00aa96afa015d5fed12ff626e48c5035983a7b28760f6a0a40c06b205d55bc2e93f82c67b29381360ec27
+  data.tar.gz: 7a7bda196011de7a10e1a8c8b98961c530dee455bc4d908f1d0c9b5c726c7df47bdeef29906a9f8faa0a65a169dfdfbadb8e1eb8c0cbb15dff35b3086c3abd42

data/README.md

@@ -228,6 +228,55 @@ def query_blog_posts(cursor = nil, search = nil, sort = nil, page_size = 50, fil
 end
 ```
 
+## Testing with Shared Examples
+
+PackAPI includes RSpec shared examples to help test your API query methods. These are opt-in and only need to be loaded if you're using RSpec.
+
+### Loading Shared Examples
+
+In your `spec_helper.rb` or `rails_helper.rb`, require the shared examples you need:
+
+```ruby
+# Load all shared examples
+require 'pack_api/rspec/shared_examples_for_api_query_methods'
+require 'pack_api/rspec/shared_examples_for_paginated_results'
+
+# Or load them individually as needed
+require 'pack_api/rspec/shared_examples_for_api_query_methods'
+```
+
+### Using the Shared Examples
+
+**Testing API Query Methods:**
+
+```ruby
+RSpec.describe 'query_blog_posts' do
+  let(:api_query_method) { method(:query_blog_posts) }
+  let(:resources) { BlogPost.all }
+
+  it_behaves_like 'an API query method'
+
+  # With custom options
+  it_behaves_like 'an API query method',
+    model_id_attribute: :uuid,
+    supports_search: true do
+    let(:search_terms) { "searchable text" }
+    let(:matched_resources) { BlogPost.where("title LIKE ?", "%searchable%") }
+  end
+end
+```
+
+**Testing Paginated Methods:**
+
+```ruby
+RSpec.describe 'paginated query' do
+  let(:paginated_api_query_method) { method(:query_blog_posts) }
+  let(:paginated_resources) { BlogPost.all }
+
+  it_behaves_like 'a paginated API method', model_id_attribute: :external_id
+end
+```
+
 ## Development
 
 After checking out the repo, run:

data/lib/pack_api/rspec/shared_examples_for_api_query_methods.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module PackAPI
+  ###
+  # Assumes the following variables are defined:
+  # - api_query_method: the method to call
+  # - resources: the resources to compare against (must be more than 1)
+  #
+  # If the options contain a key :model_id_attribute, then the public id will be mapped to the given model attribute.
+  # Otherwise, it defaults to :external_id.
+  #
+  # If the options contain a key: `supports_search` set to `true`, then
+  # the following variables are also required:
+  # - search_terms: a string, representing the search terms to use
+  # - matched_resources: *at least 2* resources that will be returned by the search
+  RSpec.shared_examples 'an API query method' do |**options|
+    let(:model_id_attribute) { options[:model_id_attribute] || :external_id }
+
+    context 'with no id' do
+      it 'returns a successful result with all resources' do
+        # when
+        result = api_query_method.call
+
+        # then
+        expect(result.success).to be_truthy, -> { result.errors }
+        expect(result.errors).to be_nil
+        expect(result.value).not_to be_nil
+        expect(result.value).to have(resources.count).items
+        expect(result.value.pluck(:id).sort).to match_array(resources.pluck(model_id_attribute).sort)
+      end
+    end
+
+    context 'with nil id' do
+      it 'returns a successful result with all resources' do
+        # when
+        result = api_query_method.call(id: nil)
+
+        # then
+        expect(result.success).to be_truthy, -> { result.errors }
+        expect(result.errors).to be_nil
+        expect(result.value).not_to be_nil
+        expect(result.value).to have(resources.count).items
+        expect(result.value.pluck(:id).sort).to match_array(resources.pluck(model_id_attribute).sort)
+      end
+    end
+
+    context 'with an empty string id' do
+      it 'returns a successful result with no resources' do
+        # when
+        result = api_query_method.call(id: '')
+
+        # then
+        expect(result.success).to be_truthy, -> { result.errors }
+        expect(result.errors).to be_nil
+        expect(result.value).not_to be_nil
+        expect(result.value).to have(0).items
+      end
+    end
+
+    context 'with an empty array id' do
+      it 'returns a successful result with no resources' do
+        # when
+        result = api_query_method.call(id: [])
+
+        # then
+        expect(result.success).to be_truthy, -> { result.errors }
+        expect(result.errors).to be_nil
+        expect(result.value).not_to be_nil
+        expect(result.value).to have(0).items
+      end
+    end
+
+    context 'with an unknown id' do
+      it 'returns an empty success result' do
+        result = api_query_method.call(id: 'unknown')
+        expect(result.success).to be_truthy, -> { result.errors }
+        expect(result.value).to have(0).items
+      end
+    end
+
+    context 'with a known id' do
+      it 'returns a success result with the resource' do
+        value = api_query_method.call(id: resources.first[model_id_attribute])
+        expect(value.success).to be_truthy, -> { result.errors }
+        expect(value.value).to have(1).item
+        expect(value.value.first.id).to eq(resources.first[model_id_attribute])
+      end
+    end
+
+    it_behaves_like 'a paginated API method', model_id_attribute: options[:model_id_attribute] || :external_id do
+      let(:paginated_api_query_method) { api_query_method }
+      let(:paginated_resources) { resources }
+    end
+
+    context 'with search terms', if: options[:supports_search] do
+      it 'limits results to matching resources' do
+        # when
+        result = api_query_method.call(search_terms:)
+        # then
+        expect(result.success).to be_truthy, -> { result.errors }
+        expect(result.value).to have(matched_resources.size).item
+        matched_resource_ids = matched_resources.pluck(model_id_attribute)
+        result.value.each do |resource|
+          expect(matched_resource_ids).to include(resource.id)
+        end
+      end
+
+      it_behaves_like 'a paginated API method', model_id_attribute: options[:model_id_attribute] || :external_id do
+        let(:paginated_api_query_method) do
+          ->(**args) { api_query_method.call(search_terms:, **args) }
+        end
+        let(:paginated_resources) { matched_resources }
+      end
+    end
+
+    it 'supports sorting by API attributes only' do
+      resources.each_with_index { |resource, index| resource.update(model_id_attribute => format('%02d', index + 1)) }
+      # when - sort by API attribute `id` in descending order
+      results = api_query_method.call(sort: { id: :desc })
+      # then - results should be in model_id_attribute in descending order
+      expect(results.success).to be_truthy, -> { results.errors }
+      expect(results.value.first.id).to eq(resources.last[model_id_attribute])
+      expect(results.value.last.id).to eq(resources.first[model_id_attribute])
+    end
+  end
+end

data/lib/pack_api/rspec/shared_examples_for_paginated_results.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PackAPI
+  ###
+  # Assumes the following variables are defined:
+  # - paginated_api_query_method: the method to call
+  # - paginated_resources: the resources to compare against (must be more than 1)
+  #
+  # If the options contain a key :model_id_attribute, then the public id will be mapped to the given model attribute.
+  # Otherwise, it defaults to :external_id.
+  # If the options contain a key :public_id_attribute, that will be used to access the resource identifier in the results.
+  RSpec.shared_examples 'a paginated API method' do |**options|
+    let(:public_id_attribute) { options[:public_id_attribute] || :id }
+    let(:model_id_attribute) { options[:model_id_attribute] || :external_id }
+
+    it 'can access the resources page-by-page' do
+      returned_object_ids = []
+
+      page_one_results = paginated_api_query_method.call(per_page: 1)
+      expect(page_one_results.success).to be_truthy, -> { page_one_results.errors }
+      expect(page_one_results.value).to have(1).item
+      expect(page_one_results.collection_metadata.next_page_cursor).not_to be_nil
+      returned_object_ids << page_one_results.value.first.send(public_id_attribute)
+      next_page_cursor = page_one_results.collection_metadata.next_page_cursor
+
+      (paginated_resources.count - 1).times do |index|
+        next_page_results = paginated_api_query_method.call(per_page: 1, cursor: next_page_cursor)
+        expect(next_page_results.success).to be_truthy, -> { next_page_results.errors }
+        expect(next_page_results.value).to have(1).item
+        if index < paginated_resources.count - 2 # if not last page
+          expect(next_page_results.collection_metadata.next_page_cursor).not_to be_nil, 'next page cursor should not be nil'
+          next_page_cursor = next_page_results.collection_metadata.next_page_cursor
+        else
+          expect(next_page_results.collection_metadata.next_page_cursor).to be_nil, 'next page cursor should be nil'
+        end
+        returned_object_ids << next_page_results.value.first.send(public_id_attribute)
+      end
+
+      # verify all objects were returned
+      expect(returned_object_ids.sort).to match_array(paginated_resources.pluck(model_id_attribute).sort)
+    end
+
+    it 'can access the metadata (without data)' do
+      results = paginated_api_query_method.call(per_page: 0)
+      expect(results.success).to be_truthy, -> { results.errors }
+      expect(results.value).to be_empty
+      expect(results.collection_metadata).not_to be_nil
+      expect(results.collection_metadata.total_items).to eq(paginated_resources.count)
+    end
+  end
+end

data/lib/pack_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PackAPI
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pack_api
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Flytedesk
@@ -230,6 +230,8 @@ files:
 - lib/pack_api/querying/dynamic_enum_filter.rb
 - lib/pack_api/querying/filter_factory.rb
 - lib/pack_api/querying/sort_hash.rb
+- lib/pack_api/rspec/shared_examples_for_api_query_methods.rb
+- lib/pack_api/rspec/shared_examples_for_paginated_results.rb
 - lib/pack_api/types/aggregate_type.rb
 - lib/pack_api/types/base_type.rb
 - lib/pack_api/types/boolean_filter_definition.rb