delivery_matchers 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 362f6ed9e967c5664e98c668b7cb0b13125ea63d
-  data.tar.gz: a9574d94b314f3de76936ffcbf2f754b4bb8c0b4
+  metadata.gz: 0e78f4296323201bb6b45d5d38d1c6097e707d47
+  data.tar.gz: 4f3a1cb764fe4d9611ce5c6be03c5692d52e785a
 SHA512:
-  metadata.gz: 9957b3743f9505b41d52b3a4b49bc38747d3d79b1ea380ce7ddf05e1a189bf5f53196b842daa964aab7f4e9451bf30b1557127f600b46e166c8f4e86e82f9227
-  data.tar.gz: e04c8ccc43d9aa738dc2868dd39a357abfd3875fe7026495d6e44c87d60811455f25e783c97afd0c3a481bec47b1244486f8c4acd0e2a0f0fbcbae2f236a8dbe
+  metadata.gz: 096a255d6cda92bda89e1ca0e271809aadf78b2482b66fbae7be2b4c3d9a54c81f5da66d7e93280235b5fb3f391868b6bbb86be1bd86929d3baf8f277f51475e
+  data.tar.gz: 4f4ab701739ba5d96659151263b5d3fb15bf0f651646810b1c444217da9fecf927087afbd08bdb7abd6a7917e350115bd95bfff6a4849133805d3c2ad143fdc6

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/Gemfile.lock
+/gemfiles/*.gemfile.lock
+/pkg/
+/spec/reports/
+/tmp/
+/vendor

data/.rspec

@@ -0,0 +1,3 @@
+--color
+-I ./lib
+-r spec_helper

data/Appraisals

@@ -0,0 +1,7 @@
+appraise "actionmailer-4" do
+  gem "actionmailer", "4.2.8"
+end
+
+appraise "actionmailer-5" do
+  gem "actionmailer", "5.0.0"
+end

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in delivery_matchers.gemspec
+gemspec

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 General Assembly
+
+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,145 @@
+# DeliveryMatchers
+
+[![Build Status](https://semaphoreci.com/api/v1/generalassembly/delivery_matchers/branches/master/badge.svg)](https://semaphoreci.com/generalassembly/delivery_matchers)
+
+An RSpec custom matcher for ActionMailer's `deliver_later` method.
+
+This matcher was extracted from a General Assembly product with a considerable amount of logic to determine when to send certain transactional emails to different subsets of students.
+
+We wanted to ensure this code had bulletproof test coverage. Inspecting the in-memory ActiveJob queue let us test our delivery logic, but it also allowed a lot of low-level details to leak into our tests, making them harder to read.
+
+We rolled this custom matcher to keep our test code beautiful. We hope you find it as useful as we did!
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'delivery_matchers'
+```
+
+and include the `DeliveryMatchers` module in your RSpec config:
+
+```ruby
+RSpec.configure do |config|
+  config.include DeliveryMatchers
+end
+```
+
+
+## Usage
+
+### Basics
+
+Let's assume you have a garden-variety ActionMailer class:
+
+```ruby
+class UserMailer < ActionMailer::Base
+  def welcome(user)
+    @user = user
+  end
+end
+```
+
+Let's further assume you have a controller action that enqueues a welcome email for delivery with `deliver_later`, but only under certain circumstances:
+
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    ...
+    if user.emailable?
+      UserMailer(user).welcome.deliver_later
+    end
+    ...
+  end
+end
+```
+
+With this custom matcher, you can write tests to assert that the controller enqueues an email for delivery.
+
+```ruby
+expect( UserMailer.welcome(emailable_user) ).to be_delivered
+```
+
+You can also assert that an email is **not** delivered, in cases where that is the expected behavior.
+
+```ruby
+expect( UserMailer.welcome(non_emailable_user) ).not_to be_delivered
+```
+
+### Delivery options
+
+#### wait_until
+
+If you schedule an email for delivery on a future date with `wait_until`
+
+```ruby
+UserMailer.welcome(user).deliver_later(wait_until: 1.day.from_now)
+```
+
+you can test it with
+
+```ruby
+let(:email) { UserMailer.welcome(user) }
+expect(email).to be_delivered 1.day.from_now
+```
+
+or with the more explicit (and sometimes more readable) form
+
+```ruby
+expect(email).to be_delivered on: expected_date
+```
+
+#### wait
+
+If you use `wait` to schedule an email for delivery after a certain interval
+
+```ruby
+UserMailer.welcome(user).deliver_later(wait: 2.days)
+```
+
+you can test it like this
+
+```ruby
+expect(email).to be_delivered in: 2.days
+```
+
+#### queue
+
+You can also test that a delivery job was put into a particular queue
+
+```ruby
+UserMailer.welcome(user).deliver_later(queue: "priority")
+```
+
+like this
+
+```ruby
+expect(email).to be_delivered via_queue: "priority"
+```
+
+`via_queue` can also be combined with either the `on` or `in` options
+
+```ruby
+expect(email).to be_delivered 3.days.from_now, via_queue: "priority"
+
+expect(email).to be_delivered in: 2.days, via_queue: "priority"
+```
+
+### Alternative interface
+
+`be_delivered` supports `in`, `on`, and `via_queue` as a convenience for readability. But if you prefer consistency with the code being tested, you can also use the same keys provided to `deliver_later`.
+
+```ruby
+expect(email).to be_delivered wait_until: expected_date
+
+expect(email).to be_delivered wait: 2.days
+
+expect(email).to be_delivered queue: "priority"
+```
+
+### A note on precision
+
+This matcher performs all time comparisons with a precision of 1 second. If you see intermittent errors as a result, consider using [ActiveSupport's TimeHelpers](http://api.rubyonrails.org/classes/ActiveSupport/Testing/TimeHelpers.html) or the [Timecop gem](https://github.com/travisjeffery/timecop) to freeze time in your tests.

data/Rakefile

@@ -0,0 +1,9 @@
+require "appraisal"
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+default_task = ENV["APPRAISAL_INITIALIZED"] ? :spec : :appraisal
+
+task default: default_task

data/delivery_matchers.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'delivery_matchers/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "delivery_matchers"
+  spec.version       = DeliveryMatchers::VERSION
+  spec.authors       = ["General Assembly"]
+  spec.email         = ["opensource@generalassemb.ly"]
+
+  spec.summary       = "RSpec custom matchers for ActionMailer's deliver_later"
+  spec.homepage      = "https://github.com/generalassembly/delivery_matchers"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rspec", ">= 3.0"
+  spec.add_dependency "actionmailer", ">= 4.2", "< 5.1"
+  spec.add_dependency "activejob", ">= 4.2", "< 5.1"
+
+  spec.add_development_dependency "appraisal"
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
+end

data/gemfiles/actionmailer_4.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "actionmailer", "4.2.8"
+
+gemspec :path => "../"

data/gemfiles/actionmailer_5.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "actionmailer", "5.0.0"
+
+gemspec :path => "../"

data/lib/delivery_matchers.rb

@@ -0,0 +1,11 @@
+require "action_mailer"
+require "active_job"
+
+require "delivery_matchers/be_delivered"
+require "delivery_matchers/version"
+
+module DeliveryMatchers
+  def be_delivered(*args)
+    BeDelivered.new(*args)
+  end
+end

data/lib/delivery_matchers/be_delivered.rb

@@ -0,0 +1,158 @@
+module DeliveryMatchers
+  class BeDelivered
+    attr_reader :options, :email
+
+    def initialize(first={}, second={})
+      case first
+      when Time
+        # Allow user to specify the :on date as the first argument:
+        # be_delivered 1.day.from_now, via_queue: 'priority'
+        options = second
+        options[:on] = first
+      when Hash
+        options = first
+      end
+
+      # Rename the hash keys used by this matcher to match the keys used by
+      # ActionMailer::MessageDelivery#deliver_later
+      options[:wait]       ||= options[:in]
+      options[:wait_until] ||= options[:on]
+      options[:queue]      ||= options[:via_queue]
+
+      @options = options
+    end
+
+    def matches?(email)
+      @email = email
+      enqueued_jobs.any? { |job| match_expected?(job) }
+    end
+
+    def failure_message
+      enqueued = enqueued_jobs.map(&:inspect).join("\n  ")
+
+      [
+        "expected to find this mail delivery job in queue:",
+        "  #{expected_job}",
+        "instead found these jobs:",
+        "  #{enqueued}"
+      ].join("\n")
+    end
+
+    def failure_message_when_negated
+      [
+        "expected NOT to find this mail delivery job in queue:",
+        "  #{expected_job}"
+      ].join("\n")
+    end
+
+    private
+
+    def match_expected?(job)
+      args_match?(job) && options_match?(job)
+    end
+
+    def args_match?(job)
+      job[:args] == expected_args
+    end
+
+    def options_match?(job)
+      class_matches?(job) && queue_matches?(job) && time_matches?(job)
+    end
+
+    def class_matches?(job)
+      job[:job] == expected_class
+    end
+
+    def queue_matches?(job)
+      return true if options[:queue].nil?
+      job[:queue] == options[:queue]
+    end
+
+    def time_matches?(job)
+      return true unless options[:wait] || options[:wait_until]
+
+      if options[:wait]
+        expected = Time.current + options[:wait]
+      elsif options[:wait_until]
+        expected = options[:wait_until].to_time
+      end
+
+      # Difference between expected and actual must be less than 1 second
+      (job[:at].to_i - expected.to_i).abs <= 1
+    end
+
+    def expected_job
+      job = {
+        job:   expected_class,
+        args:  expected_args,
+        queue: expected_queue
+      }
+
+      if expected_delivery_time
+        job[:at] = expected_delivery_time
+      end
+
+      job
+    end
+
+    def expected_class
+      ActionMailer::DeliveryJob
+    end
+
+    def expected_queue
+      options[:queue] || 'mailers'
+    end
+
+    def expected_delivery_time
+      if options[:wait_until]
+        options[:wait_until].to_time.to_f
+      elsif options[:wait]
+        (Time.current + options[:wait]).to_f
+      end
+    end
+
+    def expected_args
+      mailer = expected_mailer
+      method = expected_method
+      args   = email.instance_variable_get('@args')
+
+      [mailer, method, 'deliver_now', *global_ids(args)]
+    end
+
+    def expected_mailer
+      if rails5?
+        email.instance_variable_get(:@mailer_class).to_s
+      else
+        email.instance_variable_get(:@mailer).to_s
+      end
+    end
+
+    def expected_method
+      if rails5?
+        email.instance_variable_get(:@action).to_s
+      else
+        email.instance_variable_get(:@mail_method).to_s
+      end
+    end
+
+    def global_ids(array)
+      Array(array).map { |obj| global_id(obj) }
+    end
+
+    def global_id(obj)
+      if obj.respond_to? :to_global_id
+        { "_aj_globalid" => obj.to_global_id.to_s }
+      else
+        obj
+      end
+    end
+
+    def enqueued_jobs
+      ActiveJob::Base.queue_adapter.enqueued_jobs
+    end
+
+    def rails5?
+      ActionMailer.version >= Gem::Version.new("5.0.0")
+    end
+  end
+end

data/lib/delivery_matchers/version.rb

@@ -0,0 +1,3 @@
+module DeliveryMatchers
+  VERSION = "0.1.1"
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: delivery_matchers
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - General Assembly
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-01 00:00:00.000000000 Z
+date: 2017-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -64,6 +64,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -98,7 +112,20 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Appraisals
+- Gemfile
+- LICENSE.md
+- README.md
+- Rakefile
+- delivery_matchers.gemspec
+- gemfiles/actionmailer_4.gemfile
+- gemfiles/actionmailer_5.gemfile
+- lib/delivery_matchers.rb
+- lib/delivery_matchers/be_delivered.rb
+- lib/delivery_matchers/version.rb
 homepage: https://github.com/generalassembly/delivery_matchers
 licenses: []
 metadata: {}
@@ -118,8 +145,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: RSpec custom matchers for ActionMailer's deliver_later
 test_files: []
+has_rdoc: