rspock 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 856b42367a5e7d9bfcffe5e725f24d33c3792176aa927516a517c4c9118d5be7
-  data.tar.gz: '09aa051168f43190aba2b5ed346e141bb6f8597ff3e42a51681a2de366b96f16'
+  metadata.gz: 40f95078010f80a7874ef4cd38a286629ea2fa1c6355dd2f8b15f8b1b8f050f6
+  data.tar.gz: 7b78667195ce9c030bf0f32de406f65ae463d69be810838aff25b525b0f2e755
 SHA512:
-  metadata.gz: 296fdd0f0318aa99b4a4269b99679c35932e7dfb80ae2aecc2f879f996fee63d1fa4f35d82b3e09efe4b8b6a168aa1d3e8dba1880334467c2a595318159e8c69
-  data.tar.gz: 00a357b4915ccf4354e38dabc2f415370dbb6cb2cb9c485776f4252c300239f5285d20c6f262854f269f8d8abf2e8499e5570b7d36ad5036214d4c4259afb28b
+  metadata.gz: 301ca7b7cf35271b5b28d79acfdf135d11fd35979e4c5a3497e5d16c8bc314fa8dc9cac12053070577f93373b83ae3c5dc3321f38f57b508ca51ebf8c97f53bc
+  data.tar.gz: 98777999b2c5f4f028c66fe6e4fc109cbcce0bd024ea6729cd8d0fbe1420e512d706c5482d99c5f09f0a580887ed82ed5f19d2962d258628f7aee94c05f3d1e4

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.2.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 `>>`
 * (Planned) BDD-style custom reporter that outputs information from Code Blocks
 * (Planned) Capture all Then block violations
 
@@ -306,11 +306,12 @@ 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.
 
 ```
-1 * receiver.message('hello')
-|   |          |       |
+1 * receiver.message('hello') >> "result"
+|   |          |       |         |
+|   |          |       |         return value (optional)
 |   |          |       argument(s)
 |   |          message
 |   receiver
@@ -357,6 +358,58 @@ 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.
+
 ## Debugging
 
 ### Pry
@@ -448,7 +501,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 +509,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/interaction_transformation.rb

@@ -15,8 +15,10 @@ module RSpock
 
       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)
 
-        node.type == :send && node.children[1] == :*
+        false
       end
 
       private
@@ -45,6 +47,8 @@ module RSpock
           raise ArgumentError, "Unrecognized times constraint in interaction: #{@times_node&.loc&.expression || "?"}"
         end
 
+        result = chain_call(result, :returns, @return_value_node) if @return_value_node
+
         result
       end
 
@@ -88,11 +92,24 @@ module RSpock
         result
       end
 
+      def return_value_node?(node)
+        node.type == :send && node.children[1] == :>> && interaction_node?(node.children[0])
+      end
+
       def any_matcher_node?(node)
         node.type == :send && node.children[0].nil? && node.children[1] == :_
       end
 
       def parse_node(node)
+        # Unwrap `interaction >> return_value` into the underlying interaction,
+        # assigned to @return_value_node for transform_node to chain .returns().
+        if return_value_node?(node)
+          @return_value_node = node.children[2]
+          node = node.children[0]
+        else
+          @return_value_node = nil
+        end
+
         parse_lhs(node.children[0])
         parse_rhs(node.children[2])
       end

data/lib/rspock/backtrace_filter.rb

@@ -33,7 +33,7 @@ module RSpock
       return location unless source_map
 
       line_number = source_map.line(lineno) || '?'
-      location.gsub(/#{ASTTransform.output_path}\/([\S]+):(\d+)/, "\\1:#{line_number}")
+      location.sub("#{file_path}:#{lineno}", "#{source_map.source_file_path}:#{line_number}")
     end
 
     private

data/lib/rspock/version.rb

@@ -1,3 +1,3 @@
 module RSpock
-  VERSION = "2.1.0"
+  VERSION = "2.2.0"
 end

data/rspock.gemspec

@@ -26,6 +26,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "minitest", "~> 5.14"
   spec.add_development_dependency "minitest-reporters", "~> 1.4"
   spec.add_development_dependency "pry", ">= 0.14"
+  spec.add_development_dependency "pry-byebug", "~> 3.9"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "simplecov", "~> 0.22"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspock
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Jean-Philippe Duchesne
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-21 00:00:00.000000000 Z
+date: 2026-02-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -171,6 +185,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/CLAUDE.md"
+- ".cursor/rules/base.mdc"
+- ".cursor/rules/best-practices.mdc"
 - ".github/workflows/ci.yml"
 - ".github/workflows/release.yml"
 - ".gitignore"