mailgun-mailbox 0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YTczNGJmNTllNTQwNGUxNDc4MTI3MTA5MWMwYmJhMDhhZjM3ODcyNg==
+  data.tar.gz: !binary |-
+    N2Q2NWM3NzcyYTUzMmI5OTIwZWMxZTNkYTg2Nzk2NjQ5NmEyNTAyNQ==
+SHA512:
+  metadata.gz: !binary |-
+    ZTRlYTYyN2MxNWM4OGRkZGMyZGVmM2NkN2E2ZGMyMTRhMjUzZjFhNjFmZDEx
+    MjQ3NWU0ZTExMTdiYzRhNTI1NTBiMmIxMTk3NDUzMzVmZTJmY2UzYzA4NzIz
+    MWE4ZmYwOGNiOTI2ZmQ3YmZmYTEwOTYzOTJmNmZiYjJkZTcyZTk=
+  data.tar.gz: !binary |-
+    OTRlNTVjZjEyMzZiOGMxZDcyYzBhNzlkY2Y1MzQ4OWY4Y2EzN2ZmYWYyYWY5
+    NjI3MzIwZmNiZWJmNWYxOTdiMGI0MDE0Y2I1ZTM1OGEyMjIwOGVlMDQyMWQ5
+    YmMwNGVjMTkzYjEyM2M1ODAzNmJjNDNlMWZlZTJkZGVjY2JlNmI=

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rest_client'
+gem 'json'
+gem 'mime-types', '~> 2.1'
+gem 'mail'
+gem 'selenium-webdriver'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Long Tail Ad Solutions
+
+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,56 @@
+# Mailgun::Mailbox
+
+  This library allows to have a disposable email address service built on top of subset of Mailgun Events and Storage API.
+  It does not require creating email address in advance.
+  We use this library as a part of our Cucumber Testing Framework to validate that emails are actually get sent to end users.
+  Also every test case should be independent from other test cases - email addresses should be unique every time.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'mailgun-mailbox'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mailgun-mailbox
+
+## Usage
+
+    See features/steps_definitions.rb for detailed example
+
+````ruby
+require 'mailgun/mailbox'
+
+#set thing up
+#Mailgun::Mailbox.set_config(<your mailgun api key>, <your mailgun domain>)
+#generate random email address with your mailgun domain
+@email_address = Mailgun::Mailbox.generate_email()
+
+#Here your app will send email message with specific subject to generated email address
+#...
+
+email = Mailgun::Mailbox.wait_for_email(<know subject>, email_address)
+#print email body
+puts email
+
+#delete all emails sent to address:
+Mailgun::Mailbox.delete_emails_to!(email_address)
+````
+
+## Testing package
+
+    $ cucumber MAILGUN_API_KEY=<your api key> MAILGUN_HOST=<your domain name registered with mailgun> SMTP_PASSWORD=<smtp password provided by mailgun for your domain>
+
+## Contributing
+
+1. Fork it
+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 new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/features/mailgun-mailbox.feature

@@ -0,0 +1,10 @@
+Feature: Validating Mailgun Mailbox functionality
+  Scenario: Finding message with random address
+    When I send email to random mailbox with random subject
+    Then I can load this message from mailbox
+
+  Scenario: Deleting message
+    When I send email to random mailbox with random subject
+    Then I can load this message from mailbox
+    When I delete this message
+    Then I don't see this message in mailbox

data/features/step_definitions/mailgun_steps.rb

@@ -0,0 +1,50 @@
+When(/^I send email to random mailbox with random subject$/) do
+
+  Mailgun::Mailbox.set_config(ENV['MAILGUN_API_KEY'], ENV['MAILGUN_HOST'], 20)
+  @email_address = Mailgun::Mailbox.generate_email()
+
+  #send email with SMTP and mailgun account
+  options = { :address              => "smtp.mailgun.org",
+              :port                 => 587,
+              :domain               => ENV['MAILGUN_HOST'],
+              :user_name            => "postmaster@#{ENV['MAILGUN_HOST']}",
+              :password             => ENV['SMTP_PASSWORD'],
+              :authentication       => 'plain',
+              :enable_starttls_auto => true  }
+
+
+  Mail.defaults do
+    delivery_method :smtp, options
+  end
+
+  @subject = "Random Subject #{Random.rand(999)}"
+
+  @body = 'testing mailgun mailbox'
+
+  Mail.deliver({to:"#{@email_address}", from:"#{@email_address}", subject: "#{@subject}", body: @body})
+
+end
+
+Then(/^I can load this message from mailbox$/) do
+  email = Mailgun::Mailbox.wait_for_email(@subject, @email_address)
+  email.nil?.should_not be_true
+  email.should == @body
+end
+
+When(/^I delete this message$/) do
+  Mailgun::Mailbox.delete_emails_to!(@email_address)
+end
+
+Then(/^I don't see this message in mailbox$/) do
+  email = nil
+  found_email = false
+  begin
+    email = Mailgun::Mailbox.wait_for_email(@subject, @email_address, 15)
+    found_email = true
+  rescue Selenium::WebDriver::Error::TimeOutError=>e
+    email = nil
+    found_email = false
+  end
+  email.nil?.should be_true
+  found_email.should be_false
+end

data/features/support/env.rb

@@ -0,0 +1,5 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__),'..','..','lib'))
+
+require'rspec/expectations'
+require 'mailgun/mailbox'
+require 'mail'

