allure-ruby-commons 2.13.1 → 2.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a9115fbeeca5e229495d548047fa91edac5cb364a3a18c629f7d860fff43b3c
-  data.tar.gz: 302ce724cd87c8c8a392687355c693774e40e0dfeb6d00cc4e67c5202a2dd733
+  metadata.gz: b90157e53cb38a4fa6703c63cb675f75f85291f886c97fc7825ed33a5cbaff28
+  data.tar.gz: 3a4aff315c87fbdaa55709505dd629c731350ef01874f67e8a58cb0b08be2c09
 SHA512:
-  metadata.gz: 7392a3abf6e355d4e1a7e1dfddca5c39c68ffe89549eaf72db2a0e7e4793c4019e7f2dfb5877c82be92775476ac70349218e1c85087ed17aa7374a0d6c461beb
-  data.tar.gz: 9a263ffc1763bbb4647c5341259bf12f6e8e766feb026fc4f7fae41c51b109609b64b410baaadb0080f9bd07edfccb113ffb47553e5ddbf7632770188ed8190a
+  metadata.gz: ee87093a5030d0037ae10799ad0ea26247f90c7ffef686f2029356886cab173e7a5fd379d831f77fb0879d53b5321bdec8e39cd08c201dcb084c33435a16890b
+  data.tar.gz: 23921b2da0d5397f872f23e7fcaaf649f5d6f03caa5602f85821cd4f383eb8d7ef5fc4e9c90a7542ea734351605467ae8c09b04c303964a80c6e93f1b17c4831

data/README.md

@@ -1,5 +1,7 @@
 # Allure Ruby Adaptor API
 
