radius-spec 0.3.0 → 0.7.0

data/common_rubocop_rails.yml

@@ -1,3 +1,5 @@
+require: rubocop-rails
+
 inherit_mode:
   merge:
     - Exclude
@@ -5,10 +7,6 @@ inherit_mode:
 
 inherit_from: common_rubocop.yml
 
-# Enable additional Rails cops
-Rails:
-  Enabled: true
-
 AllCops:
   Exclude:
     - 'bin/puma'
@@ -27,6 +25,9 @@ Documentation:
 
 Metrics/BlockLength:
   Exclude:
+    - 'bin/setup'
+    - 'bin/update'
+    - 'config/routes.rb'
     - 'spec/rails_helper.rb'
 
 # Rails foreign keys and indexes can get long. We want to ignore our annotation
@@ -39,6 +40,52 @@ Metrics/LineLength:
     - '\A#  fk_rails_'
     - '\A#  index_'
 
+# For our Rails apps several of them use the `respond_to` with `format` blocks
+# to handle various mime types (mostly HTML and JSON). Given our `do` / `end`
+# block style for non-functional blocks (which includes both `respond_to` and
+# `format`) the general method limit of is too small. This also applies to the
+# helper methods which define the allowed parameters for the action; especially
+# for larger forms.
+#
+# Here is an example of a minimal controller `update` method which uses the
+# `respond_to` style to support just the HTML and JSON formats:
+#
+#   ```ruby
+#   def update
+#     respond_to do |format|
+#       if @resource.update(resource_params)
+#         format.html do
+#           redirect_to resources_url, notice: 'Resource was successfully updated.'
+#         end
+#         format.json do
+#           render :show, status: :ok, location: @resource
+#         end
+#       else
+#         format.html do
+#           render :edit
+#         end
+#         format.json do
+#           render json: @resource.errors, status: :unprocessable_entity
+#         end
+#       end
+#     end
+#   end
+#   ```
+#
+# We do believe that the default size of 10, which is what we explicitly
+# configure below so there's no confusion, is a good general limit to help
+# encourage a balance between terseness and procedural code. Thus we do not
+# want to raise the limit, instead we just want to exclude these controllers.
+#
+# At this time there is no way for us to exclude just the common controller
+# actions / *_params methods so we exclude the entire file.
+#
+# Configuration parameters: CountComments.
+Metrics/MethodLength:
+  Max: 10
+  Exclude:
+    - 'app/controllers/**/*_controller.rb'
+
 # Ignore subclass parent for one off benchmarks
 #
 # Benchmarks are generally meant to be small and targeted. They often have
@@ -59,14 +106,58 @@ Rails/ApplicationRecord:
 Rails/CreateTableWithTimestamps:
   Enabled: false
 
-# The ActiveSupport monkey patches for `present?` are nearly all defiend as:
+# Usage of `find_by` is more expressive of intent than `where.first`. We should
+# check all app code, not just the models to improve intent expression.
+#
+# Since rake tasks often live in `lib` we also check all of lib as well.
+#
+# Configuration parameters: Include.
+# Include: app/models/**/*.rb
+Rails/FindBy:
+  Enabled: true
+  Include:
+    - 'app/**/*.rb'
+    - 'lib/**/*.rb'
+
+# Usage of `each` for large datasets can be a performance issue; specially a
+# drain on system memory. When possible it's better to use `find_each` so that
+# chunks of data are evaluated at a time.
+#
+# We should check all app code, not just the models to help prevent this. Since
+# rake tasks often live in `lib` we also check all of lib as well.
+#
+# Configuration parameters: Include.
+# Include: app/models/**/*.rb
+Rails/FindEach:
+  Enabled: true
+  Include:
+    - 'app/**/*.rb'
+    - 'lib/**/*.rb'
+
+# We understand the trade-offs for using the through model versus a lookup
+# table. As such this cop is just noise as it flags only those cases we really
+# do want a lookup table.
+#
+# Configuration parameters: Include.
+# Include: app/models/**/*.rb
+Rails/HasAndBelongsToMany:
+  Enabled: false
+
+# We find the combo `:only` and `:if` readable. While the `:except` and `:if`
+# combo is easier to read as a combined proc. As a team we are fine with
+# handling this in PR reviews, until such time which Rubocop provides an option
+# for us to configure this.
+Rails/IgnoredSkipActionFilterOption:
+  Enabled: false
+
+# The ActiveSupport monkey patches for `present?` are nearly all defined as:
 #
 #     !blank?
 #
