radius-spec 0.1.0

data/README.md

@@ -0,0 +1,474 @@
+# Common RSpec Setup and Plug-ins
+
+[![Build Status](https://travis-ci.org/RadiusNetworks/radius-spec.svg?branch=master)](https://travis-ci.org/RadiusNetworks/radius-spec)
+[![Maintainability](https://api.codeclimate.com/v1/badges/701295df43d53e25eafe/maintainability)](https://codeclimate.com/github/RadiusNetworks/radius-spec/maintainability)
+[![Gem Version](https://badge.fury.io/rb/radius-spec.svg)](https://badge.fury.io/rb/radius-spec)
+
+Basic RSpec setup and plug-ins for use with Radius Networks Ruby / Rails
+projects.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'radius-spec'
+```
+
+And then execute:
+
+```console
+$ bundle
+```
+
+Or install it yourself as:
+
+```console
+$ gem install radius-spec
+```
+
+## Usage
+
+If you do not already have a project `.rspec` file we suggest creating one with
+at least the following:
+
+```ruby
+--require spec_helper
+```
+
+You _should_ check this `.rspec` file into version control. See the [RSpec
+`Configuration` docs](https://rspec.info/documentation/3.7/rspec-core/RSpec/Core/Configuration.html)
+and [Relish examples](https://relishapp.com/rspec/rspec-core/v/3-7/docs/configuration/read-command-line-configuration-options-from-files)
+for more on loading configuration options.
+
+To load the default suggested RSpec configuration, require this gem at the top
+of your `spec/spec_helper.rb` file. After requiring the gem you can include any
+custom RSpec configuration in a `RSpec.configure` block as usual:
+
+```ruby
+# /spec/spec_helper.rb
+# frozen_string_literal: true
+
+require 'radius/spec'
+
+RSpec.configure do |config|
+  # Your project specific custom settings here
+end
+```
+
+For Rails apps, we suggest a similar approach to your Rails helper:
+
+```ruby
+# /spec/rails_helper.rb
+# frozen_string_literal: true
+
+require 'spec_helper'
+ENV['RAILS_ENV'] ||= 'test'
+require File.expand_path('../../config/environment', __FILE__)
+# Prevent database truncation if the environment is production
+abort("The Rails environment is running in production mode!") if Rails.env.production?
+require 'radius/spec/rails'
+# Add additional requires below this line. Rails is not loaded until this point!
+
+# Checks for pending migration and applies them before tests are run.
+# If you are not using ActiveRecord, you can remove this line.
+ActiveRecord::Migration.maintain_test_schema!
+
+RSpec.configure do |config|
+  # Your project specific custom settings here
+end
+```
+
+## Features
+
+### Common Rubocop Config
+
+Projects can inherit from the [base Rubocop config](.rubocop.yml) by using
+either the remote raw URL or dependency gem formats:
+
+```yaml
+# Recommended Method
+inherit_gem:
+  radius-spec:
+    - common_rubocop.yml
+    # Use the following instead if it is a Rails project
+    - common_rubocop_rails.yml
+```
+
+```yaml
+# Available for projects which cannot include this gem (i.e. Ruby < 2.5)
+inherit_from:
+  - https://raw.githubusercontent.com/RadiusNetworks/radius-spec/master/common_rubocop.yml
+  # Use the following instead if it is a Rails project
+  - https://raw.githubusercontent.com/RadiusNetworks/radius-spec/master/common_rubocop_rails.yml
+```
+
+When using the raw URL you may need to add the following to the project's
+`.gitignore` file:
+
+```
+.rubocop-https---raw-githubusercontent-com-RadiusNetworks-radius-spec-master-common-rubocop-rails-yml
+.rubocop-https---raw-githubusercontent-com-RadiusNetworks-radius-spec-master-common-rubocop-yml
+```
+
+Be sure to include the project's local `.rubocop_todo.yml` **after** inheriting
+the base configuration so that they take precedence. Also, use the directive
+`inherit_mode` to specify which array configurations to merge together instead
+of overriding the inherited value. This can be set both globally and for
+specific cops:
+
+```yaml
+inherit_gem:
+  radius-spec:
+    - .rubocop.yml
+    # Use the following instead if it is a Rails project
+    - .rubocop_rails.yml
+inherit_from: .rubocop_todo.yml
+
+inherit_mode:
+  merge:
+    - Exclude
+
+Style/For:
+  inherit_mode:
+    override:
+      - Exclude
+  Exclude:
+    - bar.rb
+```
+
+Consult the [Rubocop documentation](https://rubocop.readthedocs.io/en/latest/configuration/#inheriting-configuration-from-a-remote-url)
+for the most up-to-date syntax for including the [.rubocop.yml](.rubocop.yml)
+config.
+
+### Basic Model Factory
+
+This factory is **not** Rails specific. It works for any object type that
+responds to `new` with a hash of attributes or keywords; including `Struct`
+using the new Ruby 2.5 `keyword_init` flag.
+
+#### Defining Factory Templates
+
+You can use the model factory directly to define a factory template:
+
+```ruby
+require 'radius/spec/model_factory'
+
+Radius::Spec::ModelFactory.define_factory(
+  "AnyClass",
+  attr1: :any_value,
+  attr2: :another_value,
+)
+```
+
+Most projects end up needing to specify multiple factories. Having to reference
+the full module every time you want to define a factory is tedious. When you
+need to define multiple factories we recommended using the factory catalog:
+
+```ruby
+require 'radius/spec/model_factory'
+
+Radius::Spec::ModelFactory.catalog do |c|
+  c.factory "AnyClass", attr1: :any_value, attr2: :another_value
+
+  c.factory "AnotherClass",
+            attr1: :any_value,
+            attr2: :another_value,
+            attr3: %i[any list of values]
+end
+```
+
+##### Storing Factory Templates
+
+Our convention is to store all of a project's factory templates in the file
+`spec/support/model_factories.rb`. As this is our convention, when the model
+factory is required it will attempt to load this file automatically as a
+convenience.
+
+##### Lazy Class Loading
+
+When testing in isolation we often don't want to wait a long time for a lot of
+unnecessary project/app code to load. With that in mind we want to keep loading
+the model factory and all factory templates as fast as possible. This mean not
+loading the associated project/app code at factory template definition time.
+This way if you only need one or two factories your remaining domain model code
+won't be loaded.
+
+To utilize this lazy loading define your template using either a string or
+symbol class name:
+
+```ruby
+Radius::Spec::ModelFactory.catalog do |c|
+  c.factory :AnyClass, attr1: :any_value, attr2: :another_value
+
+  c.factory "AnotherClass",
+            attr1: :any_value,
+            attr2: :another_value,
+            attr3: %i[any list of values]
+
+  c.factory "Nested::Module::SomeClass", attr1: :any_value
+end
+```
+
+The only requirement for this feature is that the class must be loaded by the
+project/app, or it uses an auto-loading mechanism, by the time the first
+instance is built by the factory.
+
+Also, this still supports defining the factory template using the class
+constant so no changes need to be made if that's your preference.
+
+##### Template Attribute Keys
+
+Attribute keys may be defined using either strings or symbols. However, they
+will be stored internally as symbols. This means that when an object instance
+is create using the factory the attribute hash will be provided to `new` with
+symbol keys.
+
+##### Dynamic Attribute Values (i.e. Generators)
+
+We try to keep the special cases / rules to a minimum. To support dynamic
+attributes we need to special case templates which define a `Proc` for an
+attribute value. For any template attribute which has a `Proc` for a value
+making an instance through the factory will send `call` to the proc with no
+args.
+
+> _NOTE: This only applies to instances of `Proc`. If you define a template
+> value with another object which responds to `call` that object will be set as
+> the attribute value without receiving `call`._
+
+You can use this to define generators in a number of ways:
+
+```ruby
+Radius::Spec::ModelFactory.catalog do |c|
+  # This is not thread safe.
+  gid_counter = 0
+  usually_gid_generator = -> { gid_counter += 1 }
+
+  c.factory :AnyClass,
+            gid: usually_gid_counter,
+            temp: -> { rand(0..100) }
+
+  c.factory "AnotherClass",
+            gid: usually_gid_counter,
+            uuid: -> { SecureRandom.uuid }
+end
+```
+
+> _NOTE: As of Ruby 2.5 `-> {}`, `lambda {}`, `proc {}`, and `Proc.new` are all
+> instances of `Proc`._
+
+While this is a powerful technique we suggest keeping it's use to a minimum.
+There's a lot of benefit to generative, mutation, and fuzzy testing. We just
+aren't convinced it should be the default when you generate unit / general
+integration test data.
+
+##### Self Documenting Attributes
+
+Factory templates may use the special symbols `:optional` and `:required` as a
+means of self documenting attributes. These are meant as descriptive
+placeholders for developers reading the factory definition. Any template
+attribute with a value of `:optional`, which is not overwritten by a custom
+value, will be removed just prior to building a new instance.
+
+Those attributes marked as `:required` will not be removed. Instead the symbol
+`:required` will be set as the attribute's value if it isn't overwritten by the
+custom data. This way, if it's considered an invalid, it will helpfully produce
+a more descriptive error message. And if it's considered a valid value, will
+provide some contextual information when used else where.
+
+For Rails projects, we suggest using `:required` for any association that is
+necessary for the object to be valid. We do not recommend attempting to
+generate default records within the factory as this can lead to unexpected
+database state; and hide relevant information away from the specs which may
+depend on it.
+
+##### "Safe" Attribute Duplication
+
+In an effort to help limit accidental state leak between instances the factory
+will duplicate all non-frozen template values prior to building the instance.
+Duplication is only applied to the values registered for the templates. Custom
+values provided when building the instance are not duplicated.
+
+#### Usage
+
+There are multiple ways you can build object instances using the model factory.
+Which method you choose depends on how much perceived magic/syntactic sugar you
+want:
+
+  - Call the model factory directly to instantiate instances:
+
+    ```ruby
+    require 'radius/spec/model_factory'
+
+    Radius::Spec::ModelFactory.define_factory "AnyClass", name: "Any Name"
+
+    AnyClass = Struct.new(:name, keyword_init: true)
+
+    default_instance = Radius::Spec::ModelFactory.build("AnyClass")
+    # => #<struct AnyClass name="Any Name">
+
+    default_instance.name
+    # => "Any Name"
+
+    custom_instance = Radius::Spec::ModelFactory.build(
+      :AnyClass,
+      name: "Any Custom Name",
+    )
+    # => #<struct AnyClass name="Any Custom Name">
+
+    custom_instance.name
+    # => "Any Custom Name"
+    ```
+
+  - Include the factory helper methods explicitly:
+
+    ```ruby
+    require 'radius/spec/model_factory'
+
+    RSpec.describe AnyClass do
+      include Radius::Spec::ModelFactory
+
+      it "includes the factory helpers" do
+        an_object = build(AnyClass)
+        expect(an_object.name).to eq "Any Name"
+      end
+    end
+    ```
+
+  - Include the factory helpers via metadata:
+
+    ```ruby
+    RSpec.describe AnyClass, :model_factory do
+      it "includes the factory helpers" do
+        an_object = build("AnyClass")
+        expect(an_object.name).to eq "Any Name"
+      end
+    end
+    ```
+
+    When using this metadata option you do not need to explicitly require the
+    model factory feature. This gem registers metadata with the RSpec
+    configuration when it loads and `RSpec` is defined. When the metadata is
+    first used it will automatically require the model factory feature and
+    include the helpers.
+
+    Any of following metadata will include the factory helpers:
+
+      - `:model_factory`
+      - `:model_factories`
+      - `type: :controller`
+      - `type: :feature`
+      - `type: :job`
+      - `type: :model`
+      - `type: :request`
+      - `type: :system`
+
+There are a few behaviors to note for using the builder:
+
+  - the class constant or fully qualified class name as a string (or symbol)
+    may be provided to the builder
+
+    This mirrors how defining the factory behaves.
+
+  - custom attribute values provided to the builder will replace any of the
+    registered defaults in the template
+
+  - new attributes not defined in the template may be included in the custom
+    attributes
+
+    These new attributes will be included with the other attributes and passed
+    to `new`.
+
+  - unlike the registered template attributes, all custom attributes (even
+    those that replace the registered attributes) are not modified or
+    duplicated in any way
+
+    This means if you provide an array or hash as an attribute value those
+    exact instances will be sent to `new`. Additionally, if you provide a
+    `Proc` as an attribute value it will be sent to new directly without
+    receiving `call`.
+
+##### Optional Block
+
+Both `build` and `create` support providing an optional block. This block is
+passed directly to `new` when creating the object. This is to support the
+common Ruby idiom of yielding `self` within initialize:
+
+  ```ruby
+  class AnyClass
+    def initialize(attrs = {})
+      # setup attrs
+      yield self if block_given?
+    end
+  end
+
+  RSpec.describe AnyClass, :model_factory do
+    it "passes the block to the object initializer" do
+      block_capture = nil
+      an_object = build("AnyClass") { |instance| block_capture = instance }
+      expect(block_capture).to be an_object
+    end
+  end
+  ```
+
+Since Ruby always supports passing a block to a method, even if the method does
+not use the block, it's possible the block will not run if the class being
+instantiated does not do anything with it.
+
+Also, while the common idiom is to `yield self` classes are free to yield
+anything. You need to be aware of how the class normally behaves when using
+this feature.
+
+##### "Creating" Instances
+
+We suggest that you create instances using the following syntax:
+
+  ```ruby
+  created_instance = build("AnyClass").tap(&:save!)
+  ```
+
+Or alternatively:
+
+  ```ruby
+  let(:an_instance) { build("AnyClass") }
+
+  before do
+    an_instance.save!
+  end
+  ```
+
+This way it is explicit what objects need to be persisted and in what order.
+
+However, many of our existing projects use a legacy `create` helper. This is
+simply a wrapper around `build.tap(&:save!)`, but it supports omitting the
+`save!` call for objects which do not support it.
+
+  ```ruby
+  created_instance = create("AnyClass")
+  ```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/RadiusNetworks/radius-spec. This project is intended to be a
+safe, welcoming space for collaboration, and contributors are expected to
+adhere to the [Contributor Covenant](http://contributor-covenant.org) code of
+conduct.
+
+## Code of Conduct
+
+Everyone interacting in the Radius::Spec project’s codebases, issue trackers,
+chat rooms and mailing lists is expected to follow the [code of
+conduct](https://github.com/RadiusNetworks/radius-spec/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/ci

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+# bin/ci: Setup environment for CI to run tests. This is primarily designed to
+#         run on the continuous integration server.
+
+set -e
+cd "$(dirname "$0")/.."
+echo "Current Working Dir: $(pwd)"
+
+# Run the specs for the rails app
+echo " ---> Running specs"
+bin/rspec
+
+# Script for running bundle audits
+# bundle-audit provides patch-level verification for Bundler
+# https://github.com/rubysec/bundler-audit.
+echo " ---> Running bundler-audit"
+gem install --no-rdoc --no-ri bundler-audit
+bundle-audit check --update
+
+# Run style checker
+echo " ---> Running rubocop"
+bin/rubocop --extra-details --display-style-guide

data/bin/console

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "radius/spec"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require "pry-byebug"
+Pry.start

data/bin/pry

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'pry' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 150) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("pry", "pry")

data/bin/rake

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 150) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 150) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/rubocop

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 150) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rubocop", "rubocop")

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install --jobs=3 --retry=3
+
+# Do any other automated setup that you need to do here

data/bin/travis

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'travis' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 150) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("travis", "travis")