factory_bot-blueprint-rspec 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f99bbc7d1b7e6a8a7fb74d0fb64b88efb1baff08a583fdab7491db3c81ab4233
-  data.tar.gz: 2aa5ba9a0705e6389236e8e5699e2d0cb7c418c70373b9ef74d71c854450a473
+  metadata.gz: 2559690c18cf146c86024386fff1630989c0e201499564fda52e09003a58b6bf
+  data.tar.gz: a6ecd312a009b3b3caf698fec6b8b1f2eb2f2973aaf3f8d8d9c92d5ab91e3b40
 SHA512:
-  metadata.gz: 71b5c78c7b59fa4f97c2171591dbe2533fd901fc4e7bd7647e48e017ce26f509e9c4c75178d3d86494c275b92e07431f11ca88c66de0164cf9b77cf3c2c1e321
-  data.tar.gz: d8e3182c44520b7ea3d2233388bf7711690f71c050f9a37089955ddad25cb9c62c5170440a486a977ae7d0b8c90a78001195bde7ea1e224026b7a497d43b67b5
+  metadata.gz: 4d38916bb4b3d7b7d68cd60fb73fc4b15acd5513e08e447d9a5c3907972c409a686367e43dc6af562c8343388aa52e7a0d2d5694382b92e57be91e6c9aed1a40
+  data.tar.gz: 29886e7b5454c8b346e0d6c6f0a961c1913079a9ed85acdbbe03b751e7ae6f8530f3a7bcf725775662bd8f9e7e5ac20bbd6bbcc18d0587106bd9e37f15d50796

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

@@ -4,129 +4,18 @@ 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.
+      # This module is automatically extended to <code>RSpec::Core::ExampleGroup</code>.
       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, &) }