-# For most of use `unless blank?` reads just as easily as `if present?`.
+# For most of us `unless blank?` reads just as easily as `if present?`.
 # Sometimes contextually, it can read better depending on the branch logic and
 # surrounding context. As `if present?` requires an additional negation and
-# method call it is technically slower. In the general case the perf different
+# method call it is technically slower. In the general case the perf difference
 # isn't much but in some cases it matters. Thus, we are not enforcing changing
 # `unless blank?` to `if present?` and are leaving it up to the context to
 # decide which is a better fit.
@@ -79,7 +170,7 @@ Rails/Present:
 # We prefer you use the attribute readers and writes. For those special cases
 # where the intent is really to interact with the raw underlying attribute we
 # prefer `read_attribute` and `write_attribute`; as this makes the intent
-# explict. Ideally we'd never use the hash like accessor `[:attr]`.
+# explicit. Ideally we'd never use the hash like accessor `[:attr]`.
 #
 # We disable this cop because it is not configurable.
 #
@@ -88,6 +179,37 @@ Rails/Present:
 Rails/ReadWriteAttribute:
   Enabled: false
 
+# This ensures we do not ignore potential validation issues in the code. Doing
+# so can lead to strange and surprising bugs where records are expected to
+# be created, or be modified, but are not.
+#
+#     # If author is a new record the book may not be created since the FK is
+#     # invalid. Perhaps omitting other fields, maybe new required fields, is
+#     # an oversight in the book creation as well.
+#     author.save
+#     Book.create(author: author)
+#
+# Or side effects are expected to occur but they do not:
+#
+#     # This is a condensed default Rails scaffold controller for `destroy`.
+#     #
+#     # Once a `has_many` or `has_one` associations is added which specifies
+#     # `dependent: :restrict_with_error` this no longer behaves as expected.
+#     # Given such associations are often added much later in time errors in
+#     # this action are an all to common oversight in Rails.
+#     def destroy
+#       @book.destroy
+#       respond_to do |format|
+#         format.html do
+#           redirect_to books_url, notice: 'Book was successfully destroyed.'
+#         end
+#       end
+#     end
+#
+# Configuration parameters: AllowImplicitReturn, AllowedReceivers.
+Rails/SaveBang:
+  Enabled: true
+
 # According to the Rails docs while the following methods skip validations they
 # only update the specified (single) attribute reducing risks. We'd rather not
 # warn for those cases:
@@ -105,17 +227,13 @@ Rails/ReadWriteAttribute:
 #   - http://api.rubyonrails.org/classes/ActiveRecord/Persistence.html
 #   - http://api.rubyonrails.org/classes/ActiveRecord/Relation.html
 #
+# Configuration parameters: Blacklist, Whitelist.
 # Blacklist: decrement!, decrement_counter, increment!, increment_counter, toggle!, touch, update_all, update_attribute, update_column, update_columns, update_counters
 Rails/SkipsModelValidations:
-  Blacklist:
-    - 'decrement_counter'
-    - 'increment_counter'
-    - 'toggle!'
-    - 'update_all'
-    - 'update_attribute'
-    - 'update_column'
-    - 'update_columns'
-    - 'update_counters'
+  Whitelist:
+    - 'decrement!'
+    - 'increment!'
+    - 'touch'
 
 # Rails uses compact style by default so we're disabling this with a :hammer:
 # for things likely to be generated by Rails (i.e. most things in app).

data/lib/radius/spec/model_factory.rb

@@ -268,6 +268,7 @@ module Radius
         def safe_transform(value)
           return value.call if value.is_a?(Proc)
           return value if value.frozen?
+
           value.dup
         end
 
@@ -426,44 +427,56 @@ module Radius
 
       # Convenience wrapper for building, and persisting, a model template.
       #
