rspock 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40f95078010f80a7874ef4cd38a286629ea2fa1c6355dd2f8b15f8b1b8f050f6
-  data.tar.gz: 7b78667195ce9c030bf0f32de406f65ae463d69be810838aff25b525b0f2e755
+  metadata.gz: 0fd03a245608aa5e7e8923fdee5a0cf31c3b553a7e58bbee8a8b57e04c3f8035
+  data.tar.gz: 55a5d98ae2855d5e1e1dfde07adba69d7b21c63eed99b3cc1bc951a7d74d62e6
 SHA512:
-  metadata.gz: 301ca7b7cf35271b5b28d79acfdf135d11fd35979e4c5a3497e5d16c8bc314fa8dc9cac12053070577f93373b83ae3c5dc3321f38f57b508ca51ebf8c97f53bc
-  data.tar.gz: 98777999b2c5f4f028c66fe6e4fc109cbcce0bd024ea6729cd8d0fbe1420e512d706c5482d99c5f09f0a580887ed82ed5f19d2962d258628f7aee94c05f3d1e4
+  metadata.gz: 10ae8fd089fa44e920f6b0f781e6099971aa2474c2aacc6a355c1c3e1a7952bbf779a8170125d66be1c1eb6ea9f21d731ceefb62490e212b4a5c3cd04b615b48
+  data.tar.gz: 848890cb9cb6cf79ef15f7c6d607b8a480f07ce500e627ab1bb246c1ed40d6b18f5f6e10ef28a3aba41cd9197b4276d8e6ce3787089740eaea69ae24a20c0e54

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rspock (2.2.0)
+    rspock (2.3.0)
       ast_transform (~> 2.0)
       minitest (~> 5.0)
       mocha (>= 1.0)

data/README.md

@@ -17,7 +17,7 @@ Note: RSpock is heavily inspired by Spock for the Groovy programming language.
 * BDD-style code blocks: Given, When, Then, Expect, Cleanup, Where
 * Data-driven testing with incredibly expressive table-based Where blocks
 * Expressive assertions: Use familiar comparison operators `==` and `!=` for assertions!