data/lib/mailgun/mailbox.rb

@@ -0,0 +1,166 @@
+require 'mailgun/mailbox/version'
+require 'rest_client'
+require 'json'
+require 'mail'
+require 'mailgun/mailbox/wait_until'
+require 'mailgun/mailbox/with_rescue'
+
+
+module Mailgun
+  module Mailbox
+    @mailgun_user = 'api'
+    @mailgun_host = 'api.mailgun.net'
+    @mailbox_timeout = 90
+
+    @found_message = nil
+    @generated_email = nil
+
+    def self.get_events_url
+      base_url = "https://#{@mailgun_host}/v2/#{@mailbox_domain}/events"
+      add_auth(base_url)
+    end
+
+    def self.add_auth(base_url)
+      uri = URI(base_url)
+      uri.user=@mailgun_user
+      uri.password=@mailgun_key
+      uri.to_s
+    end
+
+    def self.set_generated_email(email)
+      @generated_email = email
+    end
+
+
+    module_function
+    def look_for_email(subject, to_address)
+
+      to_address=@generated_email if to_address.nil?
+
+      t = events_request({:params => {:subject=>subject, :recipient => to_address}})
+
+      return if t['items'].count==0
+
+      m=nil
+      if t['items'][0].has_key?('storage')
+        m = get_first_message(t)
+      else
+        m = get_message_by_mid(t['items'][0]['message']['headers']['message-id'])
+      end
+
+      return if m.nil?
+
+      found_message = nil
+      found_message = m.text_part.decoded if m.text_part
+      found_message = m.html_part.decoded if m.html_part and found_message.nil?
+      found_message = m.body.decoded if found_message.nil?
+      return if found_message.nil?
+      return if found_message.length==0
+      @found_message = found_message
+
+    end
+
+    alias :_look_for_email :look_for_email
+
+    def get_message_by_mid(message_id)
+      t = events_request({:params => {'message-id' => message_id}})
+      return if !t.has_key?('items')
+      return if t['items'].count==0
+      return if !t['items'][0].has_key?('storage')
+      get_first_message(t)
+    end
+
+    def get_first_message(t)
+      msg_url = add_auth(t['items'][0]['storage']['url'])
+      r = RestClient.get add_auth(msg_url), {'accept' => 'message/rfc2822'}
+      t = JSON.parse(r.body)
+      m = Mail.new(t['body-mime'])
+    rescue RestClient::ResourceNotFound=>e
+      return nil
+    end
+
+    def events_request(params)
+      ::Mailgun::RetryHelper::with_rescue_many([RestClient::BadGateway, RestClient::RequestTimeout], 5) do
+        r = RestClient.get get_events_url, params
+        JSON.parse(r.body)
+      end
+    end
+
+    def self.wait_for_email(subject, to_address)
+      to_address=@generated_email if to_address.nil?
+      ::Mailgun::WaitUntil::wait_until(@mailbox_timeout, message="Email to '#{to_address}' with subject '#{subject}' was not found within #{@mailbox_timeout}") do
+        look_for_email(subject, to_address)
+      end
+    end
+
+    def self.get_message_urls(to_address)
+      t = events_request({:params => {:recipient => to_address}})
+      return if t['items'].count==0
+      t['items'].each do |item|
+        if item.has_key?('storage')
+          yield item['storage']['url']
+        else
+          t = events_request({:params => {'message-id' => item['message']['headers']['message-id']}})
+          yield t['items'][0]['storage']['url']
+        end
+      end
+    end
+
+    module_function
+
+    # deletes all email message in mailbox addressed to @to_address
+    # please note this method is tested to work on <100 messages in mailbox
+    # it would run slow if you'll try to delete 1000s of messages
+    # so it is suggested to run it after every test case
+    # @param [String] to_address
+    def delete_emails_to!(to_address)
+      get_message_urls(to_address) do |url|
+        RestClient.delete add_auth(url)
+      end
+    end
+
+    module_function
+
+    def clear_mailbox(to_address=nil)
+      to_address=@generated_email if to_address.nil?
+      delete_emails_to!(to_address)
+    end
+
+    module_function
+    #blocks till email message with specific subject and recipient address show up in the mailbox
+    #if email message doesn't show up withing <timeout> seconds throw Selenium::WebDriver::Error::TimeOutError exception
+    # @param [String] subject
+    # @param [String] to_address
+    # @param [Integer] timeout (optional)
+    # @return [String] return message body
+    # @raise Selenium::WebDriver::Error::TimeOutError if email message haven't shown up withing timeout seconds
+    def wait_for_email(subject, to_address, timeout=nil)
+      timeout = @mailbox_timeout if timeout.nil?
+      to_address=@generated_email if to_address.nil?
+      ::Mailgun::WaitUntil::wait_until(timeout, message="Email to '#{to_address}' with subject '#{subject}' was not found within #{@mailbox_timeout}") do
+        look_for_email(subject, to_address)
+      end
+    end
+
+    module_function
+    # @return [String] = random email address with Mailgun user Domain
+    def generate_email
+      @generated_email = "bot_test_runner+#{Time.now.strftime('%Y%m%d_%H%M%S')}_#{Random.rand(999)}@#{@mailbox_domain}"
+    end
+
+    module_function
+    # set configuration
+    # @param [String] mailgun_key
+    # @param [String] mailbox_domain
+    # @param [Integer] mailbox_timeout
+    # @param [String] mailgun_host
+    def set_config(mailgun_key, mailbox_domain, mailbox_timeout=90, mailgun_host='api.mailgun.net')
+      @mailgun_key = mailgun_key
+      @mailbox_domain = mailbox_domain
+      @mailgun_host = mailgun_host unless mailbox_timeout.nil?
+      @mailbox_timeout = mailbox_timeout unless mailbox_timeout.nil?
+    end
+
+
+  end
+end