-      # This is a thin wrapper around `build(name, attrs).tap(&:save!)`. The
-      # persistence message `save!` will only be called on objects which
-      # respond to it.
-      #
-      # ### Avoid for New Code
+      # This is a thin wrapper around:
       #
-      # It is strongly suggested that you avoid using `create` for new code.
-      # Instead be explicit about when and how objects are persisted. This
-      # allows you to have fine grain control over how your data is setup.
+      # ```ruby
+      # build(name, attrs, &block).tap(&:save!)
+      # ```
       #
-      # We suggest that you create instances which need to be persisted before
-      # your specs using the following syntax:
+      # The persistence message `save!` will only be called on objects which
+      # respond to it.
       #
-      # ```ruby
-      # let(:an_instance) { build("AnyClass") }
+      # @note It is generally suggested that you avoid using `build!` for new
+      #   code. Instead be explicit about when and how objects are persisted.
+      #   This allows you to have fine grain control over how your data is
+      #   setup.
       #
-      # before do
-      #   an_instance.save!
-      # end
-      # ```
+      #   We suggest that you create instances which need to be persisted
+      #   before your specs using the following syntax:
       #
-      # Alternatively if you really want for the instance be lazy instantiated,
-      # and persisted, pass the appropriate persistence method as the block:
+      #   ```ruby
+      #   let(:an_instance) { build("AnyClass") }
       #
-      # ```ruby
-      # let(:an_instance) { build("AnyClass", &:save!) }
-      # ```
+      #   before do
+      #     an_instance.save!
+      #   end
+      #   ```
       #
       # @param (see .build)
       # @return (see .build)
       # @raise (see .build)
       # @see .build
       # @see .define_factory
-      def create(name, custom_attrs = {}, &block)
+      # @since 0.5.0
+      def build!(name, custom_attrs = {}, &block)
         instance = build(name, custom_attrs, &block)
         instance.save! if instance.respond_to?(:save!)
         instance
       end
+
+      # Legacy helper provided for backwards compatibility support.
+      #
+      # This provides the same behavior as {.build!} and will be removed in a
+      # future release.
+      #
+      # @param (see .build)
+      # @return (see .build)
+      # @raise (see .build)
+      # @see .build
+      # @see .define_factory
+      def create(name, custom_attrs = {}, &block)
+        build!(name, custom_attrs, &block)
+      end
     end
   end
 end

data/lib/radius/spec/rails.rb

@@ -7,7 +7,7 @@ require 'rspec/rails'
 
 RSpec.configure do |config|
   # Remove this line if you're not using ActiveRecord or ActiveRecord fixtures
-  config.fixture_path = ::Rails.root.join("spec", "fixtures")
+  config.fixture_path = ::Rails.root.join("spec", "fixtures").to_path
 
   # If you're not using ActiveRecord, or you'd prefer not to run each of your
   # examples within a transaction, remove the following line or assign false
@@ -40,7 +40,7 @@ RSpec.configure do |config|
   #   - http://guides.rubyonrails.org/v5.1.4/testing.html#implementing-a-system-test
   #   - https://relishapp.com/rspec/rspec-core/v/3-7/docs/filtering/exclusion-filters
   #   - http://rspec.info/documentation/3.7/rspec-core/RSpec/Core/Configuration.html#filter_run_excluding-instance_method
-  config.filter_run_excluding type: "system"
+  config.filter_run_excluding type: "system" unless config.files_to_run.one?
 
   # Always clear the cache before specs to avoid state leak problems
   config.before do

data/lib/radius/spec/rspec.rb

@@ -109,6 +109,11 @@ RSpec.configure do |config|
     config.include Radius::Spec::ModelFactory, :model_factory, :model_factories
   end
 
+  config.when_first_matching_example_defined(:tempfile, :tmpfile) do
+    require 'radius/spec/tempfile'
+    config.include Radius::Spec::Tempfile, :tempfile, :tmpfile
+  end
+
   config.when_first_matching_example_defined(type: :controller) do
     require 'radius/spec/model_factory'
     config.include Radius::Spec::ModelFactory, type: :controller
