jpie 1.1.0 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e425e58d806e51b4cb6ed58345acdc3169079011dca02fa8dfae18b57bbe70c
-  data.tar.gz: e0f9316d7a675048c5c63442e9f897452ffa62358d3ca73d8e8aa288122a623c
+  metadata.gz: 8c205d5463d3fffd9ccf158d1ef8df04e34e50fd6a7385f9b727a46676181c00
+  data.tar.gz: 1c8e628e95a5296baa459c89cbc7d2bd119f4bb5e0456f5d9d3e4c8322b08a92
 SHA512:
-  metadata.gz: 36c41c6de0027699b5534abe379930f67fc67698aa8016635a294b8ba5624ace0bedaeaebddfbf5708c3ad58696527b1e15f177ac84c36c272581cff123a52ec
-  data.tar.gz: c948938233596ef3345bc7186e8f78575f37c1057d9675850634ddb53c36506de7b26b89f14555fdca8659124ae8ec0b9908da39324f87cff90dd82aa2c8cd8d
+  metadata.gz: 17bb979968aba9d606fdb537c5ebba08e8d29b39e9ffd2dbaefeaaeafc4a41b1ebb686429cd20ffd10db9276320d0e70e7cc94551a418863dbdd633542df67f6
+  data.tar.gz: 8fad54116b4eaa6c2e77f9e8034f477a3c9cb4911cc749ff00bf06cc30d801751ff0351771040dd94f6a639776aa0396775637e1d1fa4583a91a965e844ca8e8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jpie (1.1.0)
+    jpie (1.1.2)
       actionpack (~> 8.0, >= 8.0.0)
       rails (~> 8.0, >= 8.0.0)
 

data/lib/json_api/testing/rspec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Main RSpec integration for JSON:API testing support.
+#
+# Usage in your rails_helper.rb or spec_helper.rb:
+#
+#   require "json_api/testing/rspec"
+#
+# This will:
+# 1. Load all shared example module definitions
+# 2. Load all shared examples for resources and responses
+# 3. Load STI testing helpers for request specs
+# 4. Make the modules available at the top level for convenient usage
+#
+# After requiring, you can use shared examples like:
+#
+#   it_behaves_like [ Jpie, Resource, :has_attributes ].to_s, :name, :email
+#   it_behaves_like [ Jpie, Response, :data ].to_s, type: "users"
+#   it_behaves_like [ Jpie, Response, :sti_types ].to_s, expected_subtypes: ["user_messages"]
+#
+# And STI helpers in request specs:
+#
+#   expect_sti_types_in_included(expected_subtypes: ["user_messages"])
+#   expect_sti_resources_included(sti_type: "user_messages", expected_ids: [msg.id])
+
+require_relative "shared_examples/modules"
+require_relative "sti_helpers"
+
+# Load shared examples
+Dir[File.join(__dir__, "shared_examples", "*.rb")].each do |file|
+  require file unless file.end_with?("modules.rb")
+end
+
+# Make modules available at top level when included
+RSpec.configure do |config|
+  config.include(Module.new do
+    %i[Jpie Resource Response].each do |const|
+      define_method(const) { Object.const_get(const) }
+    end
+  end)
+
+  # Include STI helpers for request specs
+  config.include JSONAPI::Testing::StiHelpers, type: :request
+end