data/lib/mailgun/mailbox/version.rb

@@ -0,0 +1,5 @@
+module Mailgun
+  module Mailbox
+    VERSION = '0.1'
+  end
+end

data/lib/mailgun/mailbox/wait_until.rb

@@ -0,0 +1,12 @@
+require 'selenium/webdriver/common/error'
+require 'selenium/webdriver/common/wait'
+module Mailgun
+  module WaitUntil
+
+    def self.wait_until(timeout = 10, message=nil, &block)
+      wait = Selenium::WebDriver::Wait.new(:timeout => timeout, :message => message)
+      wait.until &block
+    end
+
+  end
+end

data/lib/mailgun/mailbox/with_rescue.rb

@@ -0,0 +1,34 @@
+module Mailgun
+  module RetryHelper
+    def self.with_rescue(exception, limit=1, &block)
+
+      try=0
+      begin
+        block.call(try)
+      rescue exception
+        try+=1
+        retry if try<=limit
+      end
+    end
+
+    def self.with_rescue_many(exceptions, limit=1, &block)
+
+      try=0
+      begin
+        block.call(try)
+      rescue *exceptions
+        try+=1
+        retry if try<=limit
+      end
+    end
+
+  end
+end
+
+=begin
+usage example
+    RetryHelper::with_rescue(Selenium::WebDriver::Error::StaleElementReferenceError, 5) do
+      page_headline.include?('Your Billing Information')
+    end
+
+=end

data/mailgun-mailbox.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'mailgun/mailbox/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "mailgun-mailbox"
+  spec.version       = Mailgun::Mailbox::VERSION
+  spec.authors       = ["Vladimir Vladimirov"]
+  spec.email         = ["vladimir@jwplayer.com"]
+  spec.description   = %q{Ruby client for Mailgun API that provides methods to use subset Mailgun Events and Storage API functionality as a disposable email address service.}
+  spec.summary       = <<-eos
+  This library allows to have a disposable email address service built on top of subset of Mailgun Events and Storage API.
+  It does not require creating email address in advance.
+  We use this library as a part of our Cucumber Testing Framework to validate that emails are actually get sent to end users.
+  Also every test case should be independent from other test cases - email addresses should be unique every time.
+eos
+  spec.homepage      = "https://github.com/JWPlayer/mailgun-mailbox"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "cucumber"
+  spec.add_dependency "rest-client"
+  spec.add_dependency "json"
+  spec.add_dependency "mail"
+  spec.add_dependency "selenium-webdriver"
+end

metadata

@@ -0,0 +1,178 @@
+--- !ruby/object:Gem::Specification
+name: mailgun-mailbox
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Vladimir Vladimirov
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-01-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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: rspec
+  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: cucumber
+  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: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: selenium-webdriver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ruby client for Mailgun API that provides methods to use subset Mailgun
+  Events and Storage API functionality as a disposable email address service.
+email:
+- vladimir@jwplayer.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- features/mailgun-mailbox.feature
+- features/step_definitions/mailgun_steps.rb
+- features/support/env.rb
+- lib/mailgun/mailbox.rb
+- lib/mailgun/mailbox/version.rb
+- lib/mailgun/mailbox/wait_until.rb
+- lib/mailgun/mailbox/with_rescue.rb
+- mailgun-mailbox.gemspec
+homepage: https://github.com/JWPlayer/mailgun-mailbox
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.1.9
+signing_key: 
+specification_version: 4
+summary: This library allows to have a disposable email address service built on top
+  of subset of Mailgun Events and Storage API. It does not require creating email
+  address in advance. We use this library as a part of our Cucumber Testing Framework
+  to validate that emails are actually get sent to end users. Also every test case
+  should be independent from other test cases - email addresses should be unique every
+  time.
+test_files:
+- features/mailgun-mailbox.feature
+- features/step_definitions/mailgun_steps.rb
+- features/support/env.rb