email_spectacular 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0f37914ebc9f8c1fba4ef39afba24d808dce2557
+  data.tar.gz: 59dd333158d579bd98ba60c68eb795e9a88d380f
+SHA512:
+  metadata.gz: 17185632819ec97f045453a508ad419d4ea9bbb8f669415d070ccb249a118fcdaa7656ef7eea29d26062f5895396fba2cc91e65a8a3af396b2721f90cb96cd25
+  data.tar.gz: 1168413e77f916258af5a793dda207dfa0d98c4cda0e055c7e95e944393807faf175618eca0511e0d4083ec459b9ec54a110e886355479d62beaedd7c5f06b97

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,40 @@
+AllCops:
+  TargetRubyVersion: 2.5
+
+Metrics/LineLength:
+  Max: 120
+
+Metrics/AbcSize:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/RescueModifier:
+  Enabled: false
+
+Layout/MultilineOperationIndentation:
+  Enabled: false
+
+Layout/TrailingWhitespace:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Max: 20
+
+Metrics/CyclomaticComplexity:
+  Max: 20
+
+Metrics/MethodLength:
+  CountComments: false
+  Max: 20
+
+Metrics/BlockLength:
+  ExcludedMethods:
+    - describe
+    - context
+    - class_eval
+

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 2.2.2
+script:
+  - bundle exec rspec

data/.yardopts