data/lib/json_api/testing/shared_examples/active_storage.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# Shared examples for testing ActiveStorage attachment serialization in JSON:API resources.
+#
+# Usage:
+#   RSpec.describe UserResource, type: :resource do
+#     let(:model) { users(:one) }
+#
+#     it_behaves_like [ Jpie, Resource, :has_one_attached ].to_s, :avatar, :model
+#     it_behaves_like [ Jpie, Resource, :has_many_attached ].to_s, :documents, :model
+#   end
+
+RSpec.shared_examples [Jpie, Resource, :has_one_attached].to_s do |rel_name, fixture_method| # rubocop:disable Metrics/BlockLength
+  describe "#{rel_name} ActiveStorage serialization" do # rubocop:disable Metrics/BlockLength
+    let(:file_fixture) { fixture_file_upload("avatar.jpg") }
+    let(:fixture) { send(fixture_method) }
+    let(:attachment) { fixture.public_send(rel_name) }
+    let(:serializer) { JSONAPI::Serializer.new(fixture) }
+    let(:serialized) { serializer.serialize_record }
+
+    context "without attachment" do
+      before do
+        attachment.purge if attachment.attached?
+        fixture.reload
+      end
+
+      it { expect(serialized.dig(:relationships, rel_name, :data)).to be_nil }
+    end
+
+    context "with attachment" do
+      before do
+        attachment.attach(file_fixture)
+        fixture.reload
+      end
+
+      it "serializes as active_storage_blobs", :aggregate_failures do
+        data = serialized.dig(:relationships, rel_name, :data)
+        expect(data).to include(type: "active_storage_blobs", id: attachment.blob.id.to_s)
+      end
+
+      context "when included" do
+        let(:serialized) { serializer.to_hash(include: [rel_name.to_s]) }
+
+        it "includes blob details", :aggregate_failures do
+          blob = serialized[:included].find { |r| r[:type] == "active_storage_blobs" }
+          expect(blob[:attributes]).to include(filename: "avatar.jpg", content_type: "image/jpeg")
+          expect(blob[:links][:download]).to be_present
+        end
+      end
+    end
+  end
+end
+
+RSpec.shared_examples [Jpie, Resource, :has_many_attached].to_s do |rel_name, fixture_method| # rubocop:disable Metrics/BlockLength
+  describe "#{rel_name} ActiveStorage serialization" do # rubocop:disable Metrics/BlockLength
+    let(:file_fixture) { fixture_file_upload("avatar.jpg") }
+    let(:fixture) { send(fixture_method) }
+    let(:attachments) { fixture.public_send(rel_name) }
+    let(:serializer) { JSONAPI::Serializer.new(fixture) }
+    let(:serialized) { serializer.serialize_record }
+
+    context "without attachments" do
+      before do
+        attachments.each(&:purge) if attachments.attached?
+        fixture.reload
+      end
+
+      it { expect(serialized.dig(:relationships, rel_name, :data)).to eq([]) }
+    end
+
+    context "with attachments" do
+      before do
+        attachments.each(&:purge) if attachments.attached?
+        attachments.attach(file_fixture)
+        fixture.reload
+      end
+
+      it "serializes as active_storage_blobs array", :aggregate_failures do
+        data = serialized.dig(:relationships, rel_name, :data)
+        expect(data).to be_an(Array)
+        expect(data.first).to include(type: "active_storage_blobs", id: attachments.first.blob.id.to_s)
+      end
+
+      context "when included" do
+        let(:serialized) { serializer.to_hash(include: [rel_name.to_s]) }
+
+        it "includes blob details", :aggregate_failures do
+          blob = serialized[:included].find { |r| r[:type] == "active_storage_blobs" }
+          expect(blob[:attributes]).to include(filename: "avatar.jpg", content_type: "image/jpeg")
+          expect(blob[:links][:download]).to be_present
+        end
+      end
+    end
+  end
+end

data/lib/json_api/testing/shared_examples/modules.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Module definitions for shared example naming in JSON:API specs.
+# This follows the pattern: [ Jpie, Category, :symbol ].to_s
+#
+# Usage:
+#   RSpec.shared_examples [ Jpie, Resource, :has_attributes ].to_s do
+#     ...
+#   end
+#
+#   it_behaves_like [ Jpie, Resource, :has_attributes ].to_s, :name, :email
+#   it_behaves_like [ Jpie, Response, :data ].to_s, type: "users"
+#
+# These modules are made available at the top level when you require
+# "json_api/testing/rspec" in your RSpec configuration.
+
+# Gem namespace - prefix for all jpie shared examples
+module Jpie; end
+
+# Resource-level shared examples (for testing resource class definitions)
+module Resource; end
+
+# Response-level shared examples (for testing JSON:API response structure)
+module Response; end

data/lib/json_api/testing/shared_examples/resources.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Shared examples for testing JSON:API Resource class definitions.
+#
+# Usage:
+#   RSpec.describe UserResource do
+#     it_behaves_like [ Jpie, Resource, :has_attributes ].to_s, :name, :email
+#     it_behaves_like [ Jpie, Resource, :has_one ].to_s, :account
+#     it_behaves_like [ Jpie, Resource, :has_many ].to_s, :posts
+#     it_behaves_like [ Jpie, Resource, :has_filter ].to_s, :name
+#   end
+
+RSpec.shared_examples [Jpie, Resource, :has_attributes].to_s do |*attributes|
+  it "exposes exactly the expected attributes" do
+    expect(described_class.permitted_attributes).to match_array(attributes.map(&:to_sym))
+  end
+end
+
+RSpec.shared_examples [Jpie, Resource, :has_one].to_s do |name, **options|
+  describe "##{name} relationship" do
+    let(:relationship_def) { described_class.relationship_definitions.find { |r| r[:name] == name } }
+
+    it { expect(relationship_def).to be_present }
+    it { expect(relationship_def[:type]).to be_in(%i[has_one belongs_to]) }
+
+    class_name = options.fetch(:class_name, name.to_s.classify.to_s)
+    it { expect(relationship_def[:options][:class_name] || name.to_s.classify.to_s).to eql class_name }
+  end
+end
+
+RSpec.shared_examples [Jpie, Resource, :has_many].to_s do |name, **options|
+  describe "##{name} relationship" do
+    let(:relationship_def) { described_class.relationship_definitions.find { |r| r[:name] == name } }
+
+    it { expect(relationship_def).to be_present }
+    it { expect(relationship_def[:type]).to eq :has_many }
+
+    if options.key?(:class_name)
+      it "has the correct class_name" do
+        actual_class_name = relationship_def[:options][:class_name] || name.to_s.classify
+        expect(actual_class_name).to eql options[:class_name]
+      end
+    end
+  end
+end
+
+RSpec.shared_examples [Jpie, Resource, :has_filter].to_s do |name|
+  describe "##{name} filter" do
+    it "exposes the expected filter (base or comparator)" do
+      expected = [name.to_sym, :"#{name}_eq"]
+      expect(described_class.permitted_filters & expected).to be_present
+    end
+  end
+end

