purizumu 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13e13e8ac2807b2872602bfc6066e18bb4b9c462c3abb09a4d9dc3922ffa93a8
-  data.tar.gz: 68f318bb8f0bfd86d86cf7e2f5490bcf1d47cc9c804ee8edb83d2c8c0f56b501
+  metadata.gz: 72573b19670b458b24a5da4260623d80470ddfc2948e197fc521264aa4825bc4
+  data.tar.gz: 2a06be3b4baea735405a4b37a6f22765507504cb1d049703420424249422852b
 SHA512:
-  metadata.gz: 818aaf90a7292954a157faa2787d17b1c9dfa643a865d23c7375c211d6a2f10a95e5fddf41f2c8e820b96c9abc1b6e98412873e183b96fe89bc9baf5da0154c2
-  data.tar.gz: 4a1784db93876921e7d32ea8f1db7ba9276017ce27f360aa081ce4aff4632f7e07d23f30424d36c7dc3db9489497ee3fda58b994ae7ccebc3e40c2b5473e2637
+  metadata.gz: e2a338946fd43b0e867f29eb6863cda8b4732a3659dff4b698577735d0bf52b367517ce56f62523dd8106134def31634134c32bc5cf6c786c05b84aaab67175e
+  data.tar.gz: b10400ba178ce055773d6c602039ff09be5ff85821645b5e1aa320dde7d473c79fb5a7b81bf0067f4508fc77b3d6b811743cd0b11f1793865cbdcb55d5690d21

data/README.md

@@ -43,7 +43,7 @@ end
 
 Available configuration options:
 
