minitest-snapshot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d5a9382c2bcf4cc2c4c57e750249e69956f73ee4b8ee09582f7b9755b1c6055e
+  data.tar.gz: 821965c4ad60006195e2535590fdd58f50ae98194201c87fa17bcf17bd23dd2a
+SHA512:
+  metadata.gz: e5c939fa50eb1ff4472c95e002137ff959e483bbb02c149dd889c7b748cf1f41d1c3b8fc0b522a433a4a29da18b9d5f9a310f7e6a01a5c669d36d0ec25ffa10b
+  data.tar.gz: 1022c4fafa57453cf0ae395eab12c25398e122acbeda053f98e6f7161d1abd32b28e549d9fbb783e2f9b8bded8924a988335a63ee6f754ab73ff87fe0af2a671

data/.rubocop.yml

@@ -0,0 +1,49 @@
+inherit_from: .rubocop_todo.yml
+
+plugins:
+  - rubocop-minitest
+  - rubocop-performance
+  - rubocop-rake
+
+# The behavior of RuboCop can be controlled via the .rubocop.yml
+# configuration file. It makes it possible to enable/disable
+# certain cops (checks) and to alter their behavior if they accept
+# any parameters. The file can be placed either in your home
+# directory or in some project directory.
+#
+# RuboCop will start looking for the configuration file in the directory
+# where the inspected file is and continue its way up to the root directory.
+#
+# See https://docs.rubocop.org/rubocop/configuration
+
+AllCops:
+  TargetRubyVersion: "3.0"
+  NewCops: enable
+
+Layout/LineLength:
+  Enabled: true
+  Max: 100
+  Exclude:
+    - "**/*.gemspec"
+
+Metrics/BlockLength:
+  Enabled: true
+  Exclude:
+    - "test/**/*.rb"
+    - "spec/**/*.rb"
+    - "**/*.gemspec"
+
+Metrics/MethodLength:
+  Enabled: true
+  Max: 15
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Exclude:
+    - "spec/**/*"
+    - "test/**/*"

data/.rubocop_todo.yml