@@ -124,6 +129,11 @@ RSpec.configure do |config|
     config.include Radius::Spec::ModelFactory, type: :job
   end
 
+  config.when_first_matching_example_defined(type: :mailer) do
+    require 'radius/spec/model_factory'
+    config.include Radius::Spec::ModelFactory, type: :mailer
+  end
+
   config.when_first_matching_example_defined(type: :model) do
     require 'radius/spec/model_factory'
     config.include Radius::Spec::ModelFactory, type: :model
@@ -138,4 +148,14 @@ RSpec.configure do |config|
     require 'radius/spec/model_factory'
     config.include Radius::Spec::ModelFactory, type: :system
   end
+
+  config.when_first_matching_example_defined(:webmock) do
+    require 'webmock/rspec'
+  end
+
+  config.when_first_matching_example_defined(:vcr, :vcr_record, :vcr_record_new) do
+    require 'radius/spec/vcr'
+  end
 end
+
+require 'radius/spec/rspec/negated_matchers'

data/lib/radius/spec/rspec/negated_matchers.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Define negated matchers for use with composable matchers and compound
+# expectations.
+#
+# @see https://relishapp.com/rspec/rspec-expectations/v/3-8/docs/composing-matchers
+# @see https://relishapp.com/rspec/rspec-expectations/v/3-8/docs/compound-expectations
+RSpec::Matchers.define_negated_matcher :exclude, :include
+RSpec::Matchers.define_negated_matcher :excluding, :including
+RSpec::Matchers.define_negated_matcher :not_eq, :eq
+
+# Allows us to check that a block doesn't raise an exception while also
+# checking for other changes using compound expectations; since you can't chain
+# a negative (`not_to`) with any other matchers
+#
+# @see https://relishapp.com/rspec/rspec-expectations/v/3-8/docs/compound-expectations
+RSpec::Matchers.define_negated_matcher :not_change, :change
+RSpec::Matchers.define_negated_matcher :not_raise_error, :raise_error
+RSpec::Matchers.define_negated_matcher :not_raise_exception, :raise_exception