-- `config.engine`: translation engine symbol. Purizumu currently ships with `:xai`.
+- `config.engine`: translation engine symbol. Purizumu currently ships with `:xai` and `:test` (see [Test Mode](#test-mode)).
 - `config.key`: API key for the configured engine.
 - `config.model`: LLM model name.
 - `config.base_url`: API base URL. Defaults to `https://api.x.ai/v1`.
@@ -130,6 +130,65 @@ The expected tool payload is:
 }
 ```
 
+## Test Mode
+
+In a test suite you usually do not want translated attribute reads to hit the configured translation engine's API. Enable test mode and Purizumu will stub translations locally without any network requests:
+
+```ruby
+Purizumu.test_mode!
+```
+
+While test mode is on, `Purizumu.engine` returns a stub engine regardless of the configured engine, and no API key or model is required. By default, the stub returns `"[<locale>] <original content>"`, so `"Prism"` translated to `:jp` becomes `"[jp] Prism"` — deterministic and easy to assert against.
+
+You can also supply a block to control what the stub returns. The block receives the full translation request as keyword arguments (`model_name`, `attribute_name`, `content`, `locale`, `source_locale`):
+
+```ruby
+Purizumu.test_mode! do |content:, locale:, **|
+  "#{content} (#{locale})"
+end
+```
+
+To turn it back off (and clear any custom block):
+
+```ruby
+Purizumu.disable_test_mode!
+```
+
+You can check the current state with `Purizumu.test_mode?`.
+
+### RSpec
+
+Enable it once for the entire run in `spec/spec_helper.rb` (or `rails_helper.rb`):
+
+```ruby
+RSpec.configure do |config|
+  config.before(:suite) do
+    Purizumu.test_mode!
+  end
+end
+```
+
+Or, if you only want it for specific examples, enable it per test:
+
+```ruby
+before { Purizumu.test_mode! }
+after { Purizumu.disable_test_mode! }
+```
+
+Test mode is independent of configuration, so it survives `Purizumu.reset_configuration!` — enabling it in `before(:suite)` keeps it on even if individual tests reset or rebuild the configuration.
+
+### Configuring the Test Engine Directly
+
+If you prefer plain configuration — for example in a Rails `config/environments/test.rb` setup where nothing resets Purizumu's configuration — the stub engine is also available as a regular engine:
+
+```ruby
+Purizumu.configure do |config|
+  config.engine = :test
+end
+```
+
+This behaves like test mode with no block: no network requests, no API key or model required, and the same `"[<locale>] <original content>"` stub output. The difference is that it lives in the configuration, so `Purizumu.reset_configuration!` or a later `Purizumu.configure` will replace it. `Purizumu.test_mode!` still overrides whatever engine is configured.
+
 ## Generator Output
 
 `rails generate purizumu:install` creates a migration for the translation table with:

data/lib/purizumu/engines/test.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Purizumu
+  module Engines
+    # Translation engine used in test mode. It never performs network
+    # requests; it returns a deterministic stub translation, or the result
+    # of the handler given to Purizumu.test_mode!.
+    class Test
+      def initialize(handler: nil)
+        @handler = handler
+      end
+
+      def translate(model_name:, attribute_name:, content:, locale:, source_locale:)
+        if handler
+          handler.call(
+            model_name:,
+            attribute_name:,
+            content:,
+            locale:,
+            source_locale:
+          ).to_s
+        else
+          "[#{locale}] #{content}"
+        end
+      end
+
+      private
+
+      attr_reader :handler
+    end
+  end
+end

data/lib/purizumu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Purizumu
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

data/lib/purizumu.rb

@@ -9,6 +9,7 @@ require 'uri'
 require 'purizumu/version'
 require 'purizumu/errors'
 require 'purizumu/configuration'
+require 'purizumu/engines/test'
 require 'purizumu/engines/xai'
 require 'purizumu/engines/xai/payload_builder'
 require 'purizumu/engines/xai/response_parser'
@@ -32,16 +33,34 @@ module Purizumu
       @configuration = Configuration.new
     end
 
+    def test_mode!(&handler)
+      @test_mode = true
+      @test_handler = handler
+    end
+
+    def test_mode?
+      @test_mode == true
+    end
+
+    def disable_test_mode!
+      @test_mode = false
+      @test_handler = nil
+    end
+
     def translate_attribute(record, attribute_name, locale: I18n.locale)
       Translator.new(record: record, attribute_name: attribute_name, locale: locale).call
     end
 
     def engine
+      return Engines::Test.new(handler: @test_handler) if test_mode?
+
       engine_name = configuration.engine.to_sym
 
       case engine_name
       when :xai
         Engines::Xai.new(configuration: configuration)
+      when :test
+        Engines::Test.new
       else
         raise UnsupportedEngineError, "Unsupported translation engine: #{engine_name}"
       end

data/spec/purizumu/test_mode_spec.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Purizumu, '.test_mode!' do
+  after do
+    described_class.disable_test_mode!
+  end
+
+  it 'is disabled by default' do
+    expect(described_class.test_mode?).to be(false)
+  end
+
+  it 'enables test mode' do
+    described_class.test_mode!
+
+    expect(described_class.test_mode?).to be(true)
+  end
+
+  it 'returns the test engine while enabled' do
+    described_class.test_mode!
+
+    expect(described_class.engine).to be_a(Purizumu::Engines::Test)
+  end
+
+  it 'does not require engine configuration while enabled' do
+    described_class.test_mode!
+
+    expect(described_class.engine.translate(**translate_arguments)).to be_a(String)
+  end
+
+  it 'survives configuration resets' do
+    described_class.test_mode!
+    described_class.reset_configuration!
+
+    expect(described_class.test_mode?).to be(true)
+  end
+
+  it 'returns a deterministic stub translation by default' do
+    described_class.test_mode!
+
+    expect(described_class.engine.translate(**translate_arguments)).to eq('[jp] Prism')
+  end
+
+  it 'uses the handler result when a block is given' do
+    described_class.test_mode! { |locale:, content:, **| "#{content} in #{locale}" }
+
+    expect(described_class.engine.translate(**translate_arguments)).to eq('Prism in jp')
+  end
+
+  it 'passes the full request to the handler' do
+    seen = nil
+    described_class.test_mode! { |**request| seen = request }
+    described_class.engine.translate(**translate_arguments)
+
+    expect(seen).to eq(translate_arguments)
+  end
+
+  it 'coerces handler results to strings' do
+    described_class.test_mode! { |**| :symbolic }
+
+    expect(described_class.engine.translate(**translate_arguments)).to eq('symbolic')
+  end
+
+  it 'clears a previous handler when re-enabled without a block' do
+    described_class.test_mode! { |**| 'from handler' }
+    described_class.test_mode!
+
+    expect(described_class.engine.translate(**translate_arguments)).to eq('[jp] Prism')
+  end
+
+  describe '.disable_test_mode!' do
+    before do
+      described_class.test_mode! { |**| 'from handler' }
+      described_class.disable_test_mode!
+    end
+
+    it 'disables test mode' do
+      expect(described_class.test_mode?).to be(false)
+    end
+
+    it 'restores the configured engine' do
+      expect(described_class.engine).to be_a(Purizumu::Engines::Xai)
+    end
+
+    it 'clears the handler for later re-enables' do
+      described_class.test_mode!
+
+      expect(described_class.engine.translate(**translate_arguments)).to eq('[jp] Prism')
+    end
+  end
+
+  describe 'configuring the test engine directly' do
+    before do
+      described_class.configure { |config| config.engine = :test }
+    end
+
+    it 'returns the test engine' do
+      expect(described_class.engine).to be_a(Purizumu::Engines::Test)
+    end
+
+    it 'returns the default stub translation' do
+      expect(described_class.engine.translate(**translate_arguments)).to eq('[jp] Prism')
+    end
+
+    it 'is overridden by a test mode handler' do
+      described_class.test_mode! { |**| 'from handler' }
+
+      expect(described_class.engine.translate(**translate_arguments)).to eq('from handler')
+    end
+  end
+
+  describe 'translating model attributes in test mode' do
+    subject(:translated_name) { record.human_name }
+
+    before do
+      stub_const('GemRecord', Class.new(ActiveRecord::Base) do
+        self.table_name = 'gems'
+
+        attribute_translation :human_name
+      end)
+
+      described_class.test_mode!
+      I18n.locale = :jp
+    end
+
+    let!(:record) { GemRecord.create!(human_name: 'Prism') }
+
+    it 'returns the stubbed translation' do
+      expect(translated_name).to eq('[jp] Prism')
+    end
+
+    it 'persists the stubbed translation' do
+      translated_name
+
+      expect(persisted_translation.content).to eq('[jp] Prism')
+    end
+
+    it 'never opens an HTTP connection' do
+      allow(Net::HTTP).to receive(:new)
+      translated_name
+
+      expect(Net::HTTP).not_to have_received(:new)
+    end
+  end
+
+  def persisted_translation
+    Purizumu::Translation.find_by!(
+      model_class_name: 'GemRecord',
+      record_id: record.id,
+      attribute_name: 'human_name',
+      locale: 'jp'
+    )
+  end
+
+  def translate_arguments
+    {
+      model_name: 'GemRecord',
+      attribute_name: 'human_name',
+      content: 'Prism',
+      locale: 'jp',
+      source_locale: 'en'
+    }
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: purizumu
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - OpenAI Codex
@@ -65,6 +65,7 @@ files:
 - lib/generators/purizumu/install/templates/create_purizumu_translations.rb.erb
 - lib/purizumu.rb
 - lib/purizumu/configuration.rb
+- lib/purizumu/engines/test.rb
 - lib/purizumu/engines/xai.rb
 - lib/purizumu/engines/xai/payload_builder.rb
 - lib/purizumu/engines/xai/response_parser.rb
@@ -77,9 +78,10 @@ files:
 - spec/purizumu/configuration_spec.rb
 - spec/purizumu/engines/xai_spec.rb
 - spec/purizumu/generators/install_generator_spec.rb
+- spec/purizumu/test_mode_spec.rb
 - spec/purizumu/translator_spec.rb
 - spec/spec_helper.rb
-- spec/tmp/generator/db/migrate/20260413083431_create_purizumu_translations.rb
+- spec/tmp/generator/db/migrate/20260814023453_create_purizumu_translations.rb
 homepage: https://example.com/purizumu
 licenses:
 - MIT