factory_bot-blueprint-rspec 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 383c2e021a8f95d413975221ad71a812573085d87c344d9092489cd4701c7bcc
+  data.tar.gz: 855d528ff18cfa4e02645fd6eb7a24b65e170918ba759454ccd06bc5c7e14574
+SHA512:
+  metadata.gz: 791b93263904413b1bbdc11df06f18c5181fe44882a10c1d9b6c114b1eec33ee3222edf6a52fff90af03aead6e9e04dfedcf22e8410687bd8d11edea92203a26
+  data.tar.gz: 057af3f3d8bba6f971a4f6e18c40ab69a13829973b38b3bf1c73ddb6477104d704d5d24d524cbf6b567c8f2ebf2c4e1a7587161c3e601256efd9bfb843040f85

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 yubrot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,9 @@
+# `factory_bot-blueprint-rspec` gem
+
+This is a part of [FactoryBot::Blueprint](https://github.com/yubrot/factory_bot-blueprint) library.
+
+`factory_bot-blueprint` integration for RSpec.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/factory_bot/blueprint/rspec/driver.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module FactoryBot
+  module Blueprint
+    module RSpec
+      # Helper methods to integrate <code>factory_bot-blueprint</code> with RSpec.
+      # This module is automatically extended to {RSpec::Core::ExampleGroup}.
+      #
+      # To use FactoryBot::Blueprint from RSpec with minimal effort, usually {#letbp} is the best choice.
+      module Driver
+        # Shorthand method for <code>let(name) { ::FactoryBot::Blueprint.plan(...) }</code>.
+        # You can access the let binding context by <code>#ext</code> in DSL code.
+        # @param name [Symbol] name of the object to be declared using RSpec's <code>let</code>
+        # @param inherit [Boolean] whether to extend the blueprint by <code>super()</code>
+        # @yield Write Blueprint DSL code here
+        # @example
+        #   RSpec.describe "something" do
+        #     let(:blog_id) { SecureRandom.uuid }
+        #
+        #     let_blueprint(:blog_bp) do
+        #       let.blog(id: ext.blog_id, title: "Daily log") do
+        #         let.article(title: "Article 1")
+        #         article(title: "Article 2")
+        #         article(title: "Article 3")
+        #       end
+        #     end
+        #   end
+        def let_blueprint(name, inherit: false, &)
+          let(name) { ::FactoryBot::Blueprint.plan(inherit ? super() : nil, ext: self, &) }
+        end
+
+        # Build objects by <code>build</code> strategy in FactoryBot from a blueprint and declare them using RSpec's
+        # <code>let</code>.
+        # @param map [Hash{Symbol => Object}]
+        #   map data structure from source blueprints to instance definitions.
+        #   Each instance will be built with <code>FactoryBot::Blueprint.build(__send__(source))</code>
+        # @example
+        #   RSpec.describe "something" do
+        #     let_blueprint(:blog_bp) do
+        #       # ... Write some DSL ...
+        #     end
+        #
+        #     # Simplest example:
+        #     # This is equivalent to `let_blueprint_build blog_bp: { representative: :blog }`
+        #     let_blueprint_build blog_bp: :blog
+        #
+        #     # Another shorthand example:
+        #     # This is equivalent to `let_blueprint_build blog_bp: { items: %i[blog article] }`
+        #     let_blueprint_build blog_bp: %i[blog article]
+        #
+        #     # Most flexible example:
+        #     #   :representative specifies the name of the representative object to be declared. Defaults to nil
+        #     #   :items specifies the names of the objects to be declared. Defaults to []
+        #     #   :instance specifies the name of the instance object to be declared. Defaults to :"#{source}_instance"
+        #     let_blueprint_build blog_bp: { representative: :blog, items: %i[article], instance: :blog_instance }
+        #
+        #     # Above example will be expanded to:
+        #     let(:blog_instance) { ::FactoryBot::Blueprint.build(blog_bp) }  # the instance object
+        #     let(:blog) { blog_instance[blog_bp.representative_node.name] }  # the representative object
+        #     let(:article) { blog_instance[:article] }                       # the item objects
+        #   end
+        def let_blueprint_build(**map) = let_blueprint_instantiate(:build, **map)
+
+        # Build objects by <code>create</code> strategy in FactoryBot from a blueprint and declare them using RSpec's
+        # <code>let</code>.
+        # See {#let_blueprint_build} for more details.
+        # @param map [Hash{Symbol => Object}]
+        #   map data structure from source blueprints to instance definitions.
+        #   Each instance will be built with <code>FactoryBot::Blueprint.build(__send__(source))</code>
+        def let_blueprint_create(**map) = let_blueprint_instantiate(:create, **map)
+
+        # @!visibility private
+        def let_blueprint_instantiate(strategy, **map)
+          raise ArgumentError, "Unsupported strategy: #{strategy}" if strategy && !%i[create build].include?(strategy)
+
+          map.each do |source, definition|
+            raise TypeError, "source must be a Symbol" unless source.is_a?(Symbol)
+
+            definition =
+              case definition
+              when Symbol
+                { representative: definition }
+              when Array
+                { items: definition }
+              when Hash
+                definition
+              else
+                raise TypeError, "definition must be one of Symbol, Array, Hash"
+              end
+
+            representative_name = definition[:representative]
+            item_names = definition[:items] || []
+            instance = definition[:instance] || :"#{source}_instance"
+
+            if representative_name && !representative_name.is_a?(Symbol)
+              raise TypeError, "representative must be a Symbol"
+            end
+            if !item_names.is_a?(Array) || !item_names.all? { _1.is_a?(Symbol) }
+              raise TypeError, "items must be an Array of Symbols"
+            end
+            raise TypeError, "instance must be a Symbol" unless instance.is_a?(Symbol)
+
+            if strategy # If no strategy is specified, the instance is assumed to exist
+              let(instance) { ::FactoryBot::Blueprint.instantiate(strategy, __send__(source)) }
+            end
+
+            if representative_name
+              let(representative_name) { __send__(instance)[__send__(source).representative_node.name] }
+            end
+
+            item_names.each do |name|
+              let(name) { __send__(instance)[name] }
+            end
+          end
+        end
+
+        # Write the blueprint in DSL, create an instance of it, and declare each object of the instance using RSpec's
+        # <code>let</code>.
+        #
+        # This is a shorthand for {#let_blueprint} with {#let_blueprint_build} or {#let_blueprint_create}.
+        # @param name [Symbol]
+        #   name of the representative object to be declared using RSpec's <code>let</code>.
+        #   It is also used as a name prefix of the blueprint
+        # @param items [Array<Symbol>] names of the objects to be declared using RSpec's <code>let</code>
+        # @param inherit [Boolean] whether to extend the blueprint by <code>super()</code>
+        # @param strategy [:create, :build]
+        #   FactoryBot strategy to use when building objects.
+        #   This option is ignored if <code>inherit: true</code>
+        # @yield Write Blueprint DSL code here
+        # @example
+        #   RSpec.describe "something" do
+        #     letbp(:blog, %i[article]) do
+        #       blog(title: "Daily log") do
+        #         let.article(title: "Article 1")
+        #         article(title: "Article 2")
+        #         article(title: "Article 3")
+        #       end
+        #     end
+        #
+        #     # Above example will be expanded to:
+        #     let_blueprint(:blog_blueprint) do
+        #       blog(title: "Daily log") do
+        #         let.article(title: "Article 1")
+        #         article(title: "Article 2")
+        #         article(title: "Article 3")
+        #       end
+        #     end
+        #     let_blueprint_create blog_blueprint: { representative: :blog, items: %i[article] }
+        #   end
+        def letbp(name, items = [], inherit: false, strategy: :create, &)
+          raise TypeError, "name must be a Symbol" unless name.is_a?(Symbol)
+
+          source = :"#{name}_blueprint"
+          strategy = nil if inherit
+
+          let_blueprint(source, inherit:, &)
+          let_blueprint_instantiate strategy, source => { representative: name, items: }
+        end
+      end
+    end
+  end
+end
+
+# @!visibility private
+module RSpec
+  module Core
+    class ExampleGroup
+      extend ::FactoryBot::Blueprint::RSpec::Driver
+    end
+  end
+end

data/lib/factory_bot/blueprint/rspec/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module FactoryBot
+  module Blueprint
+    module RSpec
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/factory_bot/blueprint/rspec.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "factory_bot/blueprint"
+require_relative "rspec/version"
+require_relative "rspec/driver"

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: factory_bot-blueprint-rspec
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- yubrot
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-07-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: factory_bot-blueprint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: FactoryBot::Blueprint integration for RSpec
+email:
+- yubrot@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/factory_bot/blueprint/rspec.rb
+- lib/factory_bot/blueprint/rspec/driver.rb
+- lib/factory_bot/blueprint/rspec/version.rb
+homepage: https://github.com/yubrot/factory_bot-blueprint
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yubrot/factory_bot-blueprint
+  source_code_uri: https://github.com/yubrot/factory_bot-blueprint
+  changelog_uri: https://github.com/yubrot/factory_bot-blueprint/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: FactoryBot::Blueprint integration for RSpec
+test_files: []