kapnismology 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 85d68c903e5f1bf29d11c3f1ecb0a3a7c850cd9e
-  data.tar.gz: 4a43dfe929d8e04456ff17d792ec2eb2ca2b3f7a
+  metadata.gz: a71f19f3000d41004864b28c10f41b3f147f7868
+  data.tar.gz: fa3dcaeda42ddb19d05bcfc0b308cbf8bef70327
 SHA512:
-  metadata.gz: a0c11e4d88f89b3b8f49c30d76493103c053f9a8ecd0015b42dd0ad12bf3ce80e43176c3295a02c5bf2d23863873e2c78585031d9e480c3a1f9f2e347d2d9b70
-  data.tar.gz: 83465c018ce7ee7c1ea6c446a61d52b67a677e8edbfbb838bb40d8eccc3fb67b9b0395a2dd7d1fcfb2bb32050ccff087eb39fbe83e15c2c54cf0fdad1c9d4a56
+  metadata.gz: 05350329b7cbfac2f6dc72a30a44dc6f168cb0f23b64324d6d85c87b1353144b886945d7c4608e6f2fc08fe27da7aa9d7b944f78a14b53447452f47dc32ddff1
+  data.tar.gz: f6c7a55968f13f3ca421696cfaa1ac45bfd34d20a4345e582a50ce8f7dc76ba755aabd9de9779d1506036672938b09ac8abd163acde779fd77e19caa5c94717f

data/README.md

@@ -1,13 +1,12 @@
 # Kapnismology
 
-Kapnismology 'the study of smoke', is a gem which contains an engine to easily create smoke tests.
+Kapnismology 'the study of smoke', is a gem containing a Rails engine to easily create smoke tests.
 
 ## Installation
 
-Kapnismology only supports Rails.
 In the Gemfile write:
 ```
-gem 'kapnismology', '~> 1.2'
+gem 'kapnismology', '~> 1.7'
 ```
 
 In your config/routes write:
@@ -28,17 +27,26 @@ Create a class like this:
 class MySmokeTest < Kapnismology::SmokeTest
 
   def result
-    Kapnismology::Result.new(true, {connection: 'good'}, "Connected!")
+    Success.new({connection: 'good'}, "Connected!")
   end
 end
 ```
 
 The class must:
 - Inherit from `Kapnismology::SmokeTest`
-- Have an instance method `result` returning a Kapnismology::Result object
+- Have an instance method `result` returning a Result or Success object
 
-Any class created this way will be called and its result will be added to a resulting hash.
-In this case the result of this class would be added to the result as:
+A test passes if it returns:
+`Result.new(true, data, message)` or
+`Success.new(data, message)`
+
+A test fails if it returns:
+`Result.new(false, data, message)` or
+`raise SmokeTestFailed.new(data, message)`
+
+
+Any class created this way will be called and its result will be merged with other results.
+In the example above the result of this class would be added to the results as:
 ```
 {'MySmokeTest': { passed: true, data: { connection: 'good' }, message: 'Connected!' }}
 ```
@@ -46,19 +54,35 @@ In this case the result of this class would be added to the result as:
 ## Loading tests
 
 Kapnismology will find any class which inherits from `Kapnismology::SmokeTest` in memory.
-Kapnismology will require all the files inside `lib/smoke_test`.
+Kapnismology will require all the files in your project in the path `lib/smoke_test`.
 If for any reason you want to have your test in any other location, then you will need to make sure they are properly required.
 
 ## Naming
 
-If you want to change the name of the test, define `self.name` in your
-smoke test class.
+If you want to change the name tests are reported in the final result, define `self.name` in your smoke test class.
+
+```ruby
+class MySmokeTest < Kapnismology::SmokeTest
+  def self.name
+    'Database smoke test'
+  end
+  def result
+    Success.new({connection: 'good'}, "Connected!")
+  end
+end
+```
+
+Will produce:
+```ruby
+{'Database smoke test': { passed: true, data: { connection: 'good' }, message: 'Connected!' }}
+
+```
 
 ## Not runnable tests
 
-If your test find a situation when it does not make sense, then you can return a `Kapnismology::NullResult` instead of a `Kapnismology::Result`. Like:
+If your test find a situation when it does not make sense, then you can return a `NullResult` instead of a `Result`. Like:
 ```