data/lib/json_api/testing/shared_examples/responses.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+# Shared examples for testing JSON:API response structure.
+#
+# These shared examples verify that API responses conform to JSON:API specification.
+# They assume the response is available via `response` and use `response.parsed_body`.
+#
+# Usage:
+#   RSpec.describe "Users API", type: :request do
+#     describe "GET /users/:id" do
+#       before { get user_path(user), headers: headers, as: :jsonapi }
+#
+#       it_behaves_like [ Jpie, Response, :data ].to_s, type: "users"
+#       it_behaves_like [ Jpie, Response, :attributes ].to_s, :name, :email
+#     end
+#   end
+
+RSpec.shared_examples [Jpie, Response, :data].to_s do |type: nil|
+  it "returns data with correct structure" do
+    data = response.parsed_body["data"]
+    expect(data).to be_present
+
+    if data.is_a?(Array)
+      data.each do |item|
+        expect(item).to have_key("type")
+        expect(item).to have_key("id")
+        expect(item["type"]).to eq(type.to_s) if type
+      end
+    else
+      expect(data).to have_key("type")
+      expect(data).to have_key("id")
+      expect(data["type"]).to eq(type.to_s) if type
+    end
+  end
+end
+
+RSpec.shared_examples [Jpie, Response, :attributes].to_s do |*attributes|
+  it "includes expected attributes in response" do
+    data = response.parsed_body["data"]
+    data = data.first if data.is_a?(Array)
+
+    expect(data).to have_key("attributes")
+    attributes.each do |attr|
+      msg = "Expected attribute '#{attr}', got: #{data["attributes"].keys}"
+      expect(data["attributes"]).to have_key(attr.to_s), msg
+    end
+  end
+end
+
+RSpec.shared_examples [Jpie, Response, :relationships].to_s do |*relationships|
+  it "includes expected relationships in response" do
+    data = response.parsed_body["data"]
+    data = data.first if data.is_a?(Array)
+
+    expect(data).to have_key("relationships")
+    relationships.each do |rel|
+      msg = "Expected relationship '#{rel}', got: #{data["relationships"].keys}"
+      expect(data["relationships"]).to have_key(rel.to_s), msg
+    end
+  end
+end
+
+RSpec.shared_examples [Jpie, Response,
+                       :included,].to_s do |type: nil, count: nil, sti_subtypes: nil, exclude_base_type: nil|
+  it "includes compound document data" do
+    included = response.parsed_body["included"]
+    expect(included).to be_an(Array)
+    expect(included).not_to be_empty
+
+    if type
+      matching = included.select { |item| item["type"] == type.to_s }
+      expect(matching).not_to be_empty, "Expected included to contain type '#{type}'"
+      expect(matching.size).to eq(count) if count
+    end
+
+    if sti_subtypes
+      included_types = included.pluck("type").uniq
+      sti_subtypes.each do |subtype|
+        expect(included_types).to include(subtype.to_s),
+                                  "Expected included to contain STI subtype '#{subtype}', got: #{included_types}"
+      end
+    end
+
+    if exclude_base_type
+      included_types ||= included.pluck("type").uniq
+      expect(included_types).not_to include(exclude_base_type.to_s),
+                                    "Expected included NOT to contain base type '#{exclude_base_type}', but it did"
+    end
+  end
+end
+
+RSpec.shared_examples [Jpie, Response, :links].to_s do |*link_keys|
+  it "includes links in response" do
+    links = response.parsed_body["links"]
+    expect(links).to be_a(Hash)
+
+    link_keys.each do |key|
+      msg = "Expected link '#{key}', got: #{links.keys}"
+      expect(links).to have_key(key.to_s), msg
+    end
+  end
+end
+
+RSpec.shared_examples [Jpie, Response, :meta].to_s do |*meta_keys|
+  it "includes meta in response" do
+    meta = response.parsed_body["meta"]
+    expect(meta).to be_a(Hash)
+
+    meta_keys.each do |key|
+      msg = "Expected meta '#{key}', got: #{meta.keys}"
+      expect(meta).to have_key(key.to_s), msg
+    end
+  end
+end
+
+RSpec.shared_examples [Jpie, Response, :errors].to_s do |count: nil|
+  it "returns errors array" do
+    errors = response.parsed_body["errors"]
+    expect(errors).to be_an(Array)
+    expect(errors).not_to be_empty
+    expect(errors.size).to eq(count) if count
+
+    errors.each do |error|
+      # JSON:API error objects should have at least one of these
+      expect(error.keys & %w[id status code title detail source meta]).not_to be_empty
+    end
+  end
+end
+
+RSpec.shared_examples [Jpie, Response, :sti_types].to_s do |expected_subtypes:, exclude_base_type: nil|
+  it "returns STI subtypes correctly" do
+    data = response.parsed_body["data"]
+    data = [data] unless data.is_a?(Array)
+    types = data.pluck("type").uniq
+
+    expected_subtypes.each do |subtype|
+      expect(types).to include(subtype.to_s),
+                       "Expected data to contain STI subtype '#{subtype}', got: #{types}"
+    end
+
+    if exclude_base_type
+      expect(types).not_to include(exclude_base_type.to_s),
+                           "Expected data NOT to contain base type '#{exclude_base_type}', but it did"
+    end
+  end
+end
+
+RSpec.shared_examples [Jpie, Response, :sti_included].to_s do |expected_subtypes:, exclude_base_type: nil|
+  it "includes STI subtypes correctly" do
+    included = response.parsed_body["included"] || []
+    expect(included).not_to be_empty, "Expected included to be present"
+
+    included_types = included.pluck("type").uniq
+
+    expected_subtypes.each do |subtype|
+      expect(included_types).to include(subtype.to_s),
+                                "Expected included to contain STI subtype '#{subtype}', got: #{included_types}"
+    end
+
+    if exclude_base_type
+      expect(included_types).not_to include(exclude_base_type.to_s),
+                                    "Expected included NOT to contain base type '#{exclude_base_type}', but it did"
+    end
+  end
+end