data/lib/radius/spec/tempfile.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'tempfile'
+
+module Radius
+  module Spec
+    # Temporary file helpers
+    #
+    # These helpers are meant to ease the creation of temporary files to either
+    # stub the data out or provide a location for data to be saved then
+    # verified.
+    #
+    # In the case of file stubs, using these helpers allows you to co-locate
+    # the file data with the specs. This makes it easy for someone to read the
+    # spec and understand the test case; instead of having to find a fixture
+    # file and look at its data. This also makes it easy to change the data
+    # between specs, allowing them to focus on just what they need.
+    #
+    # To make these helpers available require them after the gem:
+    #
+    # ```ruby
+    # require 'radius/spec'
+    # require 'radius/spec/tempfile'
+    # ```
+    #
+    # ### Including Helpers in Specs
+    #
+    # There are multiple ways you can use these helpers. Which method you
+    # choose depends on how much perceived magic/syntactic sugar you want:
+    #
+    #   - call the helpers directly on the module
+    #   - manually include the helper methods in the specs
+    #   - use metadata to auto load this feature and include it in the specs
+    #
+    # When using the metadata option you do not need to explicitly require the
+    # module. This gem registers metadata with the RSpec configuration when it
+    # loads and `RSpec` is defined. When the matching metadata is first used it
+    # will automatically require and include the helpers.
+    #
+    # Any of following metadata will include the factory helpers:
+    #
+    #   - `:tempfile`
+    #   - `:tmpfile`
+    #
+    # @example use a helper directly in specs
+    #   require 'radius/spec/tempfile'
+    #
+    #   RSpec.describe AnyClass do
+    #     it "includes the file helpers" do
+    #       Radius::Spec::Tempfile.using_tempfile do |pathname|
+    #         code_under_test pathname
+    #         expect(pathname.read).to eq "Any written data"
+    #       end
+    #     end
+    #   end
+    # @example manually include the helpers
+    #   require 'radius/spec/tempfile'
+    #
+    #   RSpec.describe AnyClass do
+    #     include Radius::Spec::Tempfile
+    #     it "includes the file helpers" do
+    #       using_tempfile do |pathname|
+    #         code_under_test pathname
+    #         expect(pathname.read).to eq "Any written data"
+    #       end
+    #     end
+    #   end
+    # @example use metadata to auto include the helpers
+    #   RSpec.describe AnyClass do
+    #     it "includes the file helpers", :tempfile do
+    #       using_tempfile do |pathname|
+    #         code_under_test pathname
+    #         expect(pathname.read).to eq "Any written data"
+    #       end
+    #     end
+    #   end
+    # @since 0.5.0
+    module Tempfile
+    module_function
+
+      # Convenience wrapper for managaing temporary files.
+      #
+      # This creates a temporary file and yields its path to the provided
+      # block. When the block returns the temporary file is deleted.
+      #
+      # ### Optional Parameters
+      #
+      # The block is required. All other parameters are optional. All
+      # parameters except `data` are Ruby version dependent and will be
+      # forwarded directly to the stdlib's
+      # {https://ruby-doc.org/stdlib/libdoc/tempfile/rdoc/Tempfile.html#method-c-create
+      # `Tempfile.create`}. The when the `data` parameter is provided it's
+      # contents will be written to the temporary file prior to yielding to the
+      # block.
+      #
+      # @example creating a tempfile to pass to code
+      #   def write_hello_world(filepath)
+      #     File.write filepath, "Hello World"
+      #   end
+      #
+      #   Radius::Spec::Tempfile.using_tempfile do |pathname|
+      #     write_hello_world pathname
+      #   end
+      # @example creating a file stub
+      #   stub_data = "Any file stub data text."
+      #   Radius::Spec::Tempfile.using_tempfile(data: stub_data) do |stubpath|
+      #     # File.read(stubpath)
+      #     # => "Any file stub data text."
+      #     code_under_test stubpath
+      #   end
+      # @example creating a file stub inline
+      #   Radius::Spec::Tempfile.using_tempfile(data: <<~TEXT) do |stubpath|
+      #     Any file stub data text.
+      #   TEXT
+      #     # File.read(stubpath)
+      #     # => "Any file stub data text.\n"
+      #     code_under_test stubpath
+      #   end
+      # @example creating a file stub inline without trailing newline
+      #   Radius::Spec::Tempfile.using_tempfile(data: <<~TEXT.chomp) do |stubpath|
+      #     Any file stub data text.
+      #   TEXT
+      #     # File.read(stubpath)
+      #     # => "Any file stub data text."
+      #     code_under_test stubpath
+      #   end
+      # @example writing binary data inline
+      #   Radius::Spec::Tempfile.using_tempfile(encoding: Encoding::BINARY, data: <<~BIN.chomp) do |binpath|
+      #     \xC8\x90\xC5\x9D\xE1\xB9\x95\xC4\x93\xC4\x89
+      #   BIN
+      #     # File.read(binpath)
+      #     # => "Ȑŝṕēĉ"
+      #     code_under_test binpath
+      #   end
+      # @param args [Object] addition file creation options
+      #
+      #   Passed directly to {https://ruby-doc.org/stdlib/libdoc/tempfile/rdoc/Tempfile.html#method-c-create
+      #   `Tempfile.create`}; see the stdlib docs for details on available
+      #   options.
+      # @param data [String] stub data to write to the file before yielding
+      # @param kwargs [Hash{Symbol => Object}] addition file creation options
+      #
+      #   Passed directly to {https://ruby-doc.org/stdlib/libdoc/tempfile/rdoc/Tempfile.html#method-c-create
+      #   `Tempfile.create`}; see the stdlib docs for details on available
+      #   options.
+      # @yieldparam pathname [Pathname] {https://ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html path}
+      #   of the created temporary file
+      # @note A block must be provided
+      # @see https://ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html Pathname
+      # @see https://ruby-doc.org/stdlib/libdoc/tempfile/rdoc/Tempfile.html Tempfile
+      def using_tempfile(*args, data: nil, **kwargs)
+        args << 'tmpfile' if args.empty?
+        ::Tempfile.create(*args, **kwargs) do |f|
+          f.write(data)
+          f.close
+          yield Pathname(f.path)
+        end
+      end
+    end
+  end
+end