-if (File.exist?('that file'))
+if (File.exist?('necessary file'))
   Result.new(....)
 else
   NullResult.new
@@ -71,14 +95,14 @@ NullResult do not need any parameter but you can optionally pass a message.
 ## Tagging and running tags
 
 All smoke tests are tagged by default with 'deployment' and 'runtime'.
-If you want to tag your test with any one of the above or any other tag, just overwrite the `self.categories` method in your smoke test class.
+If you want to tag your test with any one of the above or any other tag, just overwrite the `self.tags` method in your smoke test class.
 The following example creates a smoke test tagged with the tags 'slow' and 'integration'.
 
 ```Ruby
 class ExpensiveTest < Kapnismology::SmokeTest
   def result
   end
-  def self.categories
+  def self.tags
     ['slow', 'integration']
   end
 end
@@ -88,7 +112,7 @@ When you call the URL, all smoke tests marked with 'runtime' will be run. As by
 
 The above smoke test as it has not the 'runtime' category, it will not be run. To run it you should call your service like this:
 ```
- wget http://myservice.com/smoke_test?tags=integration_
+ wget http://myservice.com/smoke_test?tags=integration
 ```
 
 It will run all your integration tests. You can run it together with your runtime tests also:
@@ -102,9 +126,37 @@ It will run all your integration tests. You can run it together with your runtim
 If you want to skip some smoke test when you call the URL then you can add the 'skip' query parameter to the URL indicating the tests you want to skip.
 For instance:
 ```
