memoria 0.1.0

data/lib/memoria.rb

@@ -0,0 +1,119 @@
+require 'memoria/configuration'
+require 'memoria/snapshot'
+require 'memoria/snapshot_saver'
+require 'memoria/version'
+
+# Encapsulates and provides access to the public interface of the gem.
+module Memoria
+  extend self
+
+  # The last recorded snapshot.
+  #
+  # @example
+  #   Memoria.record('name-of-snapshot')
+  #   Memoria.current_snapshot # => #<Memoria::Snapshot:0x00007fc5610a17b0 @name="name-of-snapshot">
+  #
+  # @return [Snapshot] The current snapshot or nil if there is no current snapshot.
+  #
+  # @api public
+  #
+  def current_snapshot
+    snapshots.last
+  end
+
+  # Configures Memoria.
+  #
+  # @example
+  #    Memoria.configure do |config|
+  #      config.snapshot_extension = 'snappy'
+  #      config.snapshot_record_mode = :new_episodes
+  #      config.add_setting :custom_setting_name do
+  #        Time.now
+  #      end
+  #    end
+  #
+  # @yield The configuration block.
+  # @yieldparam config [Configuration] The configuration object.
+  # @return [void]
+  #
+  # @see Memoria::Configuration The configuration object and its available configuration options.
+  #
+  # @api public
+  #
+  def configure
+    yield configuration
+  end
+
+  # Exposes the gem's configuration.
+  #
+  # @example
+  #   Memoria.configuration.snapshot_extension # => 'snap'
+  #
+  # @return [Configuration] The Memoria configuration.
+  #
+  # @api public
+  #
+  def configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Returns the list of recorded snapshots.
+  #
+  # @example
+  #   Memoria.record('name-of-snapshot-one')
+  #   Memoria.snapshots # => [#<Memoria::Snapshot:0x00007fc7a3870808 @name="name-of-snapshot-one">]
+  #
+  # @return [Array<Snapshot>] An array of recorded snapshots.
+  #
+  # @api public
+  #
+  def snapshots
+    @snapshots ||= []
+  end
+
+  # Returns an entity to persist snapshots (on the file system).
+  #
+  # @example
+  #   snapshot_saver = Memoria.snapshot_saver
+  #   snapshot_saver.save(Snapshot.new('index-page'))
+  #
+  # @return [SnapshotSaver] Reads and writes snapshots to the disk.
+  #
+  # @api public
+  #
+  def snapshot_saver
+    @snapshot_saver ||= SnapshotSaver.new(configuration)
+  end
+
+  # Records a new snapshot.
+  #
+  # @example
+  #   Memoria.record('name-of-snapshot')
+  #   Memoria.current_snapshot # => #<Memoria::Snapshot:0x00007fc5610a17b0 @name="name-of-snapshot">
+  #
+  # @param [String] snapshot_name The name of the snapshot.
+  # @return [Snapshot] A new snapshot.
+  #
+  # @api public
+  #
+  def record(snapshot_name)
+    snapshot = Snapshot.new(snapshot_name)
+    snapshots.push(snapshot)
+  end
+
+  # Stops recording snapshots.
+  #
+  # @example
+  #   Memoria.record('name-of-snapshot')
+  #   Memoria.current_snapshot # => #<Memoria::Snapshot:0x00007fc5610a17b0 @name="name-of-snapshot">
+  #   Memoria.stop_recording
+  #   Memoria.current_snapshot # => nil
+  #
+  # @return [Array] An empty array.
+  #
+  # @api public
+  #
+  def stop_recording
+    snapshots.clear
+  end
+end

data/lib/memoria/configuration.rb