@@ -0,0 +1 @@
+- README LICENSE

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Guardfile

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  last_run_spec = nil
+
+  watch(%r{^lib/(.+)\.rb$}) do |match|
+    file_path =
+      if match[1] == 'lib'
+        "spec/lib/#{match[2]}_spec.rb"
+      else
+        "spec/#{match[2]}_spec.rb"
+      end
+
+    if File.exist?(file_path)
+      file_path
+    else
+      last_run_spec
+    end
+  end
+
+  # RSpec files
+  rspec = dsl.rspec
+
+  # noinspection RubyResolve
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  # noinspection RubyResolve
+  watch(rspec.spec_support) { rspec.spec_dir }
+  # noinspection RubyResolve
+  watch(rspec.spec_files) do |spec|
+    # noinspection RubyUnusedLocalVariable
+    last_run_spec = spec[0]
+  end
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2019 Aleck Greenham
+
+MIT License
+
+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,166 @@
+# EmailSpectacular
+
+[![Gem](https://img.shields.io/gem/dt/email_spectacular.svg)]()
+[![Build Status](https://travis-ci.org/greena13/email_spectacular.svg)](https://travis-ci.org/greena13/email_spectacular)
+[![GitHub license](https://img.shields.io/github/license/greena13/email_spectacular.svg)](https://github.com/greena13/email_spectacular/blob/master/LICENSE)
+
+High-level email spec helpers for acceptance, feature and request tests.
+
+## What EmailSpectacular is
+
+Expressive email assertions that let you succinctly describe when emails should and should not be sent.
+
+### What EmailSpectacular is NOT
+
+A library for low-level or unit-testing of ActionMailers.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+group :test do
+  gem 'email_spectacular', require: false
+end
+```
+
+Add `email_spectacular` to your `spec/rails_helper.rb`
+
+```ruby
+
+require 'email_spectacular'
+
+# ...
+
+RSpec.configure do |config|
+  # ...
+
+  email_spectacular_spec_types = %i[acceptance feature request]
+  
+  config.after(:each, type: email_spectacular_spec_types) do
+    # Clear emails between specs
+    clear_emails
+  end
+  
+  email_spectacular_spec_types.each do |spec_type|
+    # Include email spectacular syntax in rspec tests
+    config.include EmailSpectacular::RSpec, type: spec_type
+  end
+end
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Email receiver address
+
+It's possible to assert an email was sent to one or more or more addresses using the following format:
+
+```ruby
+expect(email).to have_been_sent.to('user@email.com')
+```
+
+### Email sender address
+
+Similarly, you can assert an email was sent from an address:
+
+```ruby
+expect(email).to have_been_sent.from('user@email.com')
+```
+
+### Email subject
+
+You can assert an email's subject:
+
+```ruby
+expect(email).to have_been_sent.with_subject('Welcome!')
+```
+
+### Email body
+
+You can assert the body of an email by text:
+
+```ruby
+expect(email).to have_been_sent.with_text('Welcome, user@email.com')
+```
+
+Or using a selector on the email's HTML:
+
+```ruby
+expect(email).to have_been_sent.with_selector('#password')
+```
+
+Or look for links:
+
+```ruby
+expect(email).to have_been_sent.with_link('www.site.com/onboarding/1')
+```
+
+Or images:
+
+```ruby
+expect(email).to have_been_sent.with_image('www.site.com/assets/images/welcome.png')
+```
+
+### Chaining assertions
+
+You can chain any combination of the above that you want for ultra specific assertions:
+
+
+```ruby
+expect(email).to have_been_sent
+                  .to('user@email.com')
+                  .from('admin@site.com')
+                  .with_subject('Welcome!')
+                  .with_text('Welcome, user@email.com')
+                  .with_selector('#password').and('#username')
+                  .with_link('www.site.com/onboarding/1')
+                  .with_image('www.site.com/assets/images/welcome.png')
+
+```
+
+You can also chain multiple assertions of the the same type with the `and` method:
+
+```ruby
+expect(email).to have_been_sent
+                    .with_text('Welcome, user@email.com').and('Thanks for signing up')
+```
+
+### Asserting emails are NOT sent
+
+The `have_sent_email` assertion works with the negative case as well:
+
+```ruby
+expect(email).to_not have_been_sent.with_text('Secret token')
+```
+
+### Clearing emails
+
+Emails can be cleared at any point by calling `clear_emails` in your tests. This is helpful when you are testing a user workflow that may trigger multiple emails.
+
+If you followed in installation steps above, emails will automatically be cleared between each spec.
+
+## Test suite
+
+`email_spectacular` comes with close-to-complete test coverage. You can run the test suite as follows:
+
+```bash
+rspec
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/greena13/email_spectacular/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## Inspirations
+
+* [CapybaraEmail](https://github.com/DockYard/capybara-email)

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'

data/email_spectacular.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'email_spectacular/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'email_spectacular'
+  spec.version       = EmailSpectacular::VERSION
+  spec.authors       = ['Aleck Greenham']
+  spec.email         = ['greenhama13@gmail.com']
+  spec.summary       = 'High-level email spec helpers for acceptance, feature and request ' \
+                        'tests'
+  spec.description   = 'Expressive email assertions that let you succinctly describe when ' \
+                        'emails should and should not be sent'
+  spec.homepage      = 'https://github.com/greena13/email_spectacular'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(spec)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'actionmailer', '>= 0'
+  spec.add_dependency 'capybara', '~> 2.5', '>= 2.5.0'
+
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'guard', '~> 2.1'
+  spec.add_development_dependency 'guard-rspec', '~> 4.7'
+  spec.add_development_dependency 'rake', '~> 0'
+  spec.add_development_dependency 'rspec', '>= 3.5.0'
+end

data/lib/email_spectacular.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'email_spectacular/version'
+
+# High-level email spec helpers for acceptance, feature and request tests.
+#
+# @author Aleck Greenham
+#
+# @see https://github.com/greena13/email_spectacular EmailSpectacular Github page
+module EmailSpectacular
+end

data/lib/email_spectacular/dsl.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module EmailSpectacular
+  # Module containing the domain-specific language for expressing expectations of emails
+  #
+  # @author Aleck Greenham
+  module DSL
+    def self.included(base) # rubocop:disable Metrics/MethodLength
+      base.class_eval do
+        def initialize
+          @scopes = {}
+          @and_scope = nil
+        end
+
+        # Allows chaining two assertions on the same email attribute together without
+        # having to repeat the same method. Intended as syntactical sugar only and is
+        # functionally equivalent to repeating the method.
+        #
+        # @example Asserting an email was sent to two email addresses
+        #   expect(email).to have_been_sent.to('user1@email.com').and('user2@email.com')
+        #
+        # @param [Array<String>] arguments parameters to pass to whatever assertion is
+        #        being extended.
+        # @return [self] reference to self, to allow for further method chaining
+        def and(*arguments)
+          if @and_scope
+            send(@and_scope, *arguments)
+          else
+            ArgumentError.new('Cannot use an and modifier without a proceeding assertion.')
+          end
+        end
+
+        # For constructing an assertion that at least one email was sent to a
+        # <tt>email_address</tt>
+        #
+        # @example Asserting an email was sent to user@email.com
+        #   expect(email).to have_been_sent.to('user@email.com')
+        #
+        # @param [String, Array<String>] email_address address email is expected to be
+        #   sent to. If an array of email addresses, the email is expected to have been
+        #   sent to all of them.
+        # @return [self] reference to self, to allow for further method chaining
+        def to(email_address)
+          @scopes[:to] ||= []
+
+          if email_address.is_a?(Array)
+            @scopes[:to] = @scopes[:to].concat(email_address)
+          else
+            @scopes[:to] ||= []
+            @scopes[:to] << email_address
+          end
+
+          @and_scope = :to
+
+          self
+        end
+
+        # For constructing an assertion that at least one email was sent from
+        # <tt>email_address</tt>.
+        #
+        # @example Asserting an email was sent from admin@site.com
+        #   expect(email).to have_been_sent.from('admin@site.com')
+        #
+        # @param [String] email_address Address email is expected to be sent from.
+        # @raise ArgumentError when {#from} is called more than once on the same
+        #        expectation, as an email can only ben sent from a single sender.
+        # @return [self] reference to self, to allow for further method chaining
+        def from(email_address)
+          if @scopes[:from]
+            raise ArgumentError(
+              'An email can only have one from address, but you tried to assert the ' \
+              'presence of 2 or more values.'
+            )
+          end
+
+          @scopes[:from] = email_address
+          @and_scope = :from
+
+          self
+        end
+
+        # For constructing an assertion that at least one email was sent with a
+        # particular subject line
+        #
+        # @example Asserting an email was sent with subject line 'Hello'
+        #   expect(email).to have_been_sent.with_subject('Hello')
+        #
+        # @param [String] subject Subject line an email is expected to have been sent
+        #        with
+        # @raise ArgumentError when {#with_subject} is called more than once on the
+        #        same expectation, as an email can only have one subject line.
+        # @return [self] reference to self, to allow for further method chaining
+        def with_subject(subject)
+          if @scopes[:with_subject]
+            raise ArgumentError(
+              'An email can only have one subject, but you tried to assert the presence ' \
+              'of 2 or more values.'
+            )
+          end
+
+          @scopes[:with_subject] = subject
+
+          @and_scope = :with_subject
+
+          self
+        end
+
+        # For constructing an assertion that at least one email was sent with a particular
+        # string in the body of the email.
+        #
+        # @example Asserting an email was sent with the text 'User 1'
+        #   expect(email).to have_been_sent.with_text('User 1')
+        #
+        # @param [String] text Text an email is expected to have been sent with in the
+        #        body
+        # @return [self] reference to self, to allow for further method chaining
+        def with_text(text)
+          @scopes[:with_text] ||= []
+          @scopes[:with_text].push(text)
+
+          @and_scope = :with_text
+          self
+        end
+
+        # For constructing an assertion that at least one email was sent with a body that
+        # matches a particular CSS selector.
+        #
+        # @example Asserting an email was sent with a body matching selector '#imporant-div'
+        #   expect(email).to have_been_sent.matching_selector('#imporant-div')
+        #
+        # @param [String] selector CSS selector that should match at least one sent
+        #   email's body
+        # @return [EmailSpectacular::Expectation] reference to self, to allow for
+        #   further method chaining
+        def matching_selector(selector)
+          @scopes[:matching_selector] ||= []
+          @scopes[:matching_selector].push(selector)
+
+          @and_scope = :matching_selector
+          self
+        end
+
+        # For constructing an assertion that at least one email was sent with a link to
+        # a particular URL in the body.
+        #
+        # @example Asserting an email was sent with a link to http://www.example.com
+        #   expect(email).to have_been_sent.with_link('http://www.example.com')
+        #
+        # @param [String] href URL that should appear in at least one sent email's body
+        # @return [self] reference to self, to allow for further method chaining
+        def with_link(href)
+          @scopes[:with_link] ||= []
+          @scopes[:with_link].push(href)
+
+          @and_scope = :with_link
+          self
+        end
+
+        # For constructing an assertion that at least one email was sent with an image
+        # hosted at a particular URL
+        #
+        # @example Asserting an email was sent with the image http://www.example.com/image.png
+        #   expect(email).to have_been_sent.with_link('http://www.example.com/image.png')
+        #
+        # @param [String] src URL of the image that should appear in at least one sent
+        #   email's body
+        # @return [self] reference to self, to allow for further method chaining
+        def with_image(src)
+          @scopes[:with_image] ||= []
+          @scopes[:with_image].push(src)
+
+          @and_scope = :with_image
+          self
+        end
+      end
+    end
+  end
+end