+[![Yard Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/gems/allure-ruby-commons)
+
 This is a helper library containing the basics for any ruby-based Allure adaptor.
 Using it you can easily implement the adaptor for your favorite ruby testing library or
 you can just create the report of any other kind using the basic Allure terms.
@@ -9,7 +11,7 @@ you can just create the report of any other kind using the basic Allure terms.
 Add the dependency to your Gemfile
 
 ```ruby
- gem 'allure-ruby-commons'
+ gem "allure-ruby-commons"
 ```
 
 ## Configuration
@@ -17,13 +19,16 @@ Add the dependency to your Gemfile
 Following configuration options are supported:
 
 ```ruby
-    Allure.configure do |c|
-      c.results_directory = "/whatever/you/like"
-      c.clean_results_directory = true
-      c.logging_level = Logger::INFO
+    Allure.configure do |config|
+      config.results_directory = "report/allure-results"
+      config.clean_results_directory = true
+      config.logging_level = Logger::INFO
+      config.logger = Logger.new($stdout, Logger::DEBUG)
+      config.environment = "staging"
+
       # these are used for creating links to bugs or test cases where {} is replaced with keys of relevant items
-      c.link_tms_pattern = "http://www.jira.com/browse/{}"
-      c.link_issue_pattern = "http://www.jira.com/browse/{}"
+      config.link_tms_pattern = "http://www.jira.com/browse/{}"
+      config.link_issue_pattern = "http://www.jira.com/browse/{}"
     end
 ```
 
@@ -33,6 +38,17 @@ Getting the configuration object:
 Allure.configuration
 ```
 
+### Allure environment
+
+It is possible to set up custom allure environment which will be used to prefix test case names. This is useful if you run same tests on different environments and generate single report. This way different runs are not put as retry. Environment can be configured in following ways:
+
+* via `ALLURE_ENVIRONMENT` environment variable
+* via `configure` method
+
+### Log level
+
+Log level can be also configured via environment variable `ALLURE_LOG_LEVEL` which accepts one of the following values: `DEBUG INFO WARN ERROR FATAL UNKNOWN`.
+
 ## Allure lifecycle
 
 Reports are built using API defined in AllureLifecycle class and using allure specific entities defined in models.
@@ -48,6 +64,23 @@ Allure.add_attachment(name: "attachment", source: "/path/to/test.txt", type: All
 Allure.add_link(name: "Custom Url", url: "http://www.github.com")
 ```
 
+## Steps
+
+It is possible to mark method definitions to be automatically added to report as steps. The class just needs to extend `AllureStepAnnotation`
+and `step` method needs to be used before the method definition.
+
+```ruby
+class TestHelper
+  extend AllureStepAnnotation
+
+  step("Singleton step")
+  def self.class_method; end
+
+  step("Standard step")
+  def standard_method; end
+end
+```
+
 ## Testing
 
 Install dependencies:

data/lib/allure-ruby-commons.rb

@@ -3,166 +3,205 @@
 
 require "require_all"
 require "uuid"
+
 require_rel "allure_ruby_commons/**/*rb"
 
 # Namespace for classes that handle allure report generation and different framework adaptors
 module Allure
-  class << self
-    # Get thread specific allure lifecycle object
-    # @return [Allure::AllureLifecycle]
-    def lifecycle
-      Thread.current[:lifecycle] ||= AllureLifecycle.new
-    end
+  # Set lifecycle object
+  # @param [AllureLifecycle] lifecycle
+  # @return [void]
+  def self.lifecycle=(lifecycle)
+    Thread.current[:lifecycle] = lifecycle
+  end
 
-    # Set lifecycle object
-    # @param [Allure::AllureLifecycle] lifecycle
-    # @return [void]
-    def lifecycle=(lifecycle)
-      Thread.current[:lifecycle] = lifecycle
-    end
+  extend self # rubocop:disable Style/ModuleFunction
 
-    # Get allure configuration
-    # @return [Allure::Config]
-    def configuration
-      Config
-    end
+  # Get thread specific allure lifecycle object
+  # @return [AllureLifecycle]
+  def lifecycle
+    Thread.current[:lifecycle] ||= AllureLifecycle.new
+  end
 
-    # Set allure configuration
-    # @yieldparam [Allure::Config]
-    # @yieldreturn [void]
-    # @return [void]
-    def configure
-      yield(Config)
-    end
+  # Get allure configuration
+  # @return [Config]
+  def configuration
+    Config.instance
+  end
 
-    # Add epic to current test case
-    # @param [String] value
-    # @return [void]
-    def epic(value)
-      label(ResultUtils::EPIC_LABEL_NAME, value)
-    end
+  # Set allure configuration
+  # @yieldparam [Config]
+  # @yieldreturn [void]
+  # @return [void]
+  def configure
+    yield(configuration)
+  end
 
-    # Add feature to current test case
-    # @param [String] value
-    # @return [void]
-    def feature(value)
-      label(ResultUtils::FEATURE_LABEL_NAME, value)
-    end
+  # Add epic to current test case
+  # @param [String] value
+  # @return [void]
+  def epic(value)
+    replace_label(ResultUtils::EPIC_LABEL_NAME, value)
+  end
 
-    # Add story to current test case
-    # @param [String] value
-    # @return [void]
-    def story(value)
-      label(ResultUtils::STORY_LABEL_NAME, value)
-    end
+  # Add feature to current test case
+  # @param [String] value
+  # @return [void]
+  def feature(value)
+    replace_label(ResultUtils::FEATURE_LABEL_NAME, value)
+  end
 
-    # Add suite to current test case
-    # @param [String] value
-    # @return [void]
-    def suite(value)
-      label(ResultUtils::SUITE_LABEL_NAME, value)
-    end
+  # Add story to current test case
+  # @param [String] value
+  # @return [void]
+  def story(value)
+    replace_label(ResultUtils::STORY_LABEL_NAME, value)
+  end
 
-    # Add label to current test case
-    # @param [String] name
-    # @param [String] value
-    # @return [void]
-    def label(name, value)
-      lifecycle.update_test_case do |test_case|
-        test_case.labels.push(Label.new(name, value))
-      end
-    end
+  # Add suite to current test case
+  # @param [String] value
+  # @return [void]
+  def suite(value)
+    replace_label(ResultUtils::SUITE_LABEL_NAME, value)
+  end
 
-    # Add description to current test case
-    # @param [String] description
-    # @return [void]
-    def add_description(description)
-      lifecycle.update_test_case do |test_case|
-        test_case.description = description
-      end
-    end
+  # Add tag to current test case
+  # @param [String] value
+  # @return [void]
+  def tag(value)
+    label(ResultUtils::TAG_LABEL_NAME, value)
+  end
 
-    # Add html description to current test case
-    # @param [String] description_html
-    # @return [void]
-    def description_html(description_html)
-      lifecycle.update_test_case do |test_case|
-        test_case.description_html = description_html
-      end
+  # Add label to current test case
+  # @param [String] name
+  # @param [String] value
+  # @return [void]
+  def label(name, value)
+    lifecycle.update_test_case do |test_case|
+      test_case.labels.push(Label.new(name, value))
     end
+  end
 
-    # Add parameter to current test case
-    # @param [String] name
-    # @param [String] value
-    # @return [void]
-    def parameter(name, value)
-      lifecycle.update_test_case do |test_case|
-        test_case.parameters.push(Parameter.new(name, value))
-      end
-    end
+  # Replace label in current test case
+  #
+  # @param [String] name
+  # @param [String] value
+  # @return [void]
+  def replace_label(name, value)
+    lifecycle.update_test_case do |test_case|
+      present = test_case.labels.detect { |l| l.name == name }
+      return label(name, value) unless present
 
-    # Add tms link to current test case
-    # @param [String] name
-    # @param [String] url
-    # @return [void]
-    def tms(name, url)
-      add_link(name: name, url: url, type: ResultUtils::TMS_LINK_TYPE)
+      test_case.labels.map! { |l| l.name == name ? Label.new(name, value) : l }
     end
+  end
 
-    # Add issue linkt to current test case
-    # @param [String] name
-    # @param [String] url
-    # @return [void]
-    def issue(name, url)
-      add_link(name: name, url: url, type: ResultUtils::ISSUE_LINK_TYPE)
+  # Add description to current test case
+  # @param [String] description
+  # @return [void]
+  def add_description(description)
+    lifecycle.update_test_case do |test_case|
+      test_case.description = description
     end
+  end
 
-    # Add link to current test case
-    # @param [String ] url
-    # @param [String] name
-    # @param [String] type type of the link used to display link icon
-    # @return [void]
-    def add_link(url:, name: nil, type: "custom")
-      lifecycle.update_test_case do |test_case|
-        test_case.links.push(Link.new(type, name || url, url))
-      end
+  # Add html description to current test case
+  # @param [String] description_html
+  # @return [void]
+  def description_html(description_html)
+    lifecycle.update_test_case do |test_case|
+      test_case.description_html = description_html
     end
+  end
 
-    # Add attachment to current test case or step
-    # @param [String] name Attachment name
-    # @param [File, String] source File or string to save as attachment
-    # @param [String] type attachment type defined in {Allure::ContentType} or any other valid mime type
-    # @param [Boolean] test_case add attachment to current test case instead of test step
-    # @return [void]
-    def add_attachment(name:, source:, type:, test_case: false)
-      lifecycle.add_attachment(name: name, source: source, type: type, test_case: test_case)
+  # Add parameter to current test case
+  # @param [String] name
+  # @param [String] value
+  # @return [void]
+  def parameter(name, value)
+    lifecycle.update_test_case do |test_case|
+      test_case.parameters.push(Parameter.new(name, value))
     end
+  end
 
-    # Add step with provided name and optional status to current test step, fixture or test case
-    # @param [String] name
-    # @param [Symbol] status <Allure::Status>, <Allure::Status::PASSED> by default
-    # @return [void]
-    def step(name:, status: nil)
-      lifecycle.add_test_step(StepResult.new(name: name, status: status || Status::PASSED, stage: Stage::FINISHED))
-    end
+  # Add tms link to current test case
+  # @param [String] name
+  # @param [String] url
+  # @return [void]
+  def tms(name, url)
+    add_link(name: name, url: url, type: ResultUtils::TMS_LINK_TYPE)
+  end
+
+  # Add issue linkt to current test case
+  # @param [String] name
+  # @param [String] url
+  # @return [void]
+  def issue(name, url)
+    add_link(name: name, url: url, type: ResultUtils::ISSUE_LINK_TYPE)
+  end
 
-    # Run passed block as step with given name
-    # @param [String] name
-    # @yield [] step block
-    # @return [void]
-    def run_step(name)
-      lifecycle.start_test_step(StepResult.new(name: name, stage: Stage::RUNNING))
-      yield
-      lifecycle.update_test_step { |step| step.status = Status::PASSED }
-    rescue => e
-      lifecycle.update_test_step do |step|
-        step.status = ResultUtils.status(e)
-        step.status_details = ResultUtils.status_details(e)
-      end
-      raise(e)
-    ensure
-      lifecycle.stop_test_step
+  # Add link to current test case
+  # @param [String ] url
+  # @param [String] name
+  # @param [String] type type of the link used to display link icon
+  # @return [void]
+  def add_link(url:, name: nil, type: "custom")
+    lifecycle.update_test_case do |test_case|
+      test_case.links.push(Link.new(type, name || url, url))
     end
   end
+
+  # Add attachment to current test case or step
+  # @param [String] name Attachment name
+  # @param [File, String] source File or string to save as attachment
+  # @param [String] type attachment type defined in {ContentType} or any other valid mime type
+  # @param [Boolean] test_case add attachment to current test case instead of test step
+  # @return [void]
+  def add_attachment(name:, source:, type:, test_case: false)
+    lifecycle.add_attachment(name: name, source: source, type: type, test_case: test_case)
+  end
+
+  # Add allure report environment info
+  # @param [Hash<Symbol, String>] environment
+  # @return [void]
+  def add_environment(environment)
+    lifecycle.write_environment(environment)
+  end
+
+  # Add categories info
+  # @param [File, Array<Category>] categories
+  # @return [void]
+  def add_categories(categories)
+    lifecycle.write_categories(categories)
+  end
+
+  # Add step with provided name and optional status to current test step, fixture or test case
+  # @param [String] name
+  # @param [Symbol] status {Status}, {Status::PASSED} by default
+  # @return [void]
+  def step(name:, status: nil)
+    lifecycle.add_test_step(StepResult.new(name: name, status: status || Status::PASSED, stage: Stage::FINISHED))
+    lifecycle.stop_test_step
+  end
+
+  # Run passed block as step with given name and return result of yield
+  # @param [String] name
+  # @yield [] step block
+  # @return [Object]
+  def run_step(name)
+    lifecycle.start_test_step(StepResult.new(name: name, stage: Stage::RUNNING))
+    result = yield
+    lifecycle.update_test_step { |step| step.status = Status::PASSED }
+
+    result
+  rescue StandardError => e
+    lifecycle.update_test_step do |step|
+      step.status = ResultUtils.status(e)
+      step.status_details = ResultUtils.status_details(e)
+    end
+    raise(e)
+  ensure
+    lifecycle.stop_test_step
+  end
 end
 # rubocop:enable Naming/FileName

data/lib/allure_ruby_commons/allure_lifecycle.rb

@@ -1,20 +1,35 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "forwardable"
 
 module Allure
   # Main class for creating and writing allure results
-  class AllureLifecycle
-    def initialize
+  class AllureLifecycle # rubocop:disable Metrics/ClassLength
+    extend Forwardable
+
+    # Allure lifecycle instance
+    #
+    # @param [Allure::Config] configuration
+    def initialize(config = Config.instance)
       @test_context = []
       @step_context = []
+      @config = config
+      @logger = config.logger
+      @file_writer = FileWriter.new(config.results_directory)
     end
 
+    attr_reader :config
+
+    def_delegators :file_writer, :write_attachment, :write_environment, :write_categories
+
     # Start test result container
     # @param [Allure::TestResultContainer] test_result_container
     # @return [Allure::TestResultContainer]
     def start_test_container(test_result_container)
       test_result_container.tap do |container|
+        logger.debug { "Starting test container: #{container.name}" }
+
         container.start = ResultUtils.timestamp
         @test_context.push(container)
       end
@@ -29,7 +44,7 @@ module Allure
     # @return [void]
     def update_test_container
       unless current_test_result_container
-        return logger.error("Could not update test container, no container is running.")
+        return logger.error { "Could not update test container, no container is running." }
       end
 
       yield(current_test_result_container)
@@ -39,10 +54,11 @@ module Allure
     # @return [void]
     def stop_test_container
       unless current_test_result_container
-        return logger.error("Could not stop test container, no container is running.")
+        return logger.error { "Could not stop test container, no container is running." }
       end
 
       current_test_result_container.tap do |container|
+        logger.debug { "Stopping container: #{container.name}" }
         container.stop = ResultUtils.timestamp
         file_writer.write_test_result_container(container)
         clear_last_test_container
@@ -55,9 +71,10 @@ module Allure
     def start_test_case(test_result)
       clear_step_context
       unless current_test_result_container
-        return logger.error("Could not start test case, test container is not started")
+        return logger.error { "Could not start test case, test container is not started" }
       end
 
+      logger.debug("Starting test case: #{test_result.name}")
       test_result.start = ResultUtils.timestamp
       test_result.stage = Stage::RUNNING
       test_result.labels.push(ResultUtils.thread_label, ResultUtils.host_label, ResultUtils.language_label)
@@ -73,7 +90,7 @@ module Allure
     # @yieldreturn [void]
     # @return [void]
     def update_test_case
-      return logger.error("Could not update test case, no test case running") unless @current_test_case
+      return logger.error { "Could not update test case, no test case running" } unless @current_test_case
 
       yield(@current_test_case)
     end
@@ -81,8 +98,9 @@ module Allure
     # Stop current test case and write result
     # @return [void]
     def stop_test_case
-      return logger.error("Could not stop test case, no test case is running") unless @current_test_case
+      return logger.error { "Could not stop test case, no test case is running" } unless @current_test_case
 
+      logger.debug { "Stopping test case: #{@current_test_case.name}" }
       @current_test_case.stop = ResultUtils.timestamp
       @current_test_case.stage = Stage::FINISHED
       file_writer.write_test_result(@current_test_case)
@@ -94,8 +112,9 @@ module Allure
     # @param [Allure::StepResult] step_result
     # @return [Allure::StepResult]
     def start_test_step(step_result)
-      return logger.error("Could not start test step, no test case is running") unless @current_test_case
+      return logger.error { "Could not start test step, no test case is running" } unless @current_test_case
 
+      logger.debug { "Starting test step: #{step_result.name}" }
       step_result.start = ResultUtils.timestamp
       step_result.stage = Stage::RUNNING
       add_test_step(step_result)
@@ -110,7 +129,7 @@ module Allure
     # @yieldreturn [void]
     # @return [void]
     def update_test_step
-      return logger.error("Could not update test step, no step is running") unless current_test_step
+      return logger.error { "Could not update test step, no step is running" } unless current_test_step
 
       yield(current_test_step)
     end
@@ -118,8 +137,9 @@ module Allure
     # Stop current test step
     # @return [void]
     def stop_test_step
-      return logger.error("Could not stop test step, no step is running") unless current_test_step
+      return logger.error { "Could not stop test step, no step is running" } unless current_test_step
 
+      logger.debug { "Stopping test step: #{current_test_step.name}" }
       current_test_step.stop = ResultUtils.timestamp
       current_test_step.stage = Stage::FINISHED
       clear_last_test_step
@@ -153,6 +173,7 @@ module Allure
         return false
       end
 
+      logger.debug { "Starting fixture: #{fixture_result.name}" }
       fixture_result.start = ResultUtils.timestamp
       fixture_result.stage = Stage::RUNNING
     end
@@ -165,7 +186,7 @@ module Allure
     # @yieldreturn [void]
     # @return [void]
     def update_fixture
-      return logger.error("Could not update fixture, fixture is not started") unless @current_fixture
+      return logger.error { "Could not update fixture, fixture is not started" } unless @current_fixture
 
       yield(@current_fixture)
     end
@@ -173,8 +194,9 @@ module Allure
     # Stop current test fixture
     # @return [void]
     def stop_fixture
-      return logger.error("Could not stop fixture, fixture is not started") unless @current_fixture
+      return logger.error { "Could not stop fixture, fixture is not started" } unless @current_fixture
 
+      logger.debug { "Stopping fixture: #{@current_fixture.name}" }
       @current_fixture.stop = ResultUtils.timestamp
       @current_fixture.stage = Stage::FINISHED
       clear_current_fixture
@@ -188,32 +210,15 @@ module Allure
     # @param [Boolean] test_case add attachment to current test case
     # @return [void]
     def add_attachment(name:, source:, type:, test_case: false)
-      attachment = prepare_attachment(name, type) || begin
-        return logger.error("Can't add attachment, unrecognized mime type: #{type}")
-      end
-      executable_item = (test_case && @current_test_case) || current_executable
-      executable_item&.attachments&.push(attachment) || begin
-        return logger.error("Can't add attachment, no test, step or fixture is running")
-      end
-      write_attachment(source, attachment)
-    end
+      attachment = ResultUtils.prepare_attachment(name, type)
+      return logger.error { "Can't add attachment, unrecognized mime type: #{type}" } unless attachment
 
-    # Create attachment object
-    # @param [String] name
-    # @param [String] type
-    # @return [Allure::Attachment]
-    def prepare_attachment(name, type)
-      extension = ContentType.to_extension(type) || return
-      file_name = "#{UUID.generate}-attachment.#{extension}"
-      Attachment.new(name: name, source: file_name, type: type)
-    end
+      executable_item = test_case ? @current_test_case : current_executable
+      return logger.error { "Can't add attachment, no test, step or fixture is running" } unless executable_item
 
-    # Write attachment file
-    # @param [File, String] source
-    # @param [Allure::Attachment] attachment
-    # @return [void]
-    def write_attachment(source, attachment)
-      file_writer.write_attachment(source, attachment)
+      executable_item.attachments.push(attachment)
+      logger.debug { "Adding attachment '#{name}' to '#{executable_item.name}'" }
+      write_attachment(source, attachment)
     end
 
     # Add step to current fixture|step|test case
@@ -228,20 +233,12 @@ module Allure
     # Clean results directory
     # @return [void]
     def clean_results_dir
-      Allure.configuration.tap do |c|
-        FileUtils.rm_f(Dir.glob("#{c.results_directory}/*")) if c.clean_results_directory
-      end
+      FileUtils.rm_f(Dir.glob("#{config.results_directory}/**/*")) if config.clean_results_directory
     end
 
     private
 
-    def logger
-      @logger ||= Logger.new(STDOUT, level: Config.logging_level)
-    end
-
-    def file_writer
-      @file_writer ||= FileWriter.new
-    end
+    attr_reader :logger, :file_writer
 
     def current_executable
       current_test_step || @current_fixture || @current_test_case