teams_connector 0.1.1 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6a72ee260e0976efb58e9871414f88ea25090fef32d9786a9d0b2b5dad252be
-  data.tar.gz: 8a17c4cf19aa3313bd2361a2a2ca5524ba354d6be8079f594ef065209fd60c44
+  metadata.gz: 9ed38230a562264b9117ecea0aef7cd66b1bb7d947056f5b892e88cfaed906af
+  data.tar.gz: e3d01cfa5b8de620938e3f8bbd0c012591dc1ecbaf5b9dc742b03801b20c4d00
 SHA512:
-  metadata.gz: 51b2a71c1d50f252f1804a037e546d9e240707553f7052128b31191e1c28316177a95afb598eadfff11d1a7dd414eaa7d53294dd64da859fc9d3c6f73112af74
-  data.tar.gz: 9f39957ce3655246af7404d99b1f7281c0cc200257faf3ccf4c64ec02d45cd83ef08264e47f8769c0fc2affab1a7cfedf9ce10e60a876a8b9cff21aed2fd6a89
+  metadata.gz: 683b6a1095609d9f13263c71d7d17c4c466bd3041c334675985d13d4f2e9fd6f9b484354f21779c07b1ea4574fb11e3b10b6fae5e9d5f8fe9fdf2b34f72c27ea
+  data.tar.gz: c0144642fff244b53410dc78f4f6f59570f6354af3f431c6d429878c2fd7c9af377edcafe55a020b08765e40db11bac5a64819321a350d4d1ed05d92379645f6

data/CHANGES.md

@@ -1,5 +1,24 @@
 # Teams Connector Changelog
 