@@ -0,0 +1,112 @@
+require 'memoria/errors'
+
+module Memoria
+  # Stores the configuration of the gem.
+  class Configuration
+    # The only allowed snapshot record modes.
+    VALID_SNAPSHOT_RECORD_MODES = %i[all new_episodes none].freeze
+
+    # @return [String] Directory where the snapshots will be saved
+    # @api public
+    #
+    attr_accessor :snapshot_directory
+
+    # @return [String] The way the snapshots are recorded.
+    # @api public
+    #
+    attr_reader :snapshot_record_mode
+
+    # @return [String] File extension of new snapshots.
+    # @api public
+    #
+    attr_reader :snapshot_extension
+
+    # Creates an instance of the configuration.
+    #
+    # @example
+    #   configuration = Memoria::Configuration.new
+    #
+    # @return [Configuration] An instance of +Configuration+.
+    #
+    # @api public
+    #
+    def initialize
+      self.snapshot_extension = 'snap'
+      self.snapshot_record_mode = :new_episodes
+    end
+
+    # Sets the extension for new snapshots.
+    #
+    # @param [Symbol] snapshot_extension The new snapshot extension.
+    # @raise [Errors::InvalidSnapshotExtension] If the snapshot extension is not valid.
+    #
+    # @return [String] The given snapshot extension.
+    #
+    # @api public
+    #
+    def snapshot_extension=(snapshot_extension)
+      validate_snapshot_extension(snapshot_extension)
+      @snapshot_extension = snapshot_extension
+    end
+
+    # Sets the snapshot record mode. TODO
+    #
+    # @param [Symbol] record_mode The new snapshot record mode.
+    # @raise [Errors::InvalidRecordMode] If record mode is not one of +VALID_SNAPSHOT_RECORD_MODES+
+    #
+    # @return [String] The given snapshot extension.
+    #
+    # @api public
+    #
+    def snapshot_record_mode=(record_mode)
+      validate_record_mode(record_mode)
+      @snapshot_record_mode = record_mode
+    end
+
+    # Adds a new setting with the given +name+.
+    #
+    # @example Configuring a setting directly.
+    #   configuration = Memoria::Configuration
+    #   configuration.add_setting(:now) do
+    #     Time.now
+    #   end
+    #
+    # @example Configuring a setting through Memoria's DSL.
+    #   Memoria.configure do |config|
+    #     config.add_setting(:now) do
+    #       Time.now
+    #     end
+    #   end
+    #
+    # @param [Symbol] name The name of the setting.
+    # @param [Symbol] block The block to be executed when the setting is called.
+    # @raise [Errors::DuplicateSetting] If there is already a setting defined with that name.
+    #
+    # @return [Symbol] The name of the setting
+    #
+    # @api public
+    #
+    def add_setting(name, &block)
+      validate_setting_existence(name)
+      define_singleton_method(name, block)
+    end
+
+    private
+
+    # Checks if there is a setting already defined with the given +setting_name.
+    def validate_setting_existence(setting_name)
+      error_message = "There is already a setting defined with the name #{setting_name}"
+      raise Errors::DuplicateSetting, error_message if respond_to?(setting_name)
+    end
+
+    # Checks if the snapshot record mode is one of the modes declared in +VALID_SNAPSHOT_RECORD_MODES+.
+    def validate_record_mode(record_mode)
+      raise Errors::InvalidRecordMode unless VALID_SNAPSHOT_RECORD_MODES.include?(record_mode.to_sym)
+    end
+
+    # Checks if the snapshot extension is valid.
+    def validate_snapshot_extension(snapshot_extension)
+      raise Errors::InvalidSnapshotExtension unless snapshot_extension =~ /^[a-zA-Z0-9]+$/
+    end
+  end
+end

data/lib/memoria/errors.rb

@@ -0,0 +1,4 @@
+require 'memoria/errors/invalid_configuration'
+require 'memoria/errors/invalid_record_mode'
+require 'memoria/errors/invalid_snapshot_extension'
+require 'memoria/errors/duplicate_setting'

data/lib/memoria/errors/duplicate_setting.rb

@@ -0,0 +1,16 @@
+module Memoria
+  module Errors
+    # Raised when attempting to add a setting that already exists.
+    class DuplicateSetting < InvalidConfiguration
+      # The generic message of the exception.
+      #
+      # @return [String] Exception's message.
+      #
+      # @api public
+      #
+      def message
+        "There's already a setting with that name."
+      end
+    end
+  end
+end

data/lib/memoria/errors/invalid_configuration.rb

@@ -0,0 +1,16 @@
+module Memoria
+  module Errors
+    # Raised when the configuration is invalid. This is a parent class to all the other classes.
+    class InvalidConfiguration < RuntimeError
+      # The generic message of the exception.
+      #
+      # @return [String] Exception's message.
+      #
+      # @api public
+      #
+      def message
+        "Memoria's configuration is invalid."
+      end
+    end
+  end
+end

data/lib/memoria/errors/invalid_record_mode.rb

@@ -0,0 +1,16 @@
+module Memoria
+  module Errors
+    # Raised when the record mode isn't one of +all+, +none+ or +new_snapshots+.
+    class InvalidRecordMode < InvalidConfiguration
+      # The generic message of the exception.
+      #
+      # @return [String] Exception's message.
+      #
+      # @api public
+      #
+      def message
+        'The snapshot record mode is invalid. The only valid modes are :all, :none and :new_snapshots.'
+      end
+    end
+  end
+end

data/lib/memoria/errors/invalid_snapshot_extension.rb

@@ -0,0 +1,16 @@
+module Memoria
+  module Errors
+    # Raised when the snapshot extension doesn't follow a file naming pattern.
+    class InvalidSnapshotExtension < InvalidConfiguration
+      # The generic message of the exception.
+      #
+      # @return [String] Exception's message.
+      #
+      # @api public
+      #
+      def message
+        'The snapshot extension is invalid.'
+      end
+    end
+  end
+end