@@ -0,0 +1,7 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2025-03-14 12:17:15 UTC using RuboCop version 1.73.2.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-03-14
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/Guardfile

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exist?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+guard :minitest do
+  # with Minitest::Spec
+  watch(%r{^spec/(.*)_spec\.rb$})
+  # watch(%r{^lib/minitest/snapshot/(.+)\.rb$}) { 'spec' }
+  watch(%r{^lib/minitest/(.+)\.rb$})  { |m| "spec/minitest/#{m[1]}_spec.rb" }
+  watch(%r{^spec/spec_helper\.rb$}) { 'spec' }
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Kematzy
+
+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,202 @@
+<!-- markdownlint-disable MD013 MD033 -->
+
+# Minitest::Snapshot - Snapshot testing
+
+[![Ruby](https://github.com/kematzy/minitest-snapshot/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/kematzy/minitest-snapshot/actions/workflows/ruby.yml) - [![Gem Version](https://badge.fury.io/rb/minitest-snapshot.svg)](https://badge.fury.io/rb/minitest-snapshot) - [![Minitest Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop-minitest)
+
+Coverage: **100%**
+
+Snapshot testing for Minitest - compare your test outputs against saved reference snapshots.
+
+## What is Snapshot Testing?
+
+Snapshot testing is a way to verify that your code's output matches a previously saved "snapshot".
+Instead of manually writing expected outputs, you simply:
+
+1. Run the test once to generate the initial snapshot
+2. Verify the snapshot is correct
+3. In future test runs, your code's output will be compared against the saved snapshot
+
+This is especially useful for testing complex objects, API responses, HTML, JSON,
+and other outputs that would be tedious to write assertions for.
+
+This gem makes snapshot testing in Minitest similar to how it works in RSpec
+with [rspec-snapshot](https://github.com/levinmr/rspec-snapshot).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'minitest-snapshot'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install minitest-snapshot
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'minitest/autorun'
+require 'minitest/snapshot'
+
+class MyTest < Minitest::Test
+  def test_complex_object_matches_snapshot
+    complex_output = {
+      user: { name: 'Jane Doe', email: 'jane@example.com' },
+      permissions: ['read', 'write', 'admin']
+    }
+
+    assert_snapshot('user_with_permissions', complex_output)
+  end
+
+  def test_response_does_not_match_snapshot
+    unexpected_output = { status: 'error' }
+
+    refute_snapshot('successful_response', unexpected_output)
+  end
+end
+```
+
+### Using Expectation Syntax
+
+```ruby
+require 'minitest/autorun'
+require 'minitest/snapshot'
+
+describe 'API Response' do
+  it 'matches the expected structure' do
+    response = {
+      data: {
+        id: 123,
+        attributes: { title: 'Example', content: 'Content' }
+      }
+    }
+
+    _(response).must_match_snapshot('api_response')
+  end
+
+  it 'has changed from the previous version' do
+    response = { version: 'v2', data: {...} }
+
+    _(response).wont_match_snapshot('api_response_v1')
+  end
+end
+```
+
+### Snapshot Naming
+
+Snapshot names must follow these rules:
+
+- Must not be empty
+- Must not contain invalid filename characters (`< > : " | ? *`)
+- Must not include path traversal (`..`)
+- Must not include the file extension
+
+Valid snapshot names:
+
+- `'user_profile'`
+- `'api/responses/success'`
+
+### Snapshot Files
+
+By default, snapshots are stored in the `__snapshots__` directory at the root of your project.
+Snapshots in nested directories (e.g., `'api/responses/success'`) will be
+stored in matching subdirectories.
+
+### Updating Snapshots
+
+To update existing snapshots, run your tests with the `UPDATE_SNAPSHOTS` environment variable:
+
+```bash
+UPDATE_SNAPSHOTS=1 bundle exec rake spec
+```
+
+## Configuration
+
+You can configure Minitest::Snapshot with custom options:
+
+```ruby
+Minitest::Snapshot.configure do |config|
+  # Change the directory where snapshots are stored
+  config.snapshot_dir = 'test/fixtures/snapshots'
+
+  # Change the file extension for snapshot files
+  config.snapshot_file_extension = 'snap.json'
+
+  # Use a predefined serializer (:default, :json, or :yaml)
+  config.serializer = :json
+
+  # Configure JSON formatting options
+  config.json_options = { indent: '    ', object_nl: "\n" }
+
+  # Configure YAML formatting options
+  config.yaml_options = { line_width: 100 }
+
+  # Use a custom serializer
+  config.serializer = proc { |value| JSON.pretty_generate(value, indent: '  ') }
+
+  # Add a custom serializer for later use
+  config.add_serializer(:xml, proc { |value| value.to_xml })
+  # Then use it with:
+  # config.serializer = :xml
+end
+```
+
+### Available Serializers
+
+- `:default`: Uses `PP.pp` for pretty printing objects (good for Ruby objects)
+- `:json`: Formats output as JSON
+- `:yaml`: Formats output as YAML
+- Custom serializers can be added with `add_serializer`
+
+## Example Workflow
+
+1. Write a test using `assert_snapshot`
+2. Run the test for the first time - it will create the snapshot file
+3. Verify the snapshot file content is correct
+4. Run the test again - it will compare against the saved snapshot
+5. If you intentionally change the expected output, update the snapshot with `UPDATE_SNAPSHOTS=1`
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+
+Then, run `bundle exec rake spec` to run the tests.
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Contributing
+
+Bug reports and pull requests are welcome at [github.com/kematzy/minitest-snapshot](https://github.com/kematzy/minitest-snapshot).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Code inspiration taken from [rspec-snapshot](https://github.com/levinmr/rspec-snapshot)
+by [Mike Levin](https://github.com/levinmr/) released under a MIT License.
+
+This gem was essentially built because I wanted to experiment with Zed's AI coding assistant.
+
+For that reason, most of the code documentation and a large portion of the tests
+were created by Claude Sonnet via Zed's Assistant UI.
+
+Various other code parts were inspired by, or extracted from, Claude, Grok or ChatGPT answers.
+
+- [Zed's AI Assistant](https://zed.dev) with Claude Sonnet 3.5 & 3.7
+- [xAI's Grok 3](https://grok.com/)
+- [OpenAI's ChatGPT](https://chatgpt.com)

data/Rakefile

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+require 'rake/testtask'
+require 'rubocop/rake_task'
+
+Minitest::TestTask.create
+RuboCop::RakeTask.new
+
+Rake::TestTask.new(:spec) do |t|
+  # load the `lib` folder, and the `test | spec` folder.
+  t.libs = %w[lib spec]
+  t.test_files = FileList['spec/**/*_spec.rb']
+  # enable extra CLI output, including the CLI command for debugging
+  t.verbose = true
+end
+
+task default: %i[rubocop coverage]
+
+desc 'alias for spec task'
+task test: :spec
+
+desc 'Run specs with coverage'
+task :coverage do
+  ENV['COVERAGE'] = 'true'
+  Rake::Task['spec'].execute
+end

data/lib/minitest/snapshot/assertions.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: false
+
+# Alternative loading version when the `lib` directory is in the `$LOAD_PATH`
+# require 'minitest/snapshot/helpers'
+
+# Access the main Minitest module
+module Minitest
+  # re-open Assertions
+  module Assertions
+    # include Minitest::Snapshot::Helpers
+    include Minitest::Snapshot
+
+    def assert_snapshot(snapshot_name, value)
+      handle_snapshot(snapshot_name, value)
+    end
+
+    def refute_snapshot(snapshot_name, value)
+      handle_snapshot(snapshot_name, value, refute: true)
+    end
+  end
+
+  # re-open Expectations
+  module Expectations
+    infect_an_assertion :assert_snapshot, :must_match_snapshot
+    infect_an_assertion :refute_snapshot, :wont_match_snapshot
+  end
+end

data/lib/minitest/snapshot/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Minitest
+  module Snapshot
+    VERSION = '0.1.0'
+  end
+end

data/lib/minitest/snapshot.rb

@@ -0,0 +1,354 @@
+# frozen_string_literal: false
+
+require 'pp'
+require 'fileutils'
+require 'minitest'
+
+# loading core files using relative paths
+# require_relative 'snapshot/version'
+
+# Alternative loading version when the `lib` directory is in the `$LOAD_PATH`
+require 'minitest/snapshot/version'
+require 'minitest/snapshot/assertions'
+
+# NOTE! loading files in this manner marks the file as 100% covered in code coverage tests
+# even though it has not been tested
+
+module Minitest
+  # Contains functionality for snapshot testing in Minitest
+  module Snapshot
+    # Configuration class for Minitest::Snapshot that manages snapshot
+    # directory, file extensions, serializers, and format options
+    #
+    # @example Basic configuration
+    #   Minitest::Snapshot.configure do |config|
+    #     config.snapshot_dir = 'test/snapshots'
+    #     config.snapshot_file_extension = 'snap.json'
+    #   end
+    #
+    # @example Setting a predefined serializer
+    #   Minitest::Snapshot.configure do |config|
+    #     config.serializer = :json  # Use JSON serialization
+    #   end
+    #
+    # @example Setting a custom serializer
+    #   Minitest::Snapshot.configure do |config|
+    #     config.serializer = proc { |value| value.to_json }
+    #   end
+    #
+    # @example Adding a new serializer
+    #   Minitest::Snapshot.configure do |config|
+    #     config.add_serializer(:my_format, proc { |value|
+    #       MyFormatter.format(value)
+    #     })
+    #     config.serializer = :my_format
+    #   end
+    #
+    # @example Configuring JSON options
+    #   Minitest::Snapshot.configure do |config|
+    #     config.serializer = :json
+    #     config.json_options = { indent: '    ', object_nl: "\n" }
+    #   end
+    #
+    class Configuration
+      attr_accessor :snapshot_dir, :snapshot_file_extension, :json_options, :yaml_options
+      attr_reader :serializers
+
+      # Initialize a new Configuration with default values
+      #
+      # @return [Configuration] A new configuration instance
+      def initialize
+        @snapshot_dir = '__snapshots__'
+        @snapshot_file_extension = 'snap'
+        @serializers = {
+          default: proc { |value| value.is_a?(String) ? value : PP.pp(value, '') },
+          json: proc { |value| JSON.pretty_generate(value) },
+          yaml: proc { |value| YAML.dump(value) }
+        }
+        @current_serializer = :default
+
+        @json_options = { indent: '  ', object_nl: "\n" }
+        @yaml_options = { line_width: 80 }
+      end
+
+      # Sets the serializer to use for snapshots
+      #
+      # @example Set a built-in serializer
+      #   config.serializer = :json
+      #
+      # @example Set a custom serializer
+      #   config.serializer = proc { |value| CustomFormat.serialize(value) }
+      #
+      # @param key_or_proc [Symbol, Proc] A symbol referring to a predefined
+      #   serializer or a custom serializer proc
+      #
+      # @raise [ArgumentError] If the serializer name doesn't exist
+      # @return [Symbol, Proc] The serializer that was set
+      #
+      def serializer=(key_or_proc)
+        if key_or_proc.is_a?(Proc)
+          @custom_serializer = key_or_proc
+          @current_serializer = :custom
+        elsif @serializers.key?(key_or_proc)
+          @current_serializer = key_or_proc
+        else
+          raise ArgumentError, "Unknown serializer: #{key_or_proc}"
+        end
+      end
+
+      # Gets the current serializer proc
+      #
+      # @example Get and use the current serializer
+      #   serialized_value = config.serializer.call(my_object)
+      #
+      # @return [Proc] The currently selected serializer proc
+      #
+      def serializer
+        @current_serializer == :custom ? @custom_serializer : @serializers[@current_serializer]
+      end
+
+      # Adds a new serializer to the available serializers
+      #
+      # @example Adding a new serializer for XML
+      #   config.add_serializer(:xml, proc { |value| value.to_xml })
+      #
+      # @param name [Symbol, String] The name for the new serializer
+      # @param serializer_proc [Proc] The serializer proc that takes an object and returns a string
+      #
+      # @return [Hash] The updated serializers hash
+      #
+      def add_serializer(name, serializer_proc)
+        @serializers[name.to_sym] = serializer_proc
+      end
+    end
+
+    class << self
+      # Returns the configuration object for Minitest::Snapshot
+      #
+      # @example Getting the current configuration
+      #   config = Minitest::Snapshot.configuration
+      #   puts config.snapshot_dir
+      #
+      # @return [Configuration] The configuration object
+      #
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Configures Minitest::Snapshot with a block
+      #
+      # @example Basic configuration
+      #   Minitest::Snapshot.configure do |config|
+      #     config.snapshot_dir = 'test/snapshots'
+      #     config.snapshot_file_extension = 'snap.json'
+      #   end
+      #
+      # @example Setting a custom serializer
+      #   Minitest::Snapshot.configure do |config|
+      #     config.serializer = proc { |value| JSON.pretty_generate(value) }
+      #   end
+      #
+      # @example Using a predefined serializer
+      #   Minitest::Snapshot.configure do |config|
+      #     config.serializer = :yaml
+      #   end
+      #
+      # @yield [configuration] The configuration object
+      # @return [void]
+      #
+      def configure
+        yield(configuration) if block_given?
+      end
+
+      # Gets the directory where snapshots are stored
+      #
+      # @example Getting the snapshot directory
+      #   dir = Minitest::Snapshot.snapshot_dir
+      #   # => "__snapshots__"
+      #
+      # @return [String] The path to the snapshots directory
+      #
+      def snapshot_dir
+        configuration.snapshot_dir
+      end
+
+      # Sets the directory where snapshots are stored
+      #
+      # @example Setting the snapshot directory
+      #   Minitest::Snapshot.snapshot_dir = 'test/fixtures/snapshots'
+      #
+      # @param value [String] The path to the snapshots directory
+      # @return [String] The new path
+      #
+      def snapshot_dir=(value)
+        configuration.snapshot_dir = value
+      end
+
+      # Gets the current serializer used for snapshots
+      #
+      # @example Getting the current serializer
+      #   serializer = Minitest::Snapshot.snapshot_serializer
+      #   serialized_value = serializer.call(my_object)
+      #
+      # @return [Proc] The serializer proc
+      #
+      def snapshot_serializer
+        configuration.serializer
+      end
+
+      # Sets the serializer used for snapshots
+      #
+      # @example Setting a custom serializer
+      #   Minitest::Snapshot.snapshot_serializer = proc { |value|
+      #     JSON.pretty_generate(value, indent: '  ')
+      #   }
+      #
+      # @example Using a predefined serializer
+      #   Minitest::Snapshot.snapshot_serializer = :json
+      #
+      # @param value [Proc, Symbol] A proc that takes an object and returns a string,
+      #                             or a symbol referencing a predefined serializer
+      #
+      # @return [Proc, Symbol] The serializer that was set
+      #
+      def snapshot_serializer=(value)
+        configuration.serializer = value
+      end
+
+      # Gets the file extension used for snapshot files
+      #
+      # @example Getting the snapshot file extension
+      #   ext = Minitest::Snapshot.snapshot_file_extension
+      #   # => "snap"
+      #
+      # @return [String] The file extension
+      #
+      def snapshot_file_extension
+        configuration.snapshot_file_extension
+      end
+
+      # Sets the file extension used for snapshot files
+      #
+      # @example Setting the snapshot file extension
+      #   Minitest::Snapshot.snapshot_file_extension = 'snap.json'
+      #
+      # @param value [String] The file extension
+      #
+      # @return [String] The new file extension
+      #
+      def snapshot_file_extension=(value)
+        configuration.snapshot_file_extension = value
+      end
+    end
+
+    class Error < StandardError
+    end
+
+    private
+
+    # Generates a file path for a snapshot based on its name
+    #
+    # @param snapshot_name [String, Symbol] Name of the snapshot
+    #
+    # @return [String] The full path where the snapshot file will be stored
+    #
+    def snapshot_file_path(snapshot_name)
+      parts = snapshot_name.to_s.split('/')
+      filename = "#{parts.pop}.#{Minitest::Snapshot.snapshot_file_extension}"
+      dir = File.join(Minitest::Snapshot.snapshot_dir, *parts)
+      FileUtils.mkdir_p(dir)
+      File.join(dir, filename)
+    end
+
+    # Loads an existing snapshot from a file
+    #
+    # @param file [String] Path to the snapshot file
+    #
+    # @return [String, nil] The content of the snapshot file or nil if the file doesn't exist
+    #
+    def load_snapshot(file)
+      File.read(file) if File.exist?(file)
+    end
+
+    # Saves a value as a snapshot to a file
+    #
+    # @param file [String] Path where the snapshot will be saved
+    # @param value [Object] The value to be serialized and saved
+    #
+    # @return [Integer] The number of bytes written
+    #
+    def save_snapshot(file, value)
+      serialized = serialize(value)
+      File.write(file, serialized)
+    end
+
+    # Serializes a value using the configured serializer
+    #
+    # @param value [Object] The value to be serialized
+    # @return [String] The serialized representation of the value
+    #
+    def serialize(value)
+      Minitest::Snapshot.snapshot_serializer.call(value)
+    end
+
+    # Handles snapshot comparison or creation
+    #
+    # This method is the main coordinator for snapshot testing. It decides
+    # whether to update an existing snapshot, create a new one, or compare
+    # against an existing one based on environment settings and file existence.
+    #
+    # @param snapshot_name [String, Symbol] Name of the snapshot, used to generate the file path
+    # @param value [Object] The value to be serialized and compared or saved
+    # @param refute [Boolean] When true, test passes if snapshots don't match
+    #
+    # @raise [Minitest::Snapshot::Error] If any error occurs during snapshot handling
+    #
+    # @return [void]
+    #
+    def handle_snapshot(snapshot_name, value, refute: false)
+      file = snapshot_file_path(snapshot_name)
+
+      begin
+        if update_snapshots?
+          save_snapshot(file, value)
+        elsif File.exist?(file)
+          compare_with_snapshot(file, value, refute)
+        else # rubocop:disable Lint/DuplicateBranch
+          save_snapshot(file, value)
+        end
+      rescue StandardError => e
+        raise Minitest::Snapshot::Error,
+              "Failed to handle snapshot '#{snapshot_name}': #{e.message}"
+      end
+    end
+
+    # Compares a value with a saved snapshot
+    #
+    # @param file [String] Path to the snapshot file to compare against
+    # @param value [Object] The value to be serialized and compared
+    # @param refute [Boolean] When true, test passes if snapshots don't match
+    #
+    # @raise [Minitest::Assertion] If the assertion fails
+    #
+    # @return [Boolean] true if the assertion passes
+    #
+    def compare_with_snapshot(file, value, refute)
+      expected = load_snapshot(file)
+      serialized = serialize(value)
+
+      if refute
+        refute_equal expected, serialized, "Snapshot '#{file}' should not match."
+      else
+        assert_equal expected, serialized, "Snapshot '#{file}' does not match."
+      end
+    end
+
+    # Checks if snapshots should be updated based on environment variable
+    #
+    # @return [Boolean] true if UPDATE_SNAPSHOTS env var is set, false otherwise
+    #
+    def update_snapshots?
+      !!ENV.fetch('UPDATE_SNAPSHOTS', nil)
+    end
+  end
+end

data/sig/minitest/snapshot.rbs

@@ -0,0 +1,31 @@
+module Minitest
+  module Snapshot
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+    # Main method used to assert equality with a snapshot
+    def assert_snapshot: (untyped actual, ?String name) -> void
+
+    # Method to update snapshots when they need to be refreshed
+    def update_snapshot?: () -> bool
+
+    # Configuration options for snapshot testing
+    class Configuration
+      attr_accessor snapshot_directory: String
+      attr_accessor update_snapshots: bool
+
+      def initialize: () -> void
+    end
+
+    # Method to configure snapshot behavior
+    def self.configure: () { (Configuration) -> void } -> void
+
+    # Access to configuration
+    def self.configuration: () -> Configuration
+  end
+
+  # Extension to Minitest::Test to include Snapshot functionality
+  class Test
+    include Snapshot
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: minitest-snapshot
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kematzy
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-03-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.20.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.20.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Snapshot testing for Minitest - compare your test outputs against saved
+  reference snapshots
+email:
+- kematzy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE.txt
+files:
+- ".rubocop.yml"
+- ".rubocop_todo.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/minitest/snapshot.rb
+- lib/minitest/snapshot/assertions.rb
+- lib/minitest/snapshot/version.rb
+- sig/minitest/snapshot.rbs
+homepage: https://github.com/kematzy/minitest-snapshot
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kematzy/minitest-snapshot
+  source_code_uri: https://github.com/kematzy/minitest-snapshot
+  documentation_uri: https://github.com/kematzy/minitest-snapshot
+  changelog_uri: https://github.com/kematzy/minitest-snapshot/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options:
+- "--quiet"
+- "--line-numbers"
+- "--inline-source"
+- "--title"
+- 'Minitest::Snapshot: '
+- "--main"
+- README.md
+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.5.22
+signing_key:
+specification_version: 4
+summary: Minitest Snapshot testing - (like "rspec-snapshot")
+test_files: []