- wget http://myservice.com/smoke_test?skip=ToNotBeCalled,NeitherCallThis_
+ wget http://myservice.com/smoke_test?skip=ToNotBeCalled,NeitherCallThis
+```
+
+## Recommended coding style
+
+Hopefully Kapnismology is flexible enough so you can code your smoke test as you prefer, our recommended style is this:
+
+```
+def result
+  user = user_from_remote
+  puts_to_result('User successfully retrieved')
+
+  role = role_from_remote(user)
+  puts_to_result('Role for the user retrieved')
+
+  if check_permissions(user, role)
+    Result.new(true, {user: user, role: role}, "Permissions are properly set")
+  else
+    Result.new(false, {user: user, role: role}, "Permissions failed")
+  end
+end
+
+def user_from_remote
+  get_user
+rescue => e
+  raise SmokeTestFailed.new({class: e.class, message: e.message}, "Error raised when accessing user")
+end
+ ...
 ```
 
+Using small methods that raise SmokeTestFailed when failed will help you write an easy to read `result` method.
 
 
 ## TODO

data/app/controllers/kapnismology/smoke_tests_controller.rb

@@ -3,7 +3,7 @@ module Kapnismology
   # smoke tests registered in the application and gather the results
   class SmokeTestsController < ApplicationController
     def index
-      evaluations = SmokeTest.evaluations(allowed_tags, blacklist)
+      evaluations = SmokeTestCollection.evaluations(allowed_tags, blacklist)
       render text: evaluations.to_json, status: status(evaluations)
     end
 

data/lib/kapnismology.rb

@@ -5,3 +5,4 @@ require 'kapnismology/evaluation'
 require 'kapnismology/evaluation_collection'
 require 'kapnismology/rake_task'
 require 'kapnismology/smoke_test'
+require 'kapnismology/smoke_test_collection'

data/lib/kapnismology/engine.rb

@@ -3,10 +3,10 @@ module Kapnismology
   begin
     # Rails engine to automatically load our code and smoke tests libraries
     class Engine < ::Rails::Engine
-      initializer 'kapnismology.add_autoload_paths', before: :set_autoload_paths do |app|
+      initializer 'kapnismology.add_autoload_paths', before: :set_autoload_paths do |_app|
         smoketest_dir = Rails.root.join('lib', 'smoke_test')
         if smoketest_dir.exist?
-          Dir[File.join(smoketest_dir, '*.rb')].each {|file| require file }
+          Dir[File.join(smoketest_dir, '*.rb')].each { |file| require file }
         end
       end
 

data/lib/kapnismology/evaluation.rb

@@ -2,11 +2,11 @@ require 'json'
 require 'kapnismology/terminal'
 
 module Kapnismology
-  # Mapping of test_name => result for each smoke test
+  # Mapping of test_name => returned result for each smoke test
   class Evaluation
     def initialize(test_class)
       @name = test_class.name.split('::').last
-      @result = test_class.new.result || unavailable_result
+      @result = test_class.new.__result__ || unavailable_result
     end
 
     def passed?
@@ -22,11 +22,7 @@ module Kapnismology
     end
 
     def to_s
-<<-eos
-The smoke test #{@name} #{passed_or_failed_text}
-  #{@result.message}
-#{@result.to_hash[:data]}
-eos
+      @result.to_s(@name)
     end
 
     private
@@ -34,9 +30,5 @@ eos
     def unavailable_result
       Result.new(false, {}, 'This test has not returned any result.')
     end
-
-    def passed_or_failed_text
-      passed? ? Terminal.green('passed') : Terminal.red('failed')
-    end
   end
 end

data/lib/kapnismology/evaluation_collection.rb

@@ -20,7 +20,7 @@ module Kapnismology
     end
 
     def to_json
-      evaluations.delete_if{ |evaluation| evaluation.null_result? }.to_json
+      evaluations.delete_if(&:null_result?).to_json
     end
 
     private

data/lib/kapnismology/rake_task.rb

@@ -2,7 +2,7 @@ require 'kapnismology/terminal'
 module Kapnismology
   class RakeTask
     def output
-      evaluations = SmokeTest.evaluations
+      evaluations = SmokeTestCollection.evaluations
       puts
       puts
       evaluations.each do |evaluation|

data/lib/kapnismology/result.rb

@@ -1,38 +1,77 @@
 module Kapnismology
+  # This is the base class for all types of results.
+  # It is useful to be able to test if the object is of a correct result type.
+  # It also have methods to add information and serialize it.
+  class BaseResult
+    def to_hash
+      { passed: passed?, data: @data, message: @message, extra_messages: @extra_messages }
+    end
+
+    def to_s(name)
+      <<-eos
+#{format_passed(passed?)}: #{name}
+#{format_extra_messages(@extra_messages)}#{Terminal.bold(@message)}
+   #{@data}
+eos
+    end
+
+    def add_extra_messages(messages)
+      @extra_messages = (messages || []).compact.flatten
+      self
+    end
+
+    def passed?
+      !!@passed
+    end
+
+    private
+
+    def format_extra_messages(extra_messages)
+      if extra_messages.empty?
+        ''
+      else
+        extra_messages.join("\n") + "\n"
+      end
+    end
+
+    def format_passed(passed)
+      passed ? Terminal.green('passed') : Terminal.red('failed')
+    end
+  end
+
   # This is the result of each smoke test.
   # This class makes sense to enforce smoke test to return something known
   # Params of the constructor:
   # * passed : Boolean: true -> test passed, false -> test failed
   # * data   : Typically Array or Hash representing the result of the test
   # * message: String with an extra message to provide human readable information
-  class Result
-    attr_reader :data, :message
-
+  class Result < BaseResult
     def initialize(passed, data, message)
       raise ArgumentError, 'passed must be true or false' unless !!passed == passed
       @passed = passed
       @data = data
       @message = message
+      @extra_messages = []
     end
+  end
 
-    def passed?
-      !!@passed
-    end
-
-    def to_hash
-      { passed: passed?, data: @data, message: @message }
+  class NullResult < BaseResult
+    def initialize(data, message = 'The result could not be determined')
+      @passed = true
+      @data = data
+      @message = message
+      @extra_messages = []
     end
   end
 
   # Use this class when your test is not valid in the current situation
   # For instance when you have a test for deployments that have not happen, etc.
-  class NullResult
-    attr_reader :message
-    def initialize(message = 'The result could not be determined')
+  class Success < BaseResult
+    def initialize(data, message)
+      @passed = true
+      @data = data
       @message = message
-    end
-    def passed?
-      true
+      @extra_messages = []
     end
   end
 end

data/lib/kapnismology/smoke_test.rb

@@ -1,5 +1,5 @@
 require 'kapnismology/result'
-require 'kapnismology/evaluation_collection'
+require 'kapnismology/smoke_test_collection'
 
 module Kapnismology
   #
@@ -11,28 +11,33 @@ module Kapnismology
     RUNTIME_TAG = 'runtime'.freeze
     DEFAULT_TAGS = [DEPLOYMENT_TAG, RUNTIME_TAG].freeze
 
-    def result
-      raise 'this method has to be implemented in inherited classes'
+    # Default constructor may be overwritten by child class
+    def initialize
+      @all_result_messages = []
     end
 
-    class << self
-      def inherited(klass)
-        smoke_tests << klass
-      end
+    def result
+
+    end
 
-      def smoke_tests
-        @smoke_tests ||= []
+    def __result__
+      result_object = result
+      unless result_object.is_a?(Kapnismology::BaseResult)
+        message = "Smoke test #{self.class}, returned #{result_object.class} instead of a Result"
+        result_object = Result.new(false, { returned_class: result_object.class }, message)
       end
+    rescue SmokeTestFailed => e
+      result_object = e.result
+    rescue => e
+      message = "Unrescued error happened in #{self.class}"
+      result_object = Result.new(false, { exception: e.class, message: e.message }, message)
+    ensure
+      return result_object.add_extra_messages(@all_result_messages)
+    end
 
-      def evaluations(allowed_tags=[RUNTIME_TAG], blacklist=[])
-        # We will run any class which categories are in the allowed list
-        # and not blacklisted
-        runable_tests = smoke_tests.select do |test|
-          klass_name = test.name.split('::').last
-          !blacklist.include?(klass_name) &&
-            !(allowed_tags & test.tags).empty?
-        end
-        EvaluationCollection.new(runable_tests)
+    class << self
+      def inherited(klass)
+        SmokeTestCollection.add_smoke_test(klass)
       end
 
       def tags
@@ -40,13 +45,29 @@ module Kapnismology
       end
     end
 
-    private
+    protected
+
+    def puts_to_result(message)
+      @all_result_messages ||= []
+      @all_result_messages.push(message)
+    end
 
     # These classes makes it very simple to implementors of results to use them without the module name
     class Result < Kapnismology::Result
     end
     class NullResult < Kapnismology::NullResult
     end
+    class Success < Kapnismology::Success
+    end
 
+    class SmokeTestFailed < StandardError
+      def initialize(data, message)
+        @data = data
+        @message = message
+      end
+      def result
+        Kapnismology::Result.new(false, @data, @message)
+      end
+    end
   end
 end

data/lib/kapnismology/smoke_test_collection.rb

@@ -0,0 +1,28 @@
+require 'kapnismology/evaluation_collection'
+
+module Kapnismology
+
+  # This class maintains the collection of all the smoke tests found in the system
+  class SmokeTestCollection
+    class << self
+      def add_smoke_test(klass)
+        smoke_tests << klass
+      end
+
+      def smoke_tests
+        @smoke_tests ||= []
+      end
+
+      def evaluations(allowed_tags = [SmokeTest::RUNTIME_TAG], blacklist = [])
+        # We will run any class which categories are in the allowed list
+        # and not blacklisted
+        runable_tests = smoke_tests.select do |test|
+          klass_name = test.name.split('::').last
+          !blacklist.include?(klass_name) &&
+            !(allowed_tags & test.tags).empty?
+        end
+        EvaluationCollection.new(runable_tests)
+      end
+    end
+  end
+end

data/lib/kapnismology/terminal.rb

@@ -3,8 +3,13 @@ module Kapnismology
     def self.green(msg)
       "\e[32m\e[1m#{msg}\e[0m"
     end
+
     def self.red(msg)
       "\e[31m\e[1m#{msg}\e[0m"
     end
+
+    def self.bold(msg)
+      "\e[1m#{msg}\e[0m"
+    end
   end
 end

data/lib/kapnismology/version.rb

@@ -1,3 +1,3 @@
 module Kapnismology
-  VERSION = '1.6.0'.freeze
+  VERSION = '1.7.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kapnismology
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Jordi Polo Carres
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-04 00:00:00.000000000 Z
+date: 2016-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '3.4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '3.4'
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement
@@ -154,6 +154,7 @@ files:
 - lib/kapnismology/rake_task.rb
 - lib/kapnismology/result.rb
 - lib/kapnismology/smoke_test.rb
+- lib/kapnismology/smoke_test_collection.rb
 - lib/kapnismology/terminal.rb
 - lib/kapnismology/version.rb
 homepage: https://www.github.com/JordiPolo/kapnismology