rspock 2.1.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 856b42367a5e7d9bfcffe5e725f24d33c3792176aa927516a517c4c9118d5be7
-  data.tar.gz: '09aa051168f43190aba2b5ed346e141bb6f8597ff3e42a51681a2de366b96f16'
+  metadata.gz: 0fd03a245608aa5e7e8923fdee5a0cf31c3b553a7e58bbee8a8b57e04c3f8035
+  data.tar.gz: 55a5d98ae2855d5e1e1dfde07adba69d7b21c63eed99b3cc1bc951a7d74d62e6
 SHA512:
-  metadata.gz: 296fdd0f0318aa99b4a4269b99679c35932e7dfb80ae2aecc2f879f996fee63d1fa4f35d82b3e09efe4b8b6a168aa1d3e8dba1880334467c2a595318159e8c69
-  data.tar.gz: 00a357b4915ccf4354e38dabc2f415370dbb6cb2cb9c485776f4252c300239f5285d20c6f262854f269f8d8abf2e8499e5570b7d36ad5036214d4c4259afb28b
+  metadata.gz: 10ae8fd089fa44e920f6b0f781e6099971aa2474c2aacc6a355c1c3e1a7952bbf779a8170125d66be1c1eb6ea9f21d731ceefb62490e212b4a5c3cd04b615b48
+  data.tar.gz: 848890cb9cb6cf79ef15f7c6d607b8a480f07ce500e627ab1bb246c1ed40d6b18f5f6e10ef28a3aba41cd9197b4276d8e6ce3787089740eaea69ae24a20c0e54

data/.claude/CLAUDE.md

@@ -0,0 +1,2 @@
+See @../.cursor/rules/base.mdc for information on your desired behavior.
+See @../.cursor/rules/best-practices.mdc for our best practices (snapshot we own and evolve).

data/.cursor/rules/base.mdc

@@ -0,0 +1,35 @@
+---
+description: Principal Engineer persona and code guidelines (stack-agnostic)
+globs:
+alwaysApply: true
+---
+As a Principal Engineer, the highest ranking engineer at our company, you are tasked with creating clear, readable code. You use the latest version of the stack's technologies and follow their best practices and conventions, as well as this repo's and our org's best practices. Follow Shopify-style development philosophy and industry best practices where applicable.
+
+When responding to questions, follow the Chain of Thought method. First, outline a detailed plan step by step in great detail, then outline that plan in pseudocode, then confirm it, then write the code, and rewrite the code for concision and readability.
+
+You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning; but you always admit when you don't know the answer.
+
+Remember the following important mindset when providing code, in the following order:
+- Adherence to conventions and patterns in the rest of the codebase
+- Simplicity
+- Readability
+- Testability
+- Explicitness
+- Beginner-friendly
+
+Adhere to the following guidelines in your code:
+- Follow the user's requirements carefully and to the letter.
+- Fully implement all requested functionality.
+- Leave no TODOs, FIXMEs, placeholders or missing pieces.
+- Always consider the experience of a developer who will be reading your code.
+- Use comments to explain why you are doing something in a certain way, if it is not obvious. If unsure, leave a comment.
+- Employ descriptive, human-readable variable and function/const names.
+- Prefer writing in a functional style where it fits, producing pure functions that do not cause side effects when practical.
+- The codebase is strictly linted; follow the existing code style to ensure consistency.
+- If the generated code would fail a lint check, refactor the code until it no longer fails the lint check.
+- Search hard to find an existing function or pattern in the codebase where possible.
+- Be sure to reference file names when relevant.
+- Be concise. Minimize any prose other than code.
+- If you think there might not be a correct answer, say so. If you do not know the answer, say so instead of guessing.
+- In tests, always avoid mocking the filesystem. Use real files and directories, in temporary directories if needed.
+- In tests, prefer to have as little shared state between tests as possible. Avoid beforeAll and afterAll.

data/.cursor/rules/best-practices.mdc

