rspec_magic 0.1.2

data/README.md

@@ -0,0 +1,328 @@
+
+# A little bit of magic for RSpec tests
+
+<!-- @import "[TOC]" {cmd="toc" depthFrom=2 depthTo=6 orderedList=false} -->
+
+<!-- code_chunk_output -->
+
+- [Overview](#overview)
+- [Setup](#setup)
+- [Features](#features)
+  - [`alias_method`](#alias_method)
+  - [`context_when`](#context_when)
+  - [`described_sym`](#described_sym)
+  - [`include_dir_context`](#include_dir_context)
+  - [`use_letset`](#use_letset)
+  - [`use_method_discovery`](#use_method_discovery)
+- [Details](#details)
+  - [On setup](#on-setup)
+  - [On `context_when`](#on-context_when)
+  - [On `include_dir_context`](#on-include_dir_context)
+- [Copyright](#copyright)
+
+<!-- /code_chunk_output -->
+
+## Overview
+
+🆎 *Этот текст можно прочитать на русском языке: [README-ru.md](README-ru.md).*
+
+RSpecMagic is a set of extensions for writing compact and expressive tests.
+
+## Setup
+
+> 💡 *It's assumed that you've already set up RSpec in your project.*
+
+Add to your project's `Gemfile`:
+
+```ruby
+gem "rspec_magic"
+#gem "rspec_magic", git: "https://github.com/dadooda/rspec_magic"
+```
+
+Add to your RSpec startup file (usually `spec/spec_helper.rb`):
+
+```ruby
+require "rspec_magic/stable"
+require "rspec_magic/unstable"
+
+RSpecMagic::Config.spec_path = File.expand_path(".", __dir__)
+```
+
+The `spec_path` is used by some of the features, notably, [include_dir_context](#include_dir_context).
+The computed path should point to `spec/` of the project's directory.
+
+See [Details](#on-setup).
+
+## Features
+
+### `alias_method`
+
+A matcher to check that a method is an alias of another method.
+
+```ruby
+describe User do
+  it { is_expected.to alias_method(:admin?, :is_admin) }
+end
+```
+
+### `context_when`
+
+Create a self-descriptive `"when …"` context with one or more `let` variables defined.
+The blocks below are synonymous.
+
+```ruby
+context_when name: "Joe", age: 25 do
+  it do
+    expect([name, age]).to eq ["Joe", 25]
+  end
+end
+```
+
+```ruby
+context "when { name: \"Joe\", age: 25 }" do
+  let(:name) { "Joe" }
+  let(:age) { 25 }
+  it do
+    expect([name, age]).to eq ["Joe", 25]
+  end
+end
+```
+
+See [Details](#on-context_when).
+
+### `described_sym`
+
+Transform `described_class` into underscored symbols `described_sym` and `me`.
+
+```ruby
+describe UserProfile do
+  it { expect(described_sym).to eq :user_profile }
+  it { expect(me).to eq :user_profile }
+end
+```
+
+Common usage with a factory:
+
+```ruby
+describe UserProfile do
+  let(:uprof1) { create described_sym }
+  let(:uprof2) { create me }
+  …
+end
+```
+
+### `include_dir_context`
+
+♒︎ *This feature was added recently and may change.*
+
+Organize shared contexts ([shared_context](https://rspec.info/features/3-12/rspec-core/example-groups/shared-context/)) in a hierarchy.
+Import relevant shared contexts into the given test.
+
+Follow these steps:
+
+1. Make sure that `RSpecMagic::Config.spec_path` is configured correctly.
+   It must point to project's `spec/`.
+
+2. Across the spec directory tree, create the shared context files, each named `_context.rb`.
+   A typical `_context.rb` looks like this:
+
+    ```ruby
+    shared_context __dir__ do
+      …
+    end
+    ```
+
+3. Add to your hypothetical `spec_helper.rb`:
+
+    ```ruby
+    # Load the shared contexts hierarchy.
+    Dir[File.expand_path("**/_context.rb", __dir__)].each { |fn| require fn }
+    ```
+
+4. In the given spec file, add a call to `include_dir_context` in the body of the outermost `describe`:
+
+    ```ruby
+    describe … do
+      include_dir_context __dir__
+      …
+    end
+    ```
+
+Say, our spec file is `spec/app/controllers/api/player_controller_spec.rb`.
+
+The main `describe` will load the contexts from the following files, if any:
+
+```
+spec/_context.rb
+spec/app/_context.rb
+spec/app/controllers/_context.rb
+spec/app/controllers/api/_context.rb
+```
+
+See [Details](#on-include_dir_context).
+
+### `use_letset`
+
+Define a method to create `let` variables, which comprise a `Hash` collection.
+
+```ruby
+describe do
+  # Method is `let_a`. Collection is `attrs`.
+  use_letset :let_a, :attrs
+
+  # Declare `attrs` elements.
+  let_a(:age)
+  let_a(:name)
+
+  subject { attrs }
+
+  # None of the elements is set yet.
+  it { is_expected.to eq({}) }
+
+  # Set `name` and see it in the collection.
+  context_when name: "Joe" do
+    it { is_expected.to eq(name: "Joe") }
+
+    # Add `age` and see both in the collection.
+    context_when age: 25 do
+      it { is_expected.to eq(name: "Joe", age: 25) }
+    end
+  end
+end
+```
+
+When used with a block, `let_a` behaves like a regular `let`:
+
+```ruby
+describe do
+  use_letset :let_a, :attrs
+
+  let_a(:age) { 25 }
+  let_a(:name) { "Joe" }
+
+  it { expect(attrs).to eq(name: "Joe", age: 25) }
+end
+```
+
+### `use_method_discovery`
+
+Create an automatic `let` variable containing the method or action name,
+computed from the description of the parent `describe`.
+
+```ruby
+describe do
+  use_method_discovery :m
+
+  subject { m }
+
+  describe "#first_name" do
+    it { is_expected.to eq :first_name }
+  end
+
+  describe ".some_stuff" do
+    it { is_expected.to eq :some_stuff }
+  end
+
+  describe "GET some_action" do
+    describe "intermediate context" do
+      it { is_expected.to eq :some_action }   # (1)
+    end
+  end
+end
+```
+
+`m` finds the nearest *usable* context, whose description format allows
+the extraction of the method name.
+At the line marked (1) above, `m` ignores the loosely formatted `"intermediate context"`
+and grabs the data from `"GET some_action"`.
+
+## Details
+
+### On setup
+
+1. `stable` and `unstable` are feature sets.
+   Set `unstable` contains recently added features that may change in the coming versions.
+
+2. It's possible to include specific features only. Example:
+
+    ```ruby
+    require "rspec_magic/stable/use_method_discovery"
+    ```
+
+### On `context_when`
+
+1. The context can be temporarily excluded by prepending `x`:
+
+    ```ruby
+    xcontext_when … do
+      …
+    end
+    ```
+
+2. It's possible to define a custom report line formatter:
+
+    ```ruby
+    describe "…" do
+      def self._context_when_formatter(h)
+        "when #{h.to_json}"
+      end
+ 
+      context_when … do
+        …
+      end
+    end
+    ```
+
+3. `context_when` works nicely with [use_letset](#use_letset),
+   usually to set the attributes of the object being tested.
+
+4. The values of `let` belong to the `describe` level.
+   If you need values computed at the `it` level, use the traditional `let(…) { … }`
+   inside the context.
+
+### On `include_dir_context`
+
+There's a cool thing in RSpec — [shared_context](https://rspec.info/features/3-12/rspec-core/example-groups/shared-context/).
+The idea is simple: somewhere (in a hypothetical `spec_helper.rb`) fold something reusable in a `shared_context "this and that"`,
+and then import that stuff via `include_context "this and that"` where we need it.
+
+We can put anything in `shared_context` — reusable tests, `let` variables, *but most importantly* —
+methods, both belonging to the `describe` level (`def self.doit`) and the `it` level (`def doit`).
+
+Sounds like a library, innit?
+
+There's a pinch of salt though.
+Existing means of contexts management are very primitive and rely solely on unique global names.
+
+RSpec doesn't let us organize shared contexts in a hierarchy,
+and import them automatically into groups of spec files, such as:
+*all* model tests get context M, *all* controller tests get context C, and *all* at once get context A.
+
+In order to maintain minimal order, one has to come up with unique names for shared contexts,
+and list those contexts *in each and every* spec file:
+
+```ruby
+describe … do
+  include_context "basic"
+  include_context "controllers"
+  include_context "api_controllers"
+  …
+end
+```
+
+If you see anything like this, give your kudos to the author, as this is an advanced level.
+Most of the time, people don't even do that, but simply dump all of their extensions
+into some “helper”-like pile of cr%p, justifying it by stating that “there was no time to sort it out”.
+
+What does `include_dir_context` have to offer?
+
+1. The means to organize shared contexts in a hierarchy.
+2. The means to automatically import sets of *what is needed* into *where it's needed.*
+
+See the [main chapter](#include_dir_context) for a step-by-step example.
+
+## Copyright
+
+The product is free software distributed under the terms of the MIT license.
+
+— © 2017-2024 Alex Fortuna

data/Rakefile

@@ -0,0 +1,15 @@
+
+desc "Build the gem"
+task :build do
+  system "gem build rspec_magic.gemspec"
+end
+
+desc "Build YARD docs"
+task :doc do
+  system "bundle exec yard"
+end
+
+desc "Run tests"
+task :test do
+  system "bundle exec rspec"
+end

data/lib/rspec_magic/config.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RSpecMagic
+  # The configuration.
+  module Config
+    class << self
+      attr_writer :spec_path
+
+      # The path of where the specs are.
+      # Most commonly, <tt>spec/</tt> of the project's directory.
+      # @return [String]
+      def spec_path
+        @spec_path || raise("`#{__method__}` must be configured")
+      end
+    end
+  end
+end

data/lib/rspec_magic/stable/alias_method.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RSpecMagic; module Stable
+  # A matcher to check that a method is an alias of another method.
+  #
+  #   describe User do
+  #     it { is_expected.to alias_method(:admin?, :is_admin) }
+  #   end
+  #
+  module AliasMethod
+  end
+
+  # NOTE: `RSpec` has an autoloader of its own. Constants might not respond until we touch them.
+  begin; RSpec::Matchers; rescue NameError; end
+
+  # Activate.
+  defined?(RSpec::Matchers) && RSpec::Matchers.respond_to?(:define) and RSpec::Matchers.define(:alias_method) do |new_name, old_name|
+    match do |subject|
+      expect(subject.method(new_name)).to eq subject.method(old_name)
+    end
+
+    description do
+      "have #{new_name.inspect} aliased to #{old_name.inspect}"
+    end
+  end
+end; end

data/lib/rspec_magic/stable/context_when.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+"LODoc"
+
+module RSpecMagic; module Stable
+  # Create a self-descriptive <tt>"when …"</tt> context with one or more +let+ variables defined.
+  # The blocks below are synonymous.
+  #
+  #   context_when name: "Joe", age: 25 do
+  #     it do
+  #       expect([name, age]).to eq ["Joe", 25]
+  #     end
+  #   end
+  #
+  #   context "when { name: \"Joe\", age: 25 }" do
+  #     let(:name) { "Joe" }
+  #     let(:age) { 25 }
+  #     it do
+  #       expect([name, age]).to eq ["Joe", 25]
+  #     end
+  #   end
+  #
+  # = Features
+  #
+  # Prepend +x+ to +context_when+ to exclude it:
+  #
+  #   xcontext_when … do
+  #     …
+  #   end
+  #
+  # ---
+  #
+  # Define a custom report line formatter:
+  #
+  #   describe "…" do
+  #     def self._context_when_formatter(h)
+  #       "when #{h.to_json}"
+  #     end
+  #
+  #     context_when … do
+  #       …
+  #     end
+  #   end
+  #
+  module ContextWhen
+    module Exports
+      # Default formatter for {#context_when}. Defined your custom one at the +describe+ level if needed.
+      # @param [Hash] h
+      # @return [String]
+      def _context_when_formatter(h)
+        # Extract labels for Proc arguments, if any.
+        labels = {}
+        h.each do |k, v|
+          if v.is_a? Proc
+            begin
+              labels[k] = h.fetch(lk = "#{k}_label".to_sym)
+              h.delete(lk)
+            rescue KeyError
+              raise ArgumentError, "`#{k}` is a `Proc`, `#{k}_label` must be given"
+            end
+          end
+        end
+
+        pcs = h.map do |k, v|
+          [
+            k.is_a?(Symbol) ? "#{k}:" : "#{k.inspect} =>",
+            v.is_a?(Proc) ? labels[k] : v.inspect,
+          ].join(" ")
+        end
+
+        "when { " + pcs.join(", ") + " }"
+      end
+
+      # Create a context.
+      # @param [Hash] h
+      def context_when(h, &block)
+        context _context_when_formatter(h) do
+          h.each do |k, v|
+            if v.is_a? Proc
+              let(k, &v)
+            else
+              # Generic scalar value.
+              let(k) { v }
+            end
+          end
+          class_eval(&block)
+        end
+      end
+
+      # Create a temporarily excluded context.
+      def xcontext_when(h, &block)
+        xcontext _context_when_formatter(h) { class_eval(&block) }
+      end
+    end # Exports
+  end # module
+
+  # Activate.
+  defined?(RSpec) && RSpec.respond_to?(:configure) and RSpec.configure do |config|
+    config.extend ContextWhen::Exports
+  end
+end; end

data/lib/rspec_magic/stable/described_sym.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+"LODoc"
+
+module RSpecMagic; module Stable
+  # Transform +described_class+ into underscored symbols +described_sym+ and +me+.
+  #
+  #   describe UserProfile do
+  #     it { expect(described_sym).to eq :user_profile }
+  #     it { expect(me).to eq :user_profile }
+  #   end
+  #
+  # With a factory:
+  #
+  #   describe UserProfile do
+  #     let(:uprof1) { create described_sym }
+  #     let(:uprof2) { create me }
+  #     …
+  #   end
+  module DescribedSym
+    module Exports
+      # A +Symbol+ representation of +described_class+.
+      # @return [Symbol] E.g. +:user_profile+.
+      def described_sym
+        Util.underscore(described_class.to_s).to_sym
+      end
+      alias_method :me, :described_sym
+    end # Exports
+
+    # Utilities.
+    module Util
+      # Generate an underscored, lowercase representation of a camel-cased word.
+      # <tt>"::"</tt>s are converted to <tt>"/"</tt>s.
+      #
+      #   underscore("ActiveModel")         # => "active_model"
+      #   underscore("ActiveModel::Errors") # => "active_model/errors"
+      #
+      # NOTE: This method has been ported from ActiveSupport, mostly as is.
+      #
+      # @param [String] camel_cased_word
+      # @return [Symbol]
+      def self.underscore(camel_cased_word)
+        # Unlike ActiveSupport, we don't support acronyms.
+        acronym_regex = /(?=a)b/
+
+        word = camel_cased_word.to_s.dup
+        word.gsub!(/::/, '/')
+        word.gsub!(/(?:([A-Za-z\d])|^)(#{acronym_regex})(?=\b|[^a-z])/) { "#{$1}#{$1 && '_'}#{$2.downcase}" }
+        word.gsub!(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
+        word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+        word.tr!("-", "_")
+        word.downcase!
+        word
+      end
+    end
+  end # module
+
+  # Activate.
+  defined?(RSpec) && RSpec.respond_to?(:configure) and RSpec.configure do |config|
+    config.include DescribedSym::Exports
+  end
+end; end

data/lib/rspec_magic/stable/use_letset.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+"LODoc"
+
+module RSpecMagic; module Stable
+  # Define a method to create +let+ variables, which comprise a +Hash+ collection.
+  #
+  #   describe do
+  #     # Method is `let_a`. Collection is `attrs`.
+  #     use_letset :let_a, :attrs
+  #
+  #     # Declare `attrs` elements.
+  #     let_a(:age)
+  #     let_a(:name)
+  #
+  #     subject { attrs }
+  #
+  #     # None of the elements is set yet.
+  #     it { is_expected.to eq({}) }
+  #
+  #     # Set `name` and see it in the collection.
+  #     context_when name: "Joe" do
+  #       it { is_expected.to eq(name: "Joe") }
+  #
+  #       # Add `age` and see both in the collection.
+  #       context_when age: 25 do
+  #         it { is_expected.to eq(name: "Joe", age: 25) }
+  #       end
+  #     end
+  #   end
+  #
+  # When used with a block, +let_a+ behaves like a regular +let+:
+  #
+  #   describe do
+  #     use_letset :let_a, :attrs
+  #
+  #     let_a(:age) { 25 }
+  #     let_a(:name) { "Joe" }
+  #
+  #     it { expect(attrs).to eq(name: "Joe", age: 25) }
+  #   end
+  #
+  module UseLetset
+    module Exports
+      # Define the collection.
+      # @param let_method [Symbol]
+      # @param collection_let [Symbol]
+      def use_letset(let_method, collection_let)
+        keys_m = "_#{collection_let}_keys".to_sym
+
+        # See "Implementation notes" on failed implementation of "collection only" mode.
+
+        # E.g. "_data_keys" or something.
+        define_singleton_method(keys_m) do
+          if instance_variable_defined?(k = "@#{keys_m}")
+            instance_variable_get(k)
+          else
+            # Start by copying superclass's known vars or default to `[]`.
+            instance_variable_set(k, (superclass.send(keys_m).dup rescue []))
+          end
+        end
+
+        define_singleton_method let_method, ->(k, &block) do
+          (send(keys_m) << k).uniq!
+          # Create a `let` variable unless it's a declaration call (`let_a(:name)`).
+          let(k, &block) if block
+        end
+
+        define_method(collection_let) do
+          {}.tap do |h|
+            self.class.send(keys_m).each do |k|
+              h[k] = public_send(k) if respond_to?(k)
+            end
+          end
+        end
+      end
+    end # Exports
+  end # module
+
+  # Activate.
+  defined?(RSpec) && RSpec.respond_to?(:configure) and RSpec.configure do |config|
+    config.extend UseLetset::Exports
+  end
+end; end
+
+#
+# Implementation notes:
+#
+# * There was once an idea to support `use_letset` in "collection only" mode. Say, `let_a` appends
+#   to `attrs`, but doesn't publish a let variable. This change IS COMPLETELY NOT IN LINE with
+#   RSpec design. Let variables are methods and the collection is built by probing for those
+#   methods. "Collection only" would require a complete redesign. It's easier to implement another
+#   helper method for that, or, even better, do it with straight Ruby right in the test where
+#   needed. The need for "collection only" mode is incredibly rare, say, specific serializer
+#   tests.