ruby_llm-test 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6320355012e11036b37b8a13d6a7bd5782e573a1e7ab1a94601d67836e3e02ab
+  data.tar.gz: 566e774f1e9ac7fb636b5f05eeef52fc27565eb2d9fb9997f0f14b6630ba67c0
+SHA512:
+  metadata.gz: 4a5b97108962cfa24230b4733e4357f2042ed6240dbe934d466567c102aadfee07224d0762b0105121c4092879d8ae5ef8f98ef7e76146170e366057aa09f15d
+  data.tar.gz: e30334a2adf81c0faeb482daf76a96dda06efa7664f567c2778a6aafd1e02c934686f33f9302f6533eae184f390c7f7bba7355e5b0fd09dc2408ff79276282eb

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Todd Kummer
+
+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,115 @@
+# RubyLLM::Test
+
+This gem provides testing utilities for RubyLLM, a Ruby library for working with large language models (LLMs). It enables calls to LLM's to be stubbed so that the surrounding application logic can be tested without making actual calls to the LLM. This is particularly useful for testing code that interacts with LLMs, as it allows developers to simulate responses from the LLM without incurring the cost, latency, or randomness of real API calls.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ruby_llm-test'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ruby_llm-test
+
+## Usage
+
+Add the following lines to your `spec/spec_helper.rb` or `test/test_helper.rb`:
+
+```ruby
+require 'ruby_llm/test'
+
+RubyLLM::Models.singleton_class.prepend(RubyLLM::Test::ResolveWithTestProvider)
+```
+
+Then, in your tests, you can use the `stub_response` method to stub responses from the LLM. For example:
+
+```ruby
+it 'returns a stubbed response' do
+  RubyLLM::Test.stub_response('Hello, world!')
+
+  response = MyLLMClient.call('Hello?')
+  expect(response).to eq('Hello, world!')
+end
+```
+
+If you make multiple calls to the LLM, you can call `stub_response` more than once or use method `stub_responses` to stub multiple responses at once. For example:
+
+```ruby
+it 'returns multiple stubbed responses' do
+  RubyLLM::Test.stub_responses('Hello, world!', 'How are you?')
+  response1 = MyLLMClient.call('Hello?')
+  response2 = MyLLMClient.call('How are you?')
+
+  expect(response1).to eq('Hello, world!')
+  expect(response2).to eq('How are you?')
+end
+```
+
+### Stubbing with a Message
+
+If you stub with a string, it will be wrapped in a `RubyLLM::Message` with the role of `:assistant`. If you want more control over the message, you can stub with a `RubyLLM::Message` directly. For example:
+
+```ruby
+it 'returns a stubbed message' do
+  message = RubyLLM::Message.new(role: :assistant, content: 'Hello, world!')
+  RubyLLM::Test.stub_response(message)
+
+  response = MyLLMClient.call('Hello?')
+  expect(response).to eq(message)
+end
+```
+
+### Stubbing with a Hash Returns JSON
+
+If you stub with a hash, it will be converted to a `RubyLLM::Message` with the content set to the JSON representation of the hash. For example:
+
+```ruby
+it 'returns a stubbed JSON message' do
+  hash = { key: 'value' }
+  RubyLLM::Test.stub_response(hash)
+
+  response = MyLLMClient.call('Hello?')
+  expect(response.content).to eq(hash.to_json)
+end
+```
+
+### Resetting Stubs
+
+Make sure to reset stubs after each test to avoid interference before or between tests.
+
+```ruby
+RubyLLM::Test.reset
+```
+
+### Stubbing with a Block
+
+You can also stub responses in a block, which handles the setup and teardown of stubs automatically. For example:
+
+```ruby
+
+RubyLLM::Test.with_responses('Hello, world!') do
+  response = MyLLMClient.call('Hello?')
+  expect(response).to eq('Hello, world!')
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/RockSolt/ruby_llm-test.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/ruby_llm/test/complete_parameters.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Test
+    # This class encapsulates all the parameters that are passed to the `complete` method of the `Test` class. It
+    # serves as a structured way to manage and access these parameters throughout the testing process.
+    class CompleteParameters
+      attr_reader :messages, :tools, :temperature, :model, :params, :headers, :schema, :thinking, :tool_prefs, :block
+
+      def initialize(messages:, tools:, temperature:, model:, params:, # rubocop:disable Metrics/ParameterLists
+                     headers:, schema:, thinking:, tool_prefs:, block:)
+        @messages = messages
+        @tools = tools
+        @temperature = temperature
+        @model = model
+        @params = params
+        @headers = headers
+        @schema = schema
+        @thinking = thinking
+        @tool_prefs = tool_prefs
+        @block = block
+      end
+
+      def block_received?
+        !@block.nil?
+      end
+    end
+  end
+end

data/lib/ruby_llm/test/errors/no_response_provided_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Test
+    module Errors
+      # # No Response Provided Error
+      #
+      # If the test setup does not provide a response for a test chat completion,
+      # this error is raised to indicate that the test is incomplete. The final chat message,
+      # generated by the `ask` method, is included in the error message for context.
+      class NoResponseProvidedError < StandardError
+        attr_reader :messages
+
+        def initialize(messages)
+          @messages = messages
+          super("No test response provided for the following request:\n#{messages.last&.content}")
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/test/resolve_with_test_provider.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Test
+    # Extend the RubyLLM::Models class to inject the Test Provider in test environments.
+    #
+    # Add the following to your test setup (e.g. in spec_helper.rb or test_helper.rb):
+    #
+    # require_relative "ruby_llm/test/resolve_with_test_provider"
+    #
+    # RubyLLM::Models.singleton_class.prepend(RubyLLM::Test::ResolveWithTestProvider)
+    module ResolveWithTestProvider
+      def resolve(...)
+        model, provider_instance = super
+        [ model, Test::TestProvider.new(provider_instance, RubyLLM::Test) ]
+      end
+    end
+  end
+end

data/lib/ruby_llm/test/test_provider.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Test
+    # This class serves as a test double for the provider used in the `RubyLLM::Test` class. It captures all calls to
+    #  the `complete` method, allowing tests to assert that the correct parameters were passed and to simulate
+    #  responses from the provider.
+    class TestProvider < SimpleDelegator
+      extend Forwardable
+
+      attr_reader :complete_calls
+
+      def_delegators :last_call, :messages, :tools, :temperature, :model, :params, :headers, :schema, :thinking,
+                     :tool_prefs, :block_received?
+
+      def initialize(provider, test_harness = RubyLLM::Test)
+        super(provider)
+        @test_harness = test_harness
+        @complete_calls = []
+      end
+
+      def complete(messages, tools:, temperature:, model:, params: {}, # rubocop:disable Metrics/ParameterLists
+                   headers: {}, schema: nil, thinking: nil, tool_prefs: nil, &block)
+        @complete_calls << CompleteParameters.new(messages:, tools:, temperature:, model:, params:, headers:, schema:,
+                                                  thinking:, tool_prefs:, block:)
+        raise Errors::NoResponseProvidedError, messages if @test_harness.responses_empty?
+
+        response = @test_harness.next_response
+        return response if response.is_a?(Message)
+
+        Message.new(
+          role: :assistant,
+          content: response.is_a?(Hash) ? response.to_json : response
+        )
+      end
+
+      def last_call
+        @complete_calls.last
+      end
+    end
+  end
+end

data/lib/ruby_llm/test/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Test
+    VERSION = "0.1.0"
+  end
+end

data/lib/ruby_llm/test.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem_extension(RubyLLM)
+loader.setup
+
+module RubyLLM
+  # The Test module provides a simple way to stub responses from an LLM for testing purposes. You can use it to set up
+  #  predetermined responses that your tests can rely on, allowing you to test your code's behavior without making
+  #  actual calls to an LLM.
+  module Test
+    class << self
+      def reset
+        @responses = nil
+      end
+
+      # Pass in a RubyLLM::Message to have full control; strings and hashes will be wrapped in a message
+      def stub_response(body)
+        responses << body
+      end
+
+      def stub_responses(*bodies)
+        responses.concat(bodies)
+      end
+
+      def with_responses(*bodies)
+        previous_responses = responses.dup
+        @responses = []
+        stub_responses(*bodies)
+        yield
+      ensure
+        @responses = previous_responses
+      end
+
+      def next_response
+        responses.shift
+      end
+
+      def responses_empty?
+        responses.empty?
+      end
+
+      def responses
+        @responses ||= []
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-test
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Todd Kummer
+bindir: bin
+cert_chain: []
+date: 2026-04-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.14.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.14.0
+description: Provides a RubyLLM::Provider that allows you to stub responses for testing
+  purposes. You can stub individual responses or a sequence of responses, and you
+  can also temporarily stub responses within a block.
+email:
+- todd@rockridgesolutions.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/ruby_llm/test.rb
+- lib/ruby_llm/test/complete_parameters.rb
+- lib/ruby_llm/test/errors/no_response_provided_error.rb
+- lib/ruby_llm/test/resolve_with_test_provider.rb
+- lib/ruby_llm/test/test_provider.rb
+- lib/ruby_llm/test/version.rb
+homepage: https://github.com/RockSolt/ruby_llm-test
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Test application logic by stubbing responses from a RubyLLM::Provider.
+test_files: []