@@ -0,0 +1,27 @@
+---
+description: Our best practices (snapshot we own and evolve; often org-wide across repos)
+globs:
+alwaysApply: true
+---
+# Best practices (d3mlabs snapshot)
+
+We own this snapshot and evolve it as the org diverges. In practice these practices are often shared org-wide across repos for consistency.
+
+## Priorities
+
+- **Conventions over configuration**: Follow existing patterns and tooling before introducing new ones.
+- **Clarity and maintainability**: Code should be easy to read and change; prefer explicit over clever.
+- **Testability**: Design so that behavior can be tested with real inputs and minimal mocks.
+- **Explicitness**: Prefer clear, named steps and obvious control flow over brevity that hides intent.
+
+## Code and tests
+
+- No TODOs, FIXMEs, or placeholders in committed code; finish or track elsewhere.
+- In tests: use real files and temporary directories; avoid filesystem mocks.
+- Minimal shared state between tests; avoid beforeAll/afterAll and global fixtures.
+- Strict lint and existing code style; refactor until lint passes.
+- Prefer existing helpers and patterns in the codebase; search before adding new abstractions.
+
+## Further reading
+
+- [Shopify Engineering](https://shopify.engineering) — blog and engineering culture.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rspock (2.1.0)
+    rspock (2.3.0)
       ast_transform (~> 2.0)
       minitest (~> 5.0)
       mocha (>= 1.0)
@@ -13,13 +13,15 @@ GEM
   specs:
     ansi (1.5.0)
     ast (2.4.3)
-    ast_transform (2.1.0)
+    ast_transform (2.1.4)
       parser (>= 3.0)
       prism (>= 1.5)
       unparser (>= 0.6)
     builder (3.3.0)
+    byebug (13.0.0)
+      reline (>= 0.6.0)
     coderay (1.1.3)
-    diff-lcs (1.6.2)
+    diff-lcs (2.0.0)
     docile (1.4.1)
     io-console (0.8.2)
     method_source (1.1.0)
@@ -39,6 +41,9 @@ GEM
       coderay (~> 1.1)
       method_source (~> 1.0)
       reline (>= 0.6.0)
+    pry-byebug (3.12.0)
+      byebug (~> 13.0)
+      pry (>= 0.13, < 0.17)
     racc (1.8.1)
     rake (13.3.1)
     reline (0.6.3)
@@ -51,8 +56,8 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    unparser (0.8.1)
-      diff-lcs (~> 1.6)
+    unparser (0.8.2)
+      diff-lcs (>= 1.6, < 3)
       parser (>= 3.3.0)
       prism (>= 1.5.1)
 
@@ -65,6 +70,7 @@ DEPENDENCIES
   minitest (~> 5.14)
   minitest-reporters (~> 1.4)
   pry (>= 0.14)
+  pry-byebug (~> 3.9)
   rake (~> 13.0)
   rspock!
   simplecov (~> 0.22)

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
+* [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,12 +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_.
+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')
-|   |          |       |
-|   |          |       argument(s)
+1 * receiver.message('hello', &blk) >> "result"
+|   |          |       |       |       |
+|   |          |       |       |       return value (optional)
+|   |          |       |       block forwarding (optional)
+|   |          |       argument(s) (optional)
 |   |          message
 |   receiver
 cardinality
@@ -319,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.
@@ -357,6 +369,77 @@ The arguments of an interaction describe which arguments of the method call are
 1 * subscriber.receive('hello') # an argument that is equal to the String 'hello'
 ```
 
+#### Stubbing Return Values
+
+Interactions can be combined with return value stubbing using the `>>` operator. This is useful when the code under test relies on the return value of a collaborator method.
+
+```ruby
+1 * subscriber.receive("hello") >> "ok"
+```
+
+The `>>` operator is placed at the end of the interaction and specifies the value that the method call will return. This means you can set up expectations _and_ stub return values in a single, expressive statement.
+
+```ruby
+class Service
+  # ...
+
+  def initialize(repository)
+    @repository = repository
+  end
+
+  def foo(param)
+    # ...
+    result = @repository.bar(param)
+    # Do something with +result+ ...
+
+    result
+  end
+end
+
+test "Service#bar" do
+  Given
+  repository = Repository.new
+  service = Service.new(repository)
+
+  When
+  result = service.foo(42)
+
+  Then
+  1 * repository.foo(42) >> { name: "item", status: "active" }
+  result == "active"
+end
+```
+
+The return value can be any expression — a literal, a variable, or a complex object:
+
+```ruby
+1 * repository.find(42) >> "result"          # a String
+1 * repository.all >> [item1, item2]         # an Array
+1 * service.call >> { status: :ok }          # a Hash
+_ * 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
@@ -448,7 +531,7 @@ There are two ways to create a release. Both require that `version.rb` has alrea
 
 ### Via GitHub UI
 
-1. Update `VERSION` in `lib/rspock/version.rb`, commit, open a PR, and merge to main
+1. Update `VERSION` in `lib/rspock/version.rb` and run `bundle install` to regenerate `Gemfile.lock`, commit, open a PR, and merge to main
 2. Go to the repo on GitHub → **Releases** → **Draft a new release**
 3. Enter a new tag (e.g. `v2.0.0`), select `main` as the target branch
 4. Add a title and release notes (GitHub can auto-generate these from merged PRs)
@@ -456,7 +539,7 @@ There are two ways to create a release. Both require that `version.rb` has alrea
 
 ### Via CLI
 
-1. Update `VERSION` in `lib/rspock/version.rb`, commit, open a PR, and merge to main
+1. Update `VERSION` in `lib/rspock/version.rb` and run `bundle install` to regenerate `Gemfile.lock`, commit, open a PR, and merge to main
 2. Tag and push:
    ```
    git checkout main && git pull

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