-* [Interaction-based testing](#mocking-with-interactions), i.e. `1 * object.receive("message")` in Then blocks, with optional [return value stubbing](#stubbing-return-values) via `>>`
+* [Interaction-based testing](#mocking-with-interactions), i.e. `1 * object.receive("message")` in Then blocks, with optional [return value stubbing](#stubbing-return-values) via `>>` and [block forwarding verification](#block-forwarding-verification) via `&block`
 * (Planned) BDD-style custom reporter that outputs information from Code Blocks
 * (Planned) Capture all Then block violations
 
@@ -306,13 +306,14 @@ test "#publish sends a message to all subscribers" do
 end
 ```
 
-The above ___Then___ block contains 2 interactions, each of which has 4 parts: the _cardinality_, the _receiver_, the _message_ and its _arguments_. Optionally, a _return value_ can be specified using the `>>` operator.
+The above ___Then___ block contains 2 interactions, each of which has 4 parts: the _cardinality_, the _receiver_, the _message_ and its _arguments_. Optionally, a _return value_ can be specified using the `>>` operator, and _block forwarding_ can be verified using the `&` operator.
 
 ```
-1 * receiver.message('hello') >> "result"
-|   |          |       |         |
-|   |          |       |         return value (optional)
-|   |          |       argument(s)
+1 * receiver.message('hello', &blk) >> "result"
+|   |          |       |       |       |
+|   |          |       |       |       return value (optional)
+|   |          |       |       block forwarding (optional)
+|   |          |       argument(s) (optional)
 |   |          message
 |   receiver
 cardinality
@@ -320,6 +321,16 @@ cardinality
 
 Note: Interactions are supported in the ___Then___ block only.
 
+#### Execution Order
+
+Although interactions are _declared_ in the ___Then___ block, they are effectively active _before_ the ___When___ block executes. RSpock ensures the following order:
+
+1. **Before the stimulus** — mock expectations and block captures are installed on the receiver, so they are ready to intercept calls.
+2. **Stimulus** — the ___When___ block runs.
+3. **After the stimulus** — assertions such as block identity checks run alongside other ___Then___ assertions. Cardinality is verified at teardown.
+
+Simply declare _what_ should happen in a natural order — RSpock handles the _when_.
+
 #### Cardinality
 
 The cardinality of an interaction describes how often a method is expected to be called. It can be a fixed number of times, or a range.
@@ -410,6 +421,25 @@ _ * cache.fetch("key") >> expensive_result   # a variable
 
 **Note**: Without `>>`, an interaction sets up an expectation only (the method will return `nil` by default). Use `>>` when the code under test depends on the return value.
 
+#### Block Forwarding Verification
+
+When the code under test forwards a block (or proc) to a collaborator, you may want to verify that the _exact_ block was passed through. RSpock supports this with the `&` operator in interactions, performing an identity check on the block reference.
+
+```ruby
+test "#frame forwards the block to CLI::UI.frame" do
+  Given "a block to forward"
+  my_block = proc { puts "hello" }
+
+  When "we call frame with that block"
+  @ui.frame("Build", &my_block)
+
+  Then "the block was forwarded to cli_ui.frame"
+  1 * @cli_ui.frame("Build", to: @out, &my_block)
+end
+```
+
+**Note**: Inline blocks (`do...end` or `{ }`) are not supported in interactions and will raise an `InteractionError`. Use a named proc or lambda variable with `&` instead, since block forwarding verification requires a reference to compare against.
+
 ## Debugging
 
 ### Pry

data/lib/rspock/ast/comparison_to_assertion_transformation.rb

@@ -22,7 +22,7 @@ module RSpock
       private
 
       def ignored_method_call_node?(node)
-        return false unless node.is_a?(Parser::AST::Node)
+        return false unless node.is_a?(::Parser::AST::Node)
 
         !@method_call_transformation.method_call_node?(node.children[0]) &&
           !@method_call_transformation.method_call_node?(node.children[2])

data/lib/rspock/ast/interaction_to_block_identity_assertion_transformation.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+require 'ast_transform/abstract_transformation'
+require 'rspock/ast/node'
+
+module RSpock
+  module AST
+    # Transforms an :rspock_interaction node into an assert_same assertion
+    # when a block_pass (&var) is present.
+    #
+    # Returns the node unchanged (passthrough) when no block_pass is present.
+    class InteractionToBlockIdentityAssertionTransformation < ASTTransform::AbstractTransformation
+      def initialize(index = 0)
+        @index = index
+      end
+
+      def run(interaction)
+        return interaction unless interaction.type == :rspock_interaction
+        return interaction unless interaction.block_pass
+
+        capture_var = :"__rspock_blk_#{@index}"
+        block_var = interaction.block_pass.children[0]
+
+        s(:send, nil, :assert_same,
+          block_var,
+          s(:send, s(:lvar, capture_var), :call)
+        )
+      end
+    end
+  end
+end

data/lib/rspock/ast/interaction_to_mocha_mock_transformation.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+require 'ast_transform/abstract_transformation'
+require 'rspock/ast/node'
+
+module RSpock
+  module AST
+    # Transforms an :rspock_interaction node into Mocha mock setup code.
+    #
+    # Input:  s(:rspock_interaction, cardinality, receiver, sym, args, return_value, block_pass)
+    # Output: receiver.expects(:message).with(*args).times(n).returns(value)
+    #
+    # When block_pass is present, wraps the expects chain with a BlockCapture.capture call.
+    class InteractionToMochaMockTransformation < ASTTransform::AbstractTransformation
+      def initialize(index = 0)
+        @index = index
+      end
+
+      def run(interaction)
+        return interaction unless interaction.type == :rspock_interaction
+
+        result = chain_call(interaction.receiver, :expects, s(:sym, interaction.message))
+        result = chain_call(result, :with, *interaction.args.children) if interaction.args
+        result = build_cardinality(result, interaction.cardinality)
+        result = chain_call(result, :returns, interaction.return_value) if interaction.return_value
+
+        if interaction.block_pass
+          build_block_capture_setup(result, interaction.receiver, interaction.message)
+        else
+          result
+        end
+      end
+
+      private
+
+      def build_cardinality(result, cardinality)
+        if any_matcher_node?(cardinality)
+          chain_call(result, :at_least, s(:int, 0))
+        elsif [:send, :lvar, :int].include?(cardinality.type)
+          chain_call(result, :times, cardinality)
+        elsif cardinality.type == :begin && cardinality.children[0]&.type == :irange
+          min_node, max_node = cardinality.children[0].children
+          build_irange(result, min_node, max_node)
+        elsif cardinality.type == :begin && cardinality.children[0]&.type == :erange
+          min_node, max_node = cardinality.children[0].children
+          max_node = chain_call(max_node, :-, s(:int, 1))
+          build_erange(result, min_node, max_node)
+        else
+          raise ArgumentError, "Unrecognized cardinality in :rspock_interaction: #{cardinality.type}"
+        end
+      end
+
+      def build_irange(result, min_node, max_node)
+        if any_matcher_node?(min_node) && any_matcher_node?(max_node)
+          chain_call(result, :at_least, s(:int, 0))
+        elsif !any_matcher_node?(min_node) && any_matcher_node?(max_node)
+          chain_call(result, :at_least, min_node)
+        elsif any_matcher_node?(min_node) && !any_matcher_node?(max_node)
+          result = chain_call(result, :at_least, s(:int, 0))
+          chain_call(result, :at_most, max_node)
+        else
+          result = chain_call(result, :at_least, min_node)
+          chain_call(result, :at_most, max_node)
+        end
+      end
+
+      def build_erange(result, min_node, max_node)
+        if any_matcher_node?(min_node) && any_matcher_node?(max_node.children[0])
+          chain_call(result, :at_least, s(:int, 0))
+        elsif !any_matcher_node?(min_node) && any_matcher_node?(max_node.children[0])
+          chain_call(result, :at_least, min_node)
+        elsif any_matcher_node?(min_node) && !any_matcher_node?(max_node.children[0])
+          result = chain_call(result, :at_least, s(:int, 0))
+          chain_call(result, :at_most, max_node)
+        else
+          result = chain_call(result, :at_least, min_node)
+          chain_call(result, :at_most, max_node)
+        end
+      end
+
+      def build_block_capture_setup(expects_node, receiver, message)
+        capture_var = :"__rspock_blk_#{@index}"
+
+        capture_call = s(:lvasgn, capture_var,
+          s(:send,
+            s(:const, s(:const, s(:const, nil, :RSpock), :Helpers), :BlockCapture),
+            :capture,
+            receiver,
+            s(:sym, message)
+          )
+        )
+
+        s(:begin, expects_node, capture_call)
+      end
+
+      def chain_call(receiver_node, method_name, *arg_nodes)
+        s(:send, receiver_node, method_name, *arg_nodes)
+      end
+
+      def any_matcher_node?(node)
+        node.type == :send && node.children[0].nil? && node.children[1] == :_
+      end
+    end
+  end
+end

data/lib/rspock/ast/node.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+require 'ast_transform/transformation_helper'
+
+module RSpock
+  module AST
+    class Node < ::Parser::AST::Node
+      REGISTRY = {}
+
+      def self.register(type)
+        REGISTRY[type] = self
+      end
+
+      def self.build(type, *children)
+        klass = REGISTRY[type] || self
+        klass.new(type, children)
+      end
+    end
+
+    class TestNode < Node
+      register :rspock_test
+
+      def def_node   = children[0]
+      def body_node  = children[1]
+      def where_node = children[2]
+    end
+
+    class BodyNode < Node
+      register :rspock_body
+    end
+
+    class DefNode < Node
+      register :rspock_def
+
+      def method_call = children[0]
+      def args        = children[1]
+    end
+
+    class GivenNode < Node
+      register :rspock_given
+    end
+
+    class WhenNode < Node
+      register :rspock_when
+    end
+
+    class ThenNode < Node
+      register :rspock_then
+    end
+
+    class ExpectNode < Node
+      register :rspock_expect
+    end
+
+    class CleanupNode < Node
+      register :rspock_cleanup
+    end
+
+    class WhereNode < Node
+      register :rspock_where
+
+      def header
+        header_node = children.find { |n| n.type == :rspock_where_header }
+        header_node.children.map { |sym_node| sym_node.children[0] }
+      end
+
+      def data_rows
+        children
+          .select { |n| n.type == :array }
+          .map(&:children)
+      end
+    end
+
+    class InteractionNode < Node
+      register :rspock_interaction
+
+      def cardinality  = children[0]
+      def receiver     = children[1]
+      def message_sym  = children[2]
+      def message      = message_sym.children[0]
+      def args         = children[3]
+      def return_value = children[4]
+      def block_pass   = children[5]
+    end
+
+    module NodeBuilder
+      include ASTTransform::TransformationHelper
+
+      def s(type, *children)
+        if type.to_s.start_with?('rspock_')
+          Node.build(type, *children)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/rspock/ast/parser/block.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+require 'rspock/ast/node'
+
+module RSpock
+  module AST
+    module Parser
+      class BlockError < StandardError; end
+
+      class Block
+        include RSpock::AST::NodeBuilder
+
+        # Constructs a new Block.
+        #
+        # @param type [Symbol] The Block type.
+        # @param node [Parser::AST::Node] The node associated to this Block.
+        def initialize(type, node)
+          @type = type
+          @node = node
+          @children = []
+        end
+
+        attr_reader :type, :node
+
+        # Adds the given +child_node+ to this Block.
+        #
+        # @param child_node [Parser::AST::Node] The node to be added.
+        def <<(child_node)
+          @children << child_node
+        end
+
+        # Retrieves the Parser::Source::Range for this Block.
+        #
+        # @return [Parser::Source::Range] The range.
+        def range
+          node&.loc&.expression || "?"
+        end
+
+        # Whether this block can be the first block in a test method.
+        def can_start?
+          false
+        end
+
+        # Whether this block can be the last block in a test method.
+        def can_end?
+          false
+        end
+
+        # Retrieves the valid successors for this Block.
+        #
+        # @return [Array<Symbol>] This Block's successors.
+        def successors
+          @successors ||= [].freeze
+        end
+
+        # Retrieves the duped array of children AST nodes for this Block.
+        #
+        # @return [Array<Parser::AST::Node>] The children nodes.
+        def children
+          @children.dup
+        end
+
+        # Converts this Block into an RSpock node.
+        #
+        # @return [Parser::AST::Node] A node with type :rspock_<block_type>.
+        def to_rspock_node
+          rspock_type = :"rspock_#{type.downcase}"
+          s(rspock_type, *@children)
+        end
+
+        # Checks whether or not the given +block+ is a valid successor for this Block.
+        #
+        # @param block [Block] The candidate successor.
+        #
+        # @return [Boolean] True if the given block is a valid successor, false otherwise.
+        def valid_successor?(block)
+          successors.include?(block.type)
+        end
+
+        # Retrieves the error message for succession errors.
+        #
+        # @return [String] The error message.
+        def succession_error_msg
+          "Block #{type} @ #{range} must be followed by one of these Blocks: #{successors}"
+        end
+      end
+    end
+  end
+end

data/lib/rspock/ast/parser/cleanup_block.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+require 'rspock/ast/parser/block'
+
+module RSpock
+  module AST
+    module Parser
+      class CleanupBlock < Block
+        def initialize(node)
+          super(:Cleanup, node)
+        end
+
+        def can_end?
+          true
+        end
+
+        def successors
+          @successors ||= [:Where].freeze
+        end
+      end
+    end
+  end
+end

data/lib/rspock/ast/parser/expect_block.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+require 'rspock/ast/parser/block'
+
+module RSpock
+  module AST
+    module Parser
+      class ExpectBlock < Block
+        def initialize(node)
+          super(:Expect, node)
+        end
+
+        def can_start?
+          true
+        end
+
+        def can_end?
+          true
+        end
+
+        def successors
+          @successors ||= [:Cleanup, :Where].freeze
+        end
+      end
+    end
+  end
+end

data/lib/rspock/ast/parser/given_block.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+require 'rspock/ast/parser/block'
+
+module RSpock
+  module AST
+    module Parser
+      class GivenBlock < Block
+        def initialize(node)
+          super(:Given, node)
+        end
+
+        def can_start?
+          true
+        end
+
+        def successors
+          @successors ||= [:When, :Expect].freeze
+        end
+      end
+    end
+  end
+end

data/lib/rspock/ast/parser/interaction_parser.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+require 'rspock/ast/node'
+
+module RSpock
+  module AST
+    module Parser
+      # Parses raw Ruby AST interaction nodes into structured :rspock_interaction nodes.
+      #
+      # Input:  1 * receiver.message("arg", &blk) >> "result"
+      # Output: s(:rspock_interaction, cardinality, receiver, sym, args, return_value, block_pass)
+      #
+      # :rspock_interaction children:
+      #   [0] cardinality  - e.g. s(:int, 1), s(:begin, s(:irange, ...)), s(:send, nil, :_)
+      #   [1] receiver     - e.g. s(:send, nil, :subscriber)
+      #   [2] message      - e.g. s(:sym, :receive)
+      #   [3] args         - nil if no args, s(:array, *arg_nodes) otherwise
+      #   [4] return_value - nil if no >>, otherwise the value node
+      #   [5] block_pass   - nil if no &, otherwise s(:block_pass, ...)
+      class InteractionParser
+        include RSpock::AST::NodeBuilder
+
+        class InteractionError < RuntimeError; end
+
+        ALLOWED_CARDINALITY_NODES = [:send, :lvar, :int].freeze
+
+        def interaction_node?(node)
+          return false if node.nil?
+          return true if node.type == :send && node.children[1] == :*
+          return true if return_value_node?(node)
+
+          false
+        end
+
+        def parse(node)
+          return node unless interaction_node?(node)
+
+          if return_value_node?(node)
+            return_value = node.children[2]
+            node = node.children[0]
+          end
+
+          cardinality = node.children[0]
+          validate_cardinality(cardinality)
+
+          rhs = node.children[2]
+          receiver, message, args, block_pass = parse_rhs(rhs)
+
+          s(:rspock_interaction,
+            cardinality,
+            receiver,
+            s(:sym, message),
+            args,
+            return_value,
+            block_pass
+          )
+        end
+
+        private
+
+        def return_value_node?(node)
+          node.type == :send && node.children[1] == :>> && interaction_node?(node.children[0])
+        end
+
+        def validate_cardinality(node)
+          case node.type
+          when *ALLOWED_CARDINALITY_NODES
+            # OK
+          when :begin
+            if node.children.count > 1
+              raise_cardinality_error(node,
+                msg_prefix: "Left-hand side of ",
+                msg_suffix: " or a range in parentheses")
+            end
+            case node.children[0].type
+            when :irange, :erange
+              unless ALLOWED_CARDINALITY_NODES.include?(node.children[0].children[0].type)
+                raise_cardinality_error(node.children[0].children[0], msg_prefix: "Minimum range of ")
+              end
+              unless ALLOWED_CARDINALITY_NODES.include?(node.children[0].children[1].type)
+                raise_cardinality_error(node.children[0].children[1], msg_prefix: "Maximum range of ")
+              end
+            else
+              raise_cardinality_error(node,
+                msg_prefix: "Left-hand side of ",
+                msg_suffix: " or a range in parentheses")
+            end
+          else
+            raise_cardinality_error(node,
+              msg_prefix: "Left-hand side of ",
+              msg_suffix: " or a range in parentheses")
+          end
+        end
+
+        def parse_rhs(node)
+          if node.type == :block
+            raise InteractionError, "Inline blocks (do...end / { }) are not supported in interactions @ #{range(node)}. " \
+              "Use &var for block forwarding verification, or << for method body override (future)."
+          end
+
+          if node.type != :send
+            raise InteractionError, "Right-hand side of Interaction @ #{range(node)} must be a :send node."
+          end
+
+          receiver, message, *arg_nodes = node.children
+
+          if receiver.nil?
+            raise InteractionError, "Right-hand side of Interaction @ #{range(node)} must have a receiver."
+          end
+
+          block_pass = arg_nodes.find { |n| n.type == :block_pass }
+          if block_pass
+            arg_nodes = arg_nodes.reject { |n| n.equal?(block_pass) }
+          end
+
+          args = arg_nodes.empty? ? nil : s(:array, *arg_nodes)
+
+          [receiver, message, args, block_pass]
+        end
+
+        def range(node)
+          node&.loc&.expression || "?"
+        end
+
+        def raise_cardinality_error(node, msg_prefix: "", msg_suffix: "")
+          raise InteractionError, "#{msg_prefix}Interaction @ #{range(node)} must be one of " \
+            "#{ALLOWED_CARDINALITY_NODES}#{msg_suffix}."
+        end
+      end
+    end
+  end
+end