data/lib/json_api/testing/sti_helpers.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Testing
+    # Helper methods for testing STI (Single Table Inheritance) resources in JSON:API responses.
+    #
+    # These helpers simplify testing that STI subtypes are correctly serialized
+    # and included in JSON:API responses.
+    #
+    # Usage in request specs:
+    #
+    #   it "includes user messages", :aggregate_failures do
+    #     get conversation_path(conversation), params: { include: "messages" }, as: :jsonapi
+    #     expect_sti_types_in_included(expected_subtypes: ["user_messages"])
+    #     expect_sti_resources_included(sti_type: "user_messages", expected_ids: [message.id])
+    #   end
+    module StiHelpers
+      # Verify that included resources contain expected STI subtypes.
+      #
+      # @param expected_subtypes [Array<String, Symbol>] Expected STI subtype names
+      # @param exclude_base_type [String, Symbol, nil] Base type that should NOT be present (optional)
+      # @return [void]
+      #
+      # @example Verify subtypes are present
+      #   expect_sti_types_in_included(expected_subtypes: ["user_messages", "ai_messages"])
+      #
+      # @example Verify subtypes and exclude base type
+      #   expect_sti_types_in_included(
+      #     expected_subtypes: ["user_messages"],
+      #     exclude_base_type: "messages"
+      #   )
+      def expect_sti_types_in_included(expected_subtypes:, exclude_base_type: nil)
+        included = response.parsed_body["included"] || []
+        included_types = included.pluck("type").uniq
+
+        expected_subtypes.each do |subtype|
+          expect(included_types).to include(subtype.to_s),
+                                    "Expected included to contain STI type '#{subtype}', got: #{included_types}"
+        end
+
+        return if exclude_base_type.blank?
+
+        expect(included_types).not_to include(exclude_base_type.to_s),
+                                      "Expected included NOT to contain base type '#{exclude_base_type}', but it did"
+      end
+
+      # Find all resources of a specific STI type in the included array.
+      #
+      # @param sti_type [String, Symbol] The STI subtype to find
+      # @return [Array<Hash>] Array of resource objects matching the STI type
+      #
+      # @example Find all user messages in included
+      #   messages = find_sti_resources_in_included("user_messages")
+      #   expect(messages.first["attributes"]["content"]).to eq("Hello")
+      def find_sti_resources_in_included(sti_type)
+        included = response.parsed_body["included"] || []
+        included.select { |item| item["type"] == sti_type.to_s }
+      end
+
+      # Verify that specific STI resources are included by ID.
+      #
+      # @param sti_type [String, Symbol] The STI subtype
+      # @param expected_ids [Array<Integer, String>] Expected resource IDs
+      # @return [void]
+      #
+      # @example Verify specific messages are included
+      #   expect_sti_resources_included(
+      #     sti_type: "user_messages",
+      #     expected_ids: [message1.id, message2.id]
+      #   )
+      def expect_sti_resources_included(sti_type:, expected_ids:)
+        resources = find_sti_resources_in_included(sti_type)
+        actual_ids = resources.map { |r| r["id"] }
+        expected_ids_str = expected_ids.map(&:to_s)
+
+        expect(actual_ids).to match_array(expected_ids_str),
+                              "Expected #{sti_type} resources with IDs #{expected_ids_str}, got: #{actual_ids}"
+      end
+
+      # Verify STI types in data array (not included).
+      #
+      # @param expected_subtypes [Array<String, Symbol>] Expected STI subtype names
+      # @param exclude_base_type [String, Symbol, nil] Base type that should NOT be present (optional)
+      # @return [void]
+      #
+      # @example Verify data contains correct STI types
+      #   expect_sti_types_in_data(
+      #     expected_subtypes: ["user_messages", "ai_messages"],
+      #     exclude_base_type: "messages"
+      #   )
+      def expect_sti_types_in_data(expected_subtypes:, exclude_base_type: nil)
+        data = response.parsed_body["data"]
+        data = [data] unless data.is_a?(Array)
+        types = data.pluck("type").uniq
+
+        expected_subtypes.each do |subtype|
+          expect(types).to include(subtype.to_s),
+                           "Expected data to contain STI subtype '#{subtype}', got: #{types}"
+        end
+
+        return if exclude_base_type.blank?
+
+        expect(types).not_to include(exclude_base_type.to_s),
+                             "Expected data NOT to contain base type '#{exclude_base_type}', but it did"
+      end
+
+      # Find all resources of a specific STI type in the data array.
+      #
+      # @param sti_type [String, Symbol] The STI subtype to find
+      # @return [Array<Hash>] Array of resource objects matching the STI type
+      #
+      # @example Find all user messages in data
+      #   messages = find_sti_resources_in_data("user_messages")
+      def find_sti_resources_in_data(sti_type)
+        data = response.parsed_body["data"]
+        data = [data] unless data.is_a?(Array)
+        data.select { |item| item["type"] == sti_type.to_s }
+      end
+
+      # Verify that specific STI resources are present in data by ID.
+      #
+      # @param sti_type [String, Symbol] The STI subtype
+      # @param expected_ids [Array<Integer, String>] Expected resource IDs
+      # @return [void]
+      #
+      # @example Verify specific messages are in data
+      #   expect_sti_resources_in_data(
+      #     sti_type: "user_messages",
+      #     expected_ids: [message1.id, message2.id]
+      #   )
+      def expect_sti_resources_in_data(sti_type:, expected_ids:)
+        resources = find_sti_resources_in_data(sti_type)
+        actual_ids = resources.map { |r| r["id"] }
+        expected_ids_str = expected_ids.map(&:to_s)
+
+        expect(actual_ids).to match_array(expected_ids_str),
+                              "Expected #{sti_type} resources with IDs #{expected_ids_str}, got: #{actual_ids}"
+      end
+    end
+  end
+end

data/lib/json_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONAPI
-  VERSION = "1.1.0"
+  VERSION = "1.1.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jpie
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.2
 platform: ruby
 authors:
 - Emil Kampp
@@ -143,6 +143,12 @@ files:
 - lib/json_api/support/sort_parsing.rb
 - lib/json_api/support/type_conversion.rb
 - lib/json_api/testing.rb
+- lib/json_api/testing/rspec.rb
+- lib/json_api/testing/shared_examples/active_storage.rb
+- lib/json_api/testing/shared_examples/modules.rb
+- lib/json_api/testing/shared_examples/resources.rb
+- lib/json_api/testing/shared_examples/responses.rb
+- lib/json_api/testing/sti_helpers.rb
 - lib/json_api/testing/test_helper.rb
 - lib/json_api/version.rb
 - lib/rubocop/cop/custom/hash_value_omission.rb