-          name
-        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: { result: :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:
-        #     #   :result specifies the name of the result 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: { result: :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[Factrey::Blueprint::Node::RESULT_NAME] }  # the result 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.map do |source, definition|
-            raise TypeError, "source must be a Symbol" unless source.is_a?(Symbol)
-
-            definition =
-              case definition
-              when Symbol
-                { result: definition }
-              when Array
-                { items: definition }
-              when Hash
-                definition
-              else
-                raise TypeError, "definition must be one of Symbol, Array, Hash"
-              end
-
-            result_name = definition[:result]
-            item_names = definition[:items] || []
-            instance = definition[:instance] || :"#{source}_instance"
-
-            raise TypeError, "result must be a Symbol" if result_name && !result_name.is_a?(Symbol)
-            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
-
-            let(result_name) { __send__(instance)[::Factrey::Blueprint::Node::RESULT_NAME] } if result_name
-
-            item_names.each { |name| let(name) { __send__(instance)[name] } }
-
-            instance
-          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 method expresses that the names given as arguments will be used in the let declaration for the set of
+        # objects to be created from the blueprint. Subsequent method calls specify specifically how to use FactoryBot
+        # to create the set of objects from the blueprint.
         #
-        # This is a shorthand for {#let_blueprint} with {#let_blueprint_build} or {#let_blueprint_create}.
-        # @param name [Symbol]
-        #   name of the result object to be declared using RSpec's <code>let</code>.
-        #   It is also used as a name prefix of the blueprint
+        # @param name [Symbol] name of the result object to be declared using RSpec's <code>let</code>
         # @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
+        # @return [Letbp]
         # @example
         #   RSpec.describe "something" do
-        #     letbp(:blog, %i[article]) do
+        #     letbp(:blog, %i[article]).build do
         #       blog(title: "Daily log") do
         #         let.article(title: "Article 1")
         #         article(title: "Article 2")
@@ -134,48 +23,43 @@ module FactoryBot
         #       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")
+        #     # Above example will be expanded to ...
+        #
+        #     # Create a blueprint:
+        #     let(:_letbp_blog_blueprint) do
+        #       FactoryBot::Blueprint.plan(ext: self) do
+        #         blog(title: "Daily log") do
+        #           let.article(title: "Article 1")
+        #           article(title: "Article 2")
+        #           article(title: "Article 3")
+        #         end
         #       end
         #     end
-        #     let_blueprint_create blog_blueprint: { result: :blog, items: %i[article] }
+        #
+        #     # Create a set of objects (with `build` build strategy) from it:
+        #     let(:_letbp_blog_instance) { FactoryBot::Blueprint.build(_letbp_blog_blueprint) }
+        #
+        #     # Declare the result object:
+        #     let(:blog) { _letbp_blog_instance[Factrey::Blueprint::Node::RESULT_NAME] }
+        #
+        #     # Declare the named objects:
+        #     let(:article) { _letbp_blog_instance[: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 => { result: name, items: }
-        end
-
-        # <code>let!</code> version of {#let_blueprint}.
-        def let_blueprint!(...)
-          name = let_blueprint(...)
-          before { __send__(name) }
-        end
-
-        # <code>let!</code> version of {#let_blueprint_build}.
-        def let_blueprint_build!(...)
-          names = let_blueprint_build(...)
-          before { names.each { __send__(_1) } }
-        end
-
-        # <code>let!</code> version of {#let_blueprint_create}.
-        def let_blueprint_create!(...)
-          names = let_blueprint_create(...)
-          before { names.each { __send__(_1) } }
-        end
+        def letbp(name, items = []) = Letbp.new(self, :lazy, name, items)
 
         # <code>let!</code> version of {#letbp}.
-        def letbp!(...)
-          names = letbp(...)
-          before { names.each { __send__(_1) } }
+        # @param name [Symbol]
+        # @param items [Array<Symbol>]
+        # @return [Letbp]
+        def letbp!(name, items = []) = Letbp.new(self, :eager, name, items)
+
+        # <code>let_it_be</code> version of {#letbp}. This requires {https://github.com/test-prof/test-prof test-prof}.
+        # @param name [Symbol]
+        # @param items [Array<Symbol>]
+        # @param options [Hash] options for <code>let_it_be</code>
+        # @return [Letbp]
+        def letbp_it_be(name, items = [], **options)
+          Letbp.new(self, :let_it_be, name, items, let_it_be_options: options)
         end
       end
     end

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module FactoryBot
+  module Blueprint
+    module RSpec
+      # An intermediate object for <code>letbp</code> syntax. See {Driver#letbp} for more details.
+      class Letbp
+        # @!visibility private
+        def initialize(context, kind, name, items, let_it_be_options: nil)
+          raise TypeError, "context must include FactoryBot::Blueprint::RSpec::Driver" unless context.is_a?(Driver)
+          raise ArgumentError, "unknown kind: #{kind}" unless %i[lazy eager let_it_be].include?(kind)
+          raise TypeError, "name must be a Symbol" unless name.is_a?(Symbol)
+          unless items.is_a?(Array) && items.all? { _1.is_a?(Symbol) }
+            raise TypeError, "items must be an Array of Symbols"
+          end
+          if let_it_be_options && kind != :let_it_be
+            raise ArgumentError, "`let_it_be_options` must be used with `let_it_be` kind"
+          end
+
+          @context = context
+          @kind = kind
+          @name = name
+          @items = items
+          @let_it_be_options = let_it_be_options
+        end
+
+        # Create a new blueprint, and create a set of objects (with <code>build</code> build strategy) from it.
+        # @yield Write Blueprint DSL code here
+        # @example
+        #   letbp(:blog, %i[article]).build do
+        #     blog(title: "Daily log") do
+        #       let.article(title: "Article 1")
+        #       article(title: "Article 2")
+        #       article(title: "Article 3")
+        #     end
+        #   end
+        def build(&)
+          let_blueprint(:new, &)
+          let_instance(:build)
+          let_objects
+        end
+
+        # Create a new blueprint, and create a set of objects (with <code>build_stubbed</code> build strategy) from it.
+        # @yield Write Blueprint DSL code here
+        def build_stubbed(&)
+          let_blueprint(:new, &)
+          let_instance(:build_stubbed)
+          let_objects
+        end
+
+        # Create a new blueprint, and create a set of objects (with <code>create</code> build strategy) from it.
+        # @yield Write Blueprint DSL code here
+        def create(&)
+          let_blueprint(:new, &)
+          let_instance(:create)
+          let_objects
+        end
+
+        # Create a set of objects (with <code>build</code> build strategy) from an existing blueprint.
+        # @yield Usual let context for retrieving an existing blueprint
+        # @example
+        #   let(:blog_blueprint) do
+        #     bp.plan do
+        #       blog(title: "Daily log") do
+        #         let.article(title: "Article 1")
+        #         article(title: "Article 2")
+        #         article(title: "Article 3")
+        #       end
+        #     end
+        #   end
+        #   letbp(:blog, %i[article]).build_from { blog_blueprint }
+        def build_from(&)
+          let_blueprint(:from, &)
+          let_instance(:build)
+          let_objects
+        end
+
+        # Create a set of objects (with <code>build_stubbed</code> build strategy) from an existing blueprint.
+        # @yield Usual let context for retrieving an existing blueprint
+        def build_stubbed_from(&)
+          let_blueprint(:from, &)
+          let_instance(:build_stubbed)
+          let_objects
+        end
+
+        # Create a set of objects (with <code>create</code> build strategy) from an existing blueprint.
+        # @yield Usual let context for retrieving an existing blueprint
+        def create_from(&)
+          let_blueprint(:from, &)
+          let_instance(:create)
+          let_objects
+        end
+
+        # Extend <code>super()</code> blueprint.
+        # @yield Write Blueprint DSL code here
+        # @example
+        #   RSpec.describe "something" do
+        #     letbp(:blog, %i[article]).build do
+        #       blog(title: "Daily log") do
+        #         let.article(title: "Article")
+        #       end
+        #     end
+        #
+        #     context "with a comment on the article" do
+        #       letbp(:blog, %i[comment]).inherit do
+        #         on.article do
+        #           let.comment(text: "Comment")
+        #         end
+        #       end
+        #     end
+        #   end
+        def inherit(&)
+          let_blueprint(:inherit, &)
+          # We don't need `let_instance` here because it's already defined in the parent context
+          let_objects
+        end
+
+        private
+
+        def blueprint_name = :"_letbp_#{@name}_blueprint"
+        def instance_name = :"_letbp_#{@name}_instance"
+
+        def let(var, &)
+          case @kind
+          when :lazy
+            @context.let(var, &)
+          when :eager
+            @context.let!(var, &)
+          when :let_it_be
+            @context.let_it_be(var, **@let_it_be_options, &)
+          end
+        end
+
+        # @param source [:new, :from, :inherit]
+        def let_blueprint(source, &)
+          case source
+          when :new
+            let(blueprint_name) { ::FactoryBot::Blueprint.plan(ext: self, &) }
+          when :from
+            let(blueprint_name, &)
+          when :inherit
+            raise ArgumentError, "#inherit does not work with `letbp_it_be`" if @kind == :let_it_be
+
+            let(blueprint_name) { ::FactoryBot::Blueprint.plan(super(), ext: self, &) }
+          end
+        end
+
+        # @param build_strategy [:build, :build_stubbed, :create]
+        def let_instance(build_strategy)
+          blueprint_name = self.blueprint_name
+          let(instance_name) { ::FactoryBot::Blueprint.instantiate(build_strategy, __send__(blueprint_name)) }
+        end
+
+        def let_objects
+          instance_name = self.instance_name
+
+          let(@name) { __send__(instance_name)[::Factrey::Blueprint::Node::RESULT_NAME] }
+          @items.each { |item| let(item) { __send__(instance_name)[item] } }
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module FactoryBot
   module Blueprint
     module RSpec
-      VERSION = "0.4.0"
+      VERSION = "0.5.0"
     end
   end
 end

data/lib/factory_bot/blueprint/rspec.rb

@@ -2,4 +2,5 @@
 
 require "factory_bot/blueprint"
 require_relative "rspec/version"
+require_relative "rspec/letbp"
 require_relative "rspec/driver"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: factory_bot-blueprint-rspec
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - yubrot
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-13 00:00:00.000000000 Z
+date: 2024-11-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: factory_bot-blueprint
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: 0.5.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: 0.5.0
 - !ruby/object:Gem::Dependency
   name: rspec-core
   requirement: !ruby/object:Gem::Requirement
@@ -49,6 +49,7 @@ files:
 - README.md
 - lib/factory_bot/blueprint/rspec.rb
 - lib/factory_bot/blueprint/rspec/driver.rb
+- lib/factory_bot/blueprint/rspec/letbp.rb
 - lib/factory_bot/blueprint/rspec/version.rb
 homepage: https://github.com/yubrot/factory_bot-blueprint
 licenses:
@@ -66,14 +67,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: FactoryBot::Blueprint integration for RSpec