oh_snap 0.2.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4c41a3989a772bbd58cf49c19f7d44b4b065050f64a605b0050803442a306848
+  data.tar.gz: 4d3cb106e11b1d74d4d9dda4212914f77a3e4fd5c65b1bab1db0500909d34460
+SHA512:
+  metadata.gz: 6b4fdf4ce22b5ed0ed7cc9da8d95a03e99bd02676f52179e52c26c5c8083fc220da929f2d14cf0c4490a2a7d570970d7cd7acca7db482601aa69421670859ae7
+  data.tar.gz: 03deebc5fb259d736c5058f6cbbd5418210ebea020d18cd8d5d6a6cdc48991a2c505d1c1dd172edf6b136525665da7b034ad100fd2ca4569f95db89b2434770b

data/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2025 Miguel Renom
+
+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,217 @@
+# OhSnap
+
+**OhSnap** is a Ruby gem for snapshot testing with helpers for Minitest and RSpec to name snapshot files after the tests that create them.
+It is built to be asserted via the equality comparator so you can use any assertion that you like that is based on it.
+
+## Features
+
+- **Compare snapshots with `#==`**: No special assertions are needed; just use equality syntax.
+- **Split in multiple files**: Stores snapshots in separate files for easy inspection.
+- **Automatic snapshot naming for Minitest and RSpec**: Automatically names snapshot files based on the test name.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'oh_snap'
+```
+
+and then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install oh_snap
+```
+
+## Usage
+
+Use the `OhSnap::Helper` to set up your snapshot registry on every test run:
+
+```ruby
+require 'oh_snap/helper'
+
+class MyTest < Test::Unit::TestCase
+  include OhSnap::Helper
+
+  def startup
+    super
+    setup_snapshots(path: File.dirname(__FILE__))
+  end
+
+  def test_a_snapshot_matches
+    assert_equal snapshot(name: 'snapshot_name'), 'some value'
+  end
+
+  def shutdown
+    save_snapshots
+    super
+  end
+end
+```
+
+You are responsible for specifying the base location for the `__snapshots__` directory in the `path:` argument and naming your snapshots passing `name:` in each call to `#snapshot`.
+
+Bear in mind that order is important when comparing snapshots to values:
+
+```ruby
+# Bad
+assert 'something' == snapshot
+assert_equal 'something', snapshot
+
+# Good
+assert snapshot == 'something'
+assert_equal snapshot, 'something'
+```
+
+If you really do not care about choosing your assertion, use the `snapshot_matches` helper method included with `OhSnap::Helper`:
+
+```ruby
+assert snapshot_matches('something')
+expect(snapshot_matches('something')).to be true
+```
+
+### Minitest and RSpec
+
+Helpers for RSpec and Minitest make things easier because they name the snapshot file automagically based on the test name:
+
+#### Minitest
+
+In your test file:
+
+```ruby
+require 'minitest/autorun'
+require 'oh_snap/minitest'
+
+class MyTest < Minitest::Test
+  include OhSnap::Minitest
+
+  def test_example
+    result = perform_complex_operation
+    assert snapshot == result
+  end
+
+    def test_example_with_assert_equal
+    result = perform_complex_operation
+    assert_equal snapshot, result
+  end
+
+  def test_example_with_matcher
+    result = perform_complex_operation
+    assert snapshot_matches(result)
+  end
+
+  def test_custom_named_snapshot
+    result = perform_another_operation
+    assert_equal snapshot(name: 'custom_snapshot_name'), result
+  end
+
+  def test_custom_named_snapshot_with_matcher
+    result = perform_another_operation
+    assert snapshot_matches(result, name: 'custom_snapshot_name')
+  end
+end
+```
+
+#### RSpec
+
+In your test file:
+
+```ruby
+require 'oh_snap/rspec'
+
+RSpec.configure do |config|
+  config.include OhSnap::RSpec
+end
+
+RSpec.describe 'My feature' do
+  it 'produces the correct output' do
+    result = perform_complex_operation
+    expect(snapshot).to eq result
+  end
+
+  it 'also produces the correct output' do
+    result = perform_complex_operation
+    expect(snapshot_matches(result)).to be true
+  end
+
+  it 'produces the correct output with custom snapshot name' do
+    result = perform_another_operation
+    expect(snapshot(name: 'custom_snapshot_name')).to eq result
+  end
+
+  it 'also produces the correct output with custom snapshot name' do
+    result = perform_another_operation
+    expect(snapshot_matches(result, name: 'custom_snapshot_name')).to be true
+  end
+end
+
+```
+
+In both cases, snapshots will be saved in the `__snapshots__` directory adjacent to the test file.
+
+## Updating Snapshots
+
+To update existing snapshots, set the `UPDATE_SNAPSHOTS` environment variable:
+
+```bash
+UPDATE_SNAPSHOTS=1 bundle exec rake test
+```
+
+This will regenerate snapshots for tests that fail due to mismatches.
+
+Notice that setting any value for `UPDATE_SNAPSHOTS` will be interpreted as setting the write mode as `true`.
+If you do not want to update snapshots, do not set `UPDATE_SNAPSHOTS` at all.
+The latter should be the case in your CI environment.
+
+## Configuration
+
+Global configuration can be set via `OhSnap.config`:
+```ruby
+OhSnap.config.tap do |config|
+  config.serializer = OhSnap::IdentitySerializer # Should inherit from OhSnap::BaseSerializer and implement #serialize.
+  config.snapshots_dirname = '__snapshots__' # Sets the name for the directory used to store snapshots.
+  config.writable = false # Sets the write/update mode. `true` if the UPDATE_SNAPSHOTS environment variable is set.
+end
+```
+
+### Write your own serializer
+
+Using `IdentitySerializer` forces you to compare stringified values to snapshots.
+If you need to serialize non-string objects, you can write your own serializer inheriting from `OhSnap::BaseSerializer` and implementing the `#serialize` method to return a string.
+
+```ruby
+require 'json'
+
+class MyJSONSerializer < OhSnap::BaseSerializer
+  def serialize(value)
+    JSON.dump(value)
+  end
+end
+```
+
+You can then use `setup_snapshots` in your test to use your new serializer:
+
+```ruby
+def setup
+  setup_snapshots(serializer: MyJSONSerializer)
+end
+
+def test_it_renders_the_expected_json_body
+  json_value = render_json_value
+  assert_equal snapshot, json_value
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/migl/oh_snap.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/oh_snap/base_serializer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'snapshot'
+
+module OhSnap
+  # Serializes and loads Snapshot objects.
+  class BaseSerializer
+    def serialize(value)
+      raise NotImplementedError, "#{self.class} must implement #serialize"
+    end
+
+    def load(value)
+      Snapshot.new(value, serializer: self)
+    end
+  end
+end

data/lib/oh_snap/helper.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'oh_snap'
+require 'oh_snap/registry'
+
+module OhSnap
+  # Helper methods for OhSnap to be included in test suites.
+  module Helper
+    def setup_snapshots(path:,
+                        serializer: OhSnap.config.serializer.new,
+                        snapshots_dirname: OhSnap.config.snapshots_dirname,
+                        writable: OhSnap.config.writable?)
+      @ohsnapshots = Registry.new(path: path,
+                                  serializer: serializer,
+                                  snapshots_dirname: snapshots_dirname,
+                                  writable: writable)
+    end
+
+    def snapshot(name:)
+      @ohsnapshots.snapshot(name: name)
+    end
+
+    def snapshot_matches(actual, name:)
+      snapshot(name: name) == actual
+    end
+
+    def save_snapshots
+      @ohsnapshots&.save
+    end
+  end
+end

data/lib/oh_snap/identity_serializer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'base_serializer'
+
+module OhSnap
+  # Returns `value` as is, without any transformation.
+  # `value` must be writable to a file.
+  class IdentitySerializer < BaseSerializer
+    def serialize(value)
+      value
+    end
+  end
+end

data/lib/oh_snap/minitest.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'oh_snap/helper'
+
+module OhSnap
+  # OhSnap helper for Minitest.
+  module Minitest
+    include OhSnap::Helper
+
+    def before_setup
+      super
+      setup_snapshots(path: File.dirname(File.expand_path(method(name).source_location.first)))
+    end
+
+    def snapshot(name: nil)
+      super(name: name || self.name)
+    end
+
+    def after_teardown
+      save_snapshots
+      super
+    end
+  end
+end

data/lib/oh_snap/registry.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module OhSnap
+  # Registry is responsible for managing snapshots during a test run.
+  class Registry
+    def initialize(path:, serializer:, snapshots_dirname:, writable:)
+      @path = path
+      @serializer = serializer
+      @snapshots_dirname = snapshots_dirname
+      @writable = writable
+      @snapshots = {}
+    end
+
+    def snapshot(name:)
+      return @snapshots[name] if @snapshots&.key?(name)
+
+      unless File.exist?(snapshot_path(name))
+        return @snapshots[name] = @serializer.load('') unless writable?
+
+        return @snapshots[name] = @serializer.load(nil)
+      end
+
+      File.open(snapshot_path(name), 'r') do |file|
+        @snapshots[name] = @serializer.load(file.read)
+      end
+
+      @snapshots[name]
+    end
+
+    def save
+      return unless writable?
+
+      Dir.mkdir(snapshots_path) unless Dir.exist?(snapshots_path)
+
+      @snapshots.each do |name, snapshot|
+        dump(name, snapshot)
+      end
+    end
+
+    private
+
+    def writable?
+      @writable
+    end
+
+    def dump(name, snapshot)
+      value = snapshot.touched? ? snapshot.actual : snapshot.expected
+      return if value.nil? || value.empty?
+
+      File.open(snapshot_path(name), 'w') do |file|
+        file.write(value)
+      end
+    end
+
+    def snapshot_path(name)
+      File.join(snapshots_path, "#{name}.snap")
+    end
+
+    def snapshots_path
+      @snapshots_path ||= File.join(@path, @snapshots_dirname)
+    end
+  end
+end

data/lib/oh_snap/rspec.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'oh_snap/helper'
+
+module OhSnap
+  # OhSnap helper for RSpec.
+  module RSpec
+    include OhSnap::Helper
+
+    def self.included(rspec)
+      rspec.before do
+        setup_snapshots(path: File.dirname(File.expand_path(rspec.location)))
+      end
+
+      rspec.after do
+        save_snapshots
+      end
+    end
+
+    def snapshot(name: nil)
+      name ||= ::RSpec.current_example
+                      .full_description
+                      .tr("%$|/:;<>?*#\"\t\r\n\\", '-')
+                      .tr(' ', '_')
+                      .strip
+      super(name: name)
+    end
+  end
+end

data/lib/oh_snap/snapshot.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OhSnap
+  # Represents a snapshot
+  class Snapshot
+    attr_reader :actual, :expected, :matched
+
+    def initialize(expected = nil, serializer:)
+      @actual = nil
+      @expected = expected
+      @serializer = serializer
+    end
+
+    def ==(other)
+      @actual = serialize(other)
+      @expected ||= serialize(other)
+      @matched = @expected == @actual
+    end
+
+    def touched?
+      defined?(@matched) && !@matched
+    end
+
+    def inspect
+      @expected.inspect
+    end
+
+    private
+
+    def serialize(value)
+      @serializer.serialize(value)
+    end
+  end
+end

data/lib/oh_snap/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OhSnap
+  VERSION = '0.2.3'
+end

data/lib/oh_snap.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'oh_snap/identity_serializer'
+
+# OhSnap is a library for managing snapshots in tests.
+# In memory of Laurent "Lolo" Wauquier, who never missed an opportunity to say it.
+module OhSnap
+  # Configuration class for OhSnap.
+  Configuration = Struct.new(:serializer, :snapshots_dirname, :writable) do
+    alias_method :writable?, :writable
+  end
+
+  def self.config
+    @config ||= Configuration.new.tap do |config|
+      config.serializer = OhSnap::IdentitySerializer
+      config.snapshots_dirname = '__snapshots__'
+      config.writable = ENV.fetch('UPDATE_SNAPSHOTS', false)
+    end
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: oh_snap
+version: !ruby/object:Gem::Version
+  version: 0.2.3
+platform: ruby
+authors:
+- migl
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: OhSnap is a Ruby library that provides snapshot testing capabilities
+  for Ruby applications, allowing developers to easily capture and compare snapshots
+  of serializable structures.
+email: hello@migl.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/oh_snap.rb
+- lib/oh_snap/base_serializer.rb
+- lib/oh_snap/helper.rb
+- lib/oh_snap/identity_serializer.rb
+- lib/oh_snap/minitest.rb
+- lib/oh_snap/registry.rb
+- lib/oh_snap/rspec.rb
+- lib/oh_snap/snapshot.rb
+- lib/oh_snap/version.rb
+homepage: https://github.com/migl/oh_snap
+licenses:
+- MIT
+metadata:
+  github_repo: ssh://github.com/migl/oh_snap
+  source_code_uri: https://github.com/migl/oh_snap
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Snapshots for Ruby tests
+test_files: []