data/lib/memoria/rspec.rb

@@ -0,0 +1,14 @@
+require 'memoria'
+require 'memoria/rspec/configurator'
+
+Memoria.configure do |config|
+  config.add_setting(:configure_rspec_hooks) do
+    Memoria::RSpec::Configurator.configure_rspec_hooks
+  end
+
+  config.add_setting(:include_rspec_matchers) do
+    Memoria::RSpec::Configurator.include_rspec_matchers
+  end
+
+  config.snapshot_directory = 'spec/fixtures/snapshots' unless config.snapshot_directory.nil?
+end

data/lib/memoria/rspec/configurator.rb

@@ -0,0 +1,46 @@
+require 'memoria/rspec/metadata'
+require 'memoria/rspec/metadata_parser'
+
+module Memoria
+  module RSpec
+    # Configures the integration with RSpec.
+    module Configurator
+      module_function
+
+      # Configures RSpec's +before+ and +after+ hooks to record snapshots when  +match_snapshot+ is called.
+      #
+      # @return [void]
+      #
+      # @api private
+      #
+      def configure_rspec_hooks
+        ::RSpec.configure do |config|
+          config.before(:each, snapshot: true) do |example|
+            current_example = example.respond_to?(:metadata) ? example : example.example
+            snapshot_name   = Memoria::RSpec::MetadataParser.find_description_for(current_example.metadata)
+
+            Memoria.record(snapshot_name)
+          end
+
+          config.after(:each, snapshot: true) do
+            Memoria.stop_recording
+          end
+        end
+      end
+
+      # Includes RSpec's matchers such as +match_snapshot+.
+      #
+      # @return [void]
+      #
+      # @api private
+      #
+      def include_rspec_matchers
+        require 'memoria/rspec/matcher'
+
+        ::RSpec.configure do |config|
+          config.include Memoria::RSpec::Metadata
+        end
+      end
+    end
+  end
+end

data/lib/memoria/rspec/matcher.rb

@@ -0,0 +1,30 @@
+require 'rspec/expectations'
+
+RSpec::Matchers.define :match_snapshot do
+  diffable
+
+  match do |actual|
+    snapshot_name = Memoria.current_snapshot.name
+
+    if snapshot_saver.snapshot_exists?(snapshot_name)
+      @expected = snapshot_saver.read(snapshot_name)
+      expect(expected).to eq(actual)
+    else
+      snapshot_saver.write(snapshot_name, actual)
+      RSpec.configuration.reporter.message "Generated snapshot: #{snapshot_name}"
+      true
+    end
+  end
+
+  # :nocov:
+  failure_message do
+    'Received value does not match the stored snapshot'
+  end
+  # :nocov:
+
+  def snapshot_saver
+    Memoria.snapshot_saver
+  end
+
+  attr_reader :expected
+end

data/lib/memoria/rspec/metadata.rb

@@ -0,0 +1,16 @@
+module Memoria
+  module RSpec
+    # Provides methods to retrieve RSpec's example metadata
+    module Metadata
+      # Retrieve the metadata from the current example
+      #
+      # @api private
+      #
+      # @return [Hash] RSpec's metadata of the current example.
+      #
+      def current_example_metadata
+        self.class.metadata
+      end
+    end
+  end
+end

data/lib/memoria/rspec/metadata_parser.rb

@@ -0,0 +1,49 @@
+module Memoria
+  module RSpec
+    # Extracts information from RSpec's examples metadata.
+    module MetadataParser
+      extend self
+
+      # Finds RSpec's description of a given example's metadata.
+      #
+      # @param [Hash] metadata RSpec's metadata of a given example.
+      #
+      # @return [String]
+      #
+      # @api private
+      #
+      def find_description_for(metadata)
+        description = find_description_in(metadata)
+        example_group = find_example_group_in(metadata)
+
+        if example_group
+          [find_description_for(example_group), description].join('/')
+        else
+          description
+        end
+      end
+
+      private
+
+      # Finds an RSpec description in a given metadata.
+      #
+      # @param [Hash] metadata RSpec's metadata
+      #
+      # @return [String] The description of an RSpec example
+      #
+      def find_description_in(metadata)
+        metadata[:description].empty? ? metadata[:scoped_id] : metadata[:description]
+      end
+
+      # Finds an RSpec example group in a given metadata.
+      #
+      # @param [Hash] metadata RSpec's metadata
+      #
+      # @return [Hash] The metadata of an RSpec example group
+      #
+      def find_example_group_in(metadata)
+        metadata.key?(:example_group) ? metadata[:example_group] : metadata[:parent_example_group]
+      end
+    end
+  end
+end