+0.1.5
+---
+- RSpec Matchers for testing, thanks to [rspec-rails](https://github.com/rspec/rspec-rails) for their ActionCable `have_broadcasted_to` matcher as reference
+- README update for testing
+- Sometimes use testing mode internally
+- Fixed code smells
+
+0.1.4
+---
+- Add rudimentary testing method
+
+0.1.3
+---
+- Allow sending a notification to multiple channels at the same time
+
+0.1.2
+---
+- Use `TeamsConnector::Configuration#load_from_rails_credentials` to load encrypted channel URLs in your Rails environment
+
 0.1.1
 ---
 - Adaptive Card Notification

data/README.md

@@ -25,16 +25,18 @@ Or install it yourself as:
     $ gem install teams_connector
 
 ## Usage
-After setting up the Incoming Webhook Connector four your Microsoft Teams channel, it is as simple as configuring the channel and creating a new `TeamsConnector::Notification`.
+After setting up the Incoming Webhook Connector for your Microsoft Teams channel, it is as simple as configuring the channel and creating a new `TeamsConnector::Notification`.
+
+The `channels` parameter can either be a single channel identifier or an array of multiple channel identifiers, that each will receive the notification. 
 
 ```ruby
-# Configuration
+# TeamsConnector initializer
 TeamsConnector.configure do |config|
   config.channel :channel_id, "https://<YOUR COMPLETE WEBHOOK URL GOES HERE>"
 end
 
 # Send a test card to your channel
-TeamsConnector::Notification.new(:test_card, :channel_id).deliver_later
+TeamsConnector::Notification.new(template: :test_card, channels: :channel_id).deliver_later
 
 # Send a card with a list of facts
 content = {
@@ -46,9 +48,38 @@ content = {
 }
 TeamsConnector::Notification::Message.new(:facts_card, "This is a summary", content).deliver_later
 ```
-This gem provides some basic templates in its default template path. You can also define your own templates in your own path. The default templates will be still available so you can mix and match.
 
-### Default templates
+### Secure Channel Configuration
+Since the Incoming Webhook Connector does not allow any authentication at the endpoint it is crucial that you keep your channel urls secret.
+At best nobody finds the url but it can also lead to spam or even faking of critical messages.
+
+In Rails provides the credentials functionality for [environmental security](https://edgeguides.rubyonrails.org/security.html#environmental-security). This mechanism can be used by TeamsConnector to load channels from an encrypted file. This also allows easy separation of production and development channel URLs.
+All channels are defined under the top-level entry `teams_connector` and will be identified by their key.
+```yaml
+# $ bin/rails credentials:edit
+teams_connector:
+  default: "<INSERT DEFAULT URL HERE>"
+  sales: "<INSERT URL FOR THE :sales CHANNEL HERE>"
+```
+
+After configuration of the credentials you can load the channels in your initializer.
+Since `#load_from_rails_configuration` is a wrapper around `#channel` both methods can be used together.
+
+```ruby
+# TeamsConnector initializer
+TeamsConnector.configure do |config|
+  config.load_from_rails_credentials
+  # After loading the :default channel is available and can be set as the default 
+  config.default = :default
+  config.channel :another_channel, "<URL>"
+end
+```
+
+### Templates
+This gem provides some basic templates in its default template path. You can also define your own templates in your own path.
+The default templates will be still available so you can mix and match.
+
+#### Default templates
 
 Template name | Description
 -----|-------
@@ -56,13 +87,13 @@ Template name | Description
 :facts_card | A card with title, subtitle and a list of facts
 :test_card | A simple text message without any configurable content for testing
 
-### Custom Templates
+#### Custom Templates
 
 Custom templates are stored in the directory specified by the configuration option `template_dir`. As an array of strings, describing the path relative to the project root. When using Rails or Bundler their root is used, otherwise it is the current working directory.
 
 Templates are json files with the extension `.json.erb`. The file is parsed and populated by the ruby ERB module.
 
-### Builder
+#### Builder
 
 You can use TeamsConnector::Builder to create Adaptive Cards directly in ruby. YOu can output the result of the builder as JSON for future use with `TeamsController::Notification::AdaptiveCard#pretty_print`.
 
@@ -78,6 +109,66 @@ end
 TeamsConnector::Notification::AdaptiveCard.new(content: builder).deliver_later
 ```
 
+## Testing
+
+To test TeamsConnector integration in your application you can use the `:testing` method.
+Instead of performing real HTTP requests, an array in `TeamsConnector.testing.requests` is filled with your notifications in chronological order.
+
+The request elements have the following structure:
+```ruby
+{
+  channel: :default,
+  template: :facts_card,
+  content: '{"rendered content": "in JSON format"}',
+  time: Time.now
+}
+```
+
+### RSpec Matcher
+TeamsConnector provides the `have_sent_notification_to(channel = nil, template = nil)` matcher for RSpec.
+It is available by adding `require "teams_connector/rspec"` to your `spec_helper.rb`.
+The matcher supports filtering notifications by channel and template. If one is not given, it does not filter the notifications by it.
+There exists the alias `send_notification_to` for `have_sent_notification_to`.
+
+```ruby
+it "has sent exactly one notification to the channel" do
+  expect { notification.deliver_later }.to have_sent_notification_to(:channel)
+end
+```
+
+#### Expecting number of notifications
+By default `have_sent_notification_to` expects exactly one matching notification.
+You can change the expected amount by chaining `exactly`, `at_least` or `at_most`.
+
+Example:
+```ruby
+it "has sent less than 10 notifications to the channel" do
+  expect { notification.deliver_later }.to have_sent_notification_to(:channel).at_most(10)
+end
+```
+
+You can also use `once`, `twice` and `thrice` as an alias for `exactly(1..3)`.
+For more readable expectations `times` can be chained.
+
+#### Expecting templates
+The template argument in the matcher does filter the notifications.
+If you expect a template instead, you can chain with `with_template(:template)`.
+
+#### Expecting content
+To expect specific content, you can chain with `with(data = nil, &block)`.
+Data supports other RSpec matchers like `hash_including`.
+The block is called for every notification with the notification content hash and the raw notification itself.
+
+Example:
+```ruby
+expect {
+  notification(:default, :test_card).deliver_later
+}.to have_sent_notification_to(:default).with { |content, notification|
+  expect(notification[:channel]).to eq :default
+  expect(notification[:template]).to eq :test_card
+  expect(content["sections"]).to include(hash_including("activityTitle", "activitySubtitle", "facts", "markdown" => true))
+}
+```
 ## 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.

data/lib/teams_connector/configuration.rb

@@ -19,7 +19,7 @@ module TeamsConnector
     end
 
     def method=(method)
-      raise ArgumentError, "Method '#{method.to_s}' is not supported" unless [:direct, :sidekiq].include? method
+      raise ArgumentError, "Method '#{method.to_s}' is not supported" unless [:direct, :sidekiq, :testing].include? method
       raise ArgumentError, "Sidekiq is not available" if method == :sidekiq && !defined? Sidekiq
       @method = method
     end
@@ -27,5 +27,16 @@ module TeamsConnector
     def channel(name, url)
       @channels[name] = url;
     end
+
+    def load_from_rails_credentials
+      unless defined? Rails
+        raise RuntimeError, "This method is only available in Ruby on Rails."
+      end
+
+      webhook_urls = Rails.application.credentials.teams_connector!
+      webhook_urls.each do |entry|
+        channel(entry[0], entry[1])
+      end
+    end
   end
 end

data/lib/teams_connector/matchers/have_sent_notification_to.rb

@@ -0,0 +1,163 @@
+module TeamsConnector
+  module Matchers
+    class HaveSentNotificationTo
+      include RSpec::Matchers::Composable
+
+      def initialize(channel, template)
+        @filter = {
+          channel: channel,
+          template: template
+        }
+        @block = proc {}
+        @data = nil
+        @template_data = nil
+        set_expected_number(:exactly, 1)
+      end
+
+      def with(data = nil, &block)
+        @data = data
+        @block = block if block
+        self
+      end
+
+      def with_template(template = nil)
+        @template_data = template
+        self
+      end
+
+      def exactly(count)
+        set_expected_number(:exactly, count)
+        self
+      end
+
+      def at_least(count)
+        set_expected_number(:at_least, count)
+        self
+      end
+
+      def at_most(count)
+        set_expected_number(:at_most, count)
+        self
+      end
+
+      def times
+        self
+      end
+
+      def once
+        exactly(:once)
+      end
+
+      def twice
+        exactly(:twice)
+      end
+
+      def thrice
+        exactly(:thrice)
+      end
+
+      def failure_message
+        "expected to send #{base_message}".tap do |msg|
+          if @unmatching_ntfcts.any?
+            msg << "\nSent notifications"
+            msg << " to #{@filter[:channel]}" if @filter[:channel]
+            msg << " of #{@filter[:template]}" if @filter[:template]
+            msg << ":"
+            @unmatching_ntfcts.each do |data|
+              msg << "\n   #{data}"
+            end
+          end
+        end
+      end
+
+      def failure_message_when_negated
+        "expected not to send #{base_message}"
+      end
+
+      def matches?(expectation)
+        if Proc === expectation
+          original_count = TeamsConnector.testing.requests.size
+          expectation.call
+          in_block_notifications = TeamsConnector.testing.requests.drop(original_count)
+        else
+          in_block_notifications = expectation
+        end
+
+        in_block_notifications = in_block_notifications.select { |msg|
+          @filter.map { |k, v| msg[k] === v unless v.nil? }.compact.all?
+        }
+
+        check(in_block_notifications)
+      end
+
+      def supports_block_expectations?
+        true
+      end
+
+      private
+
+      def check(notifications)
+        @matching_ntfcts, @unmatching_ntfcts = notifications.partition do |ntfct|
+          result = true
+
+          result &= ntfct[:template] == @template_data unless @template_data.nil?
+
+          decoded = JSON.parse(ntfct[:content])
+          if @data.nil? || @data === decoded
+            @block.call(decoded, ntfct)
+            result &= true
+          else
+            result = false
+          end
+
+          result
+        end
+
+        @matching_count = @matching_ntfcts.size
+
+        case @expectation_type
+        when :exactly then @expected_number == @matching_count
+        when :at_most then @expected_number >= @matching_count
+        when :at_least then @expected_number <= @matching_count
+        end
+      end
+
+      def set_expected_number(relativity, count)
+        @expectation_type = relativity
+        @expected_number =
+          case count
+          when :once then 1
+          when :twice then 2
+          when :thrice then 3
+          else Integer(count)
+          end
+      end
+
+      def base_message
+        "#{message_expectation_modifier} #{@expected_number} notifications".tap do |msg|
+          msg << " to #{@filter[:channel]}" if @filter[:channel]
+          msg << " of #{@filter[:template]}" if @filter[:template]
+          msg << " with template #{@template_data}" if @template_data
+          msg << " with content #{data_description(@data)}" if @data
+          msg << ", but sent #{@matching_count}"
+        end
+      end
+
+      def message_expectation_modifier
+        case @expectation_type
+        when :exactly then "exactly"
+        when :at_most then "at most"
+        when :at_least then "at least"
+        end
+      end
+
+      def data_description(data)
+        if RSpec::Support.is_a_matcher?(data) && data.respond_to?(:description)
+          data.description
+        else
+          data
+        end
+      end
+    end
+  end
+end

data/lib/teams_connector/matchers.rb

@@ -0,0 +1,11 @@
+require 'teams_connector/matchers/have_sent_notification_to'
+
+module TeamsConnector
+  module Matchers
+    def have_sent_notification_to(channel = nil, template = nil)
+      HaveSentNotificationTo.new(channel, template)
+    end
+
+    alias_method :send_notification_to, :have_sent_notification_to
+  end
+end

data/lib/teams_connector/notification/adaptive_card.rb

@@ -3,7 +3,7 @@ module TeamsConnector
     attr_accessor :content
 
     def initialize(template: :adaptive_card, content: {}, channel: TeamsConnector.configuration.default)
-      super(template: template, channel: channel)
+      super(template: template, channels: channel)
       if content.instance_of? TeamsConnector::Builder
         @content = {
           card: [content.result]

data/lib/teams_connector/notification/message.rb

@@ -3,7 +3,7 @@ module TeamsConnector
     attr_accessor :summary, :content
 
     def initialize(template, summary, content = {}, channel = TeamsConnector.configuration.default)
-      super(template: template, channel: channel)
+      super(template: template, channels: channel)
       @summary = summary
       @content = content
     end

data/lib/teams_connector/notification.rb

@@ -5,11 +5,11 @@ require 'teams_connector/post_worker' if defined? Sidekiq
 
 module TeamsConnector
   class Notification
-    attr_accessor :template, :channel
+    attr_accessor :template, :channels
 
-    def initialize(template: nil, channel: TeamsConnector.configuration.default)
+    def initialize(template: nil, channels: TeamsConnector.configuration.default)
       @template = template
-      @channel = channel
+      @channels = channels.instance_of?(Array) ? channels : [channels]
     end
 
     def deliver_later
@@ -18,17 +18,21 @@ module TeamsConnector
       renderer = ERB.new(File.read(template_path))
       renderer.location = [template_path.to_s, 0]
 
-      url = TeamsConnector.configuration.channels[@channel]
-      url = TeamsConnector.configuration.channels[TeamsConnector.configuration.default] if TeamsConnector.configuration.always_use_default
-      raise ArgumentError, "The Teams channel '#{@channel}' is not available in the configuration." if url.nil?
-
       content = renderer.result(binding)
 
-      if TeamsConnector.configuration.method == :sidekiq
-        TeamsConnector::PostWorker.perform_async(url, content)
-      else
-        response = Net::HTTP.post(URI(url), content, { "Content-Type": "application/json" })
-        response.value
+      channels = TeamsConnector.configuration.always_use_default ? [TeamsConnector.configuration.default] : @channels
+      channels.each do |channel|
+        url = TeamsConnector.configuration.channels[channel]
+        raise ArgumentError, "The Teams channel '#{channel}' is not available in the configuration." if url.nil?
+
+        if TeamsConnector.configuration.method == :sidekiq
+          TeamsConnector::PostWorker.perform_async(url, content)
+        elsif TeamsConnector.configuration.method == :testing
+          TeamsConnector.testing.perform_request channel, @template, content
+        else
+          response = Net::HTTP.post(URI(url), content, { "Content-Type" => "application/json" })
+          response.value
+        end
       end
     end
 

data/lib/teams_connector/rspec.rb

@@ -0,0 +1,5 @@
+require "teams_connector/matchers"
+
+RSpec.configure do |config|
+  config.include TeamsConnector::Matchers
+end

data/lib/teams_connector/testing.rb

@@ -0,0 +1,13 @@
+module TeamsConnector
+  class Testing
+    attr_reader :requests
+
+    def initialize
+      @requests = []
+    end
+
+    def perform_request(channel, template, content)
+      @requests.push({channel: channel, content: content, template: template, time: Time.now})
+    end
+  end
+end

data/lib/teams_connector/version.rb

@@ -1,3 +1,3 @@
 module TeamsConnector
-  VERSION = "0.1.1"
+  VERSION = "0.1.5"
 end

data/lib/teams_connector.rb

@@ -7,7 +7,7 @@ require 'teams_connector/builder'
 
 module TeamsConnector
   class << self
-    attr_accessor :configuration
+    attr_accessor :configuration, :testing
   end
 
   def self.configuration
@@ -22,6 +22,16 @@ module TeamsConnector
     yield configuration
   end
 
+  def self.testing
+    require 'teams_connector/testing'
+    @testing ||= Testing.new
+  end
+
+  def self.reset_testing
+    require 'teams_connector/testing'
+    @testing = Testing.new
+  end
+
   def self.project_root
     if defined?(Rails)
       return Rails.root

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: teams_connector
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.5
 platform: ruby
 authors:
 - Lucas Keune
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-11-15 00:00:00.000000000 Z
+date: 2021-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -117,10 +117,14 @@ files:
 - lib/teams_connector.rb
 - lib/teams_connector/builder.rb
 - lib/teams_connector/configuration.rb
+- lib/teams_connector/matchers.rb
+- lib/teams_connector/matchers/have_sent_notification_to.rb
 - lib/teams_connector/notification.rb
 - lib/teams_connector/notification/adaptive_card.rb
 - lib/teams_connector/notification/message.rb
 - lib/teams_connector/post_worker.rb
+- lib/teams_connector/rspec.rb
+- lib/teams_connector/testing.rb
 - lib/teams_connector/version.rb
 - teams_connector.gemspec
 - templates/teams_connector/adaptive_card.json.erb