allure-rspec 0.8.0 → 2.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 6f7cae6b08f0509c5b7830ccf1108034c9becd88
-  data.tar.gz: 19b250c168c6db5d4d1f27878cee086b4748592c
+SHA256:
+  metadata.gz: 3e6c5bb377f6a90b6ef4d6927421c61f6a273d160fbf6ff571e34fc8826cc62a
+  data.tar.gz: b32ba8c7ab41c07aa02a6ff0d4f4285ef1bbaffd37a15857176ac651cb333138
 SHA512:
-  metadata.gz: f8f472e50e1b2c4e5e399f6bcbfe773b2ab47fea722436447794a67a12c7d54616799fa39bcc07c097df239221d34291d55b694fceef6c9ab12151fe3180eb2b
-  data.tar.gz: f45f2993559ee15598f2a3111ee80ecdd4c585bf7702c0e5cf645d348ea231932c6978abc82de78a34e456529ca7316a6a827392b71b1274bd93d08535d4943f
+  metadata.gz: a37fcab764248deb65cfff370cb92d4b3bc16c7cbda92487faf593aca77e62401f1aa094df659e1c1c075333ab982709e53c26f343b12fb7b9244bb41eda69b5
+  data.tar.gz: 1fd4ffd1c21d2a575a2bdd9925e71f08c18bed8ab7668558456ac754c0e5e22b7e6ffac5bbfb9b5f2eb93570d7de1117d886fd9f3d90b940650c70d611d65107

data/README.md

@@ -1,74 +1,224 @@
-# Allure RSpec Adaptor
+# allure-rspec
 
-[![Gem Version](https://badge.fury.io/rb/allure-rspec.svg)](http://badge.fury.io/rb/allure-rspec)
+[![Yard Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/gems/allure-rspec)
 
-Adaptor to use the Allure framework along with the RSpec. See [an example](https://github.com/allure-examples/allure-rspec-example) project to take a quick tour.
+Allure adapter for [rspec](https://rspec.info/) testing framework
 
-## What's new
+## Installation
 
-See the [releases](https://github.com/allure-framework/allure-rspec/releases) tab.
+Add it to gemfile:
 
+```ruby
+gem "allure-rspec"
+```
+
+Require in `spec_helper` or any other setup file:
+
+```ruby
+require "allure-rspec"
+```
 
-## Setup
+## Configuration
 
-Add the dependency to your Gemfile. Choose the version carefully:
-* 0.5.x - for RSpec2.
-* <= 0.6.7 - for RSpec < 3.2.
-* >= 0.6.9 - for RSpec >= 3.2.
+Following configuration options are supported:
 
 ```ruby
- gem 'allure-rspec'
+AllureRspec.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
+  config.link_tms_pattern = "http://www.jira.com/browse/{}"
+  config.link_issue_pattern = "http://www.jira.com/browse/{}"
+  
+  # additional metadata
+  # environment.properties
+  config.environment_properties = {
+    custom_attribute: "foo"
+  }
+  # categories.json
+  config.categories = File.new("my_custom_categories.json")
+end
+```
+
+## Usage
+
+Via commandline arguments, simply add:
+
+```bash
+--format AllureRspecFormatter
 ```
 
-And then include it in your spec_helper.rb:
+or
+
+Via RSpec configuration:
 
 ```ruby
-    RSpec.configure do |c|
-      c.include AllureRSpec::Adaptor
-    end
+RSpec.configure do |config|
+  config.formatter = AllureRspecFormatter
+end
 ```
 
-## Advanced options
+### Adding tms links
 
-You can specify the directory where the Allure test results will appear. By default it would be 'gen/allure-results'
-within your current directory.
+Configure tms link pattern and rspec tag:
 
 ```ruby
-    AllureRSpec.configure do |c|
-      c.output_dir = "/whatever/you/like" # default: gen/allure-results
-      c.clean_dir = false # clean the output directory first? (default: true)
-      c.logging_level = Logger::DEBUG # logging level (default: DEBUG)
-    end
+AllureRspec.configure do |config|
+  config.link_tms_pattern = "http://www.jira.com/browse/{}"
+  config.tms_tag = :tms
+end
 ```
 
-## Usage examples
+Add tag to rspec test:
 
 ```ruby
-describe MySpec, :feature => "Some feature", :severity => :normal do
+it "some test case", tms: "QA-123" do
+  # test
+end
+```
 
-  before(:step) do |s|
-    puts "Before step #{s.current_step}"
-  end
+It's possible to add multiple tms links using `tms_` pattern:
 
-  it "should be critical", :story => "First story", :severity => :critical, :testId => 99 do
-    "string".should == "string"
-  end
+```ruby
+it "some test case", tms_1: "QA-123", tms_2: "QA-124" do
+  # test
+end
+```
 
-  it "should be steps enabled", :story => ["First story", "Second story"], :testId => 31 do |e|
+### Adding issue links
 
-    e.step "step1" do |s|
-      s.attach_file "screenshot1", take_screenshot_as_file
-    end
+Configure issue link pattern:
 
-    e.step "step2" do
-      5.should be > 0
-    end
+```ruby
+AllureRspec.configure do |config|
+  config.link_issue_pattern = "http://www.jira.com/browse/{}"
+  config.issue_tag = :issue
+end
+```
+
+Add tag to rspec test:
+
+```ruby
+it "some test case", issue: "QA-123" do
+  # test
+end
+```
+
+It's possible to add multiple tms links using `issue_` pattern:
+
+```ruby
+it "some test case", issue_1: "QA-123", issue_2: "QA-124" do
+  # test
+end
+```
+
+### Adding custom severity and status details
+
+Configure severity tag:
+
+```ruby
+AllureRspec.configure do |config|
+  config.severity_tag = :severity
+end
+```
+
+Test severity is set to `normal` by default:
+
+```ruby
+it "some test case", severity: :critical do
+  # test
+end
+```
 
-    e.step "step3" do
-      0.should == 0
-    end
+Custom status details can be set via `muted`, `known`, `flaky` tags:
 
-    e.attach_file "screenshot2", take_screenshot_as_file
+```ruby
+it "some test case", flaky: true, muted: false, known: true do
+  # test
+end
+```
+
+### Adding additional labels to allure test case
+
+Additional labels can be added using `allure_` pattern:
+
+```ruby
+it "some test case", allure_1: "visual_test", allure_2: "core_functionality" do
+  # test
+end
+```
+
+All other metadata tags are also automatically added as labels:
+
+```ruby
+it "some test case", :visual_test, :core_functionality do
+  # test
+end
+```
+
+#### Skipping certain tags
+
+To skip adding certain tags as labels, following configuration can be added:
+
+```ruby
+AllureRspec.configure do |config|
+  config.ignored_tags = [:core_functionality, :generic_metadata_to_ignore]
+end
+```
+
+### Behavior driven test grouping
+
+Marking tests with tags `:epic, :feature, :story`, will group tests accordingly in Behavior report tab.\
+Tag values can also be configured:
+
+```ruby
+AllureRspec.configure do |config|
+  config.epic_tag = :epic
+  config.feature_tag = :feature
+  config.story_tag = :story
+end
+```
+
+```ruby
+context "context", feature: "my feature"  do
+  it "some test case", story: "user story" do
+    # test
+  end
+end
+
+context "context 2", feature: "my feature" do
+it "some test case 2", story: "user story" do
+    # test
+  end
+end
+```
+
+### Custom actions
+
+Rspec example object has access to [Allure](https://www.rubydoc.info/github/allure-framework/allure-ruby/Allure) helper methods.
+It can be used to add or run steps, add attachments, modify test case etc.
+
+```ruby
+it "some test case" do |e|
+  e.run_step("my custom step") do
+    # some action
   end
+  e.add_attachment(name: "attachment", source: "Some string", type: Allure::ContentType::TXT)
 end
 ```
+
+### Steps
+
+[Step annotations](../allure-ruby-commons/README.md#steps)
+
+### Example project
+
+[RSpec Example](https://github.com/allure-examples/allure-rspec-example)
+
+## HTML report generation
+
+Report is generated using allure commandline tool. [Allure wiki](https://docs.qameta.io/allure/#_reporting).

data/lib/allure-rspec.rb

@@ -1,56 +1,28 @@
-require 'allure-ruby-adaptor-api'
-require 'allure-rspec/version'
-require 'allure-rspec/formatter'
-require 'allure-rspec/adaptor'
-require 'allure-rspec/dsl'
-require 'allure-rspec/hooks'
+# rubocop:disable Naming/FileName
+# frozen_string_literal: true
 
-module AllureRSpec
-  module Config
-    class << self
-      attr_accessor :output_dir
-      attr_accessor :clean_dir
-      attr_accessor :logging_level
+require "allure-ruby-commons"
 
-      DEFAULT_OUTPUT_DIR = 'gen/allure-results'
-      DEFAULT_LOGGING_LEVEL = Logger::DEBUG
-
-      def output_dir
-        @output_dir || DEFAULT_OUTPUT_DIR
-      end
-
-      def clean_dir?
-        @clean_dir.nil? ? true : @clean_dir
-      end
-
-      def logging_level
-        @logging_level || DEFAULT_LOGGING_LEVEL
-      end
-    end
-  end
-
-  class Context
-    attr_accessor :rspec
-
-    def rspec
-      @rspec
-    end
-  end
+require_rel "allure_rspec/**/*.rb"
 
+module AllureRspec
   class << self
-    def context
-      @context ||= Context.new
+    # Get allure cucumber configuration
+    # @return [AllureRspec::RspecConfig]
+    def configuration
+      RspecConfig.instance
     end
-  end
 
-  class << self
-    def configure(&block)
-      yield Config
-      AllureRubyAdaptorApi.configure { |c|
-        c.output_dir = Config.output_dir
-        c.logging_level = Config.logging_level
-      }
+    # Set allure configuration
+    # @yieldparam [AllureRspec::RspecConfig]
+    # @yieldreturn [void]
+    # @return [void]
+    def configure
+      yield(configuration)
     end
   end
-
 end
+
+# Rspec formatter class shorthand
+AllureRspecFormatter = AllureRspec::RSpecFormatter
+# rubocop:enable Naming/FileName

data/lib/allure_rspec/_utils.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module AllureRspec
+  module Utils
+    # Strip relative ./ form path
+    # @param [String] path
+    # @return [String]
+    def strip_relative(path)
+      path.gsub("./", "")
+    end
+  end
+end

data/lib/allure_rspec/config.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module AllureRspec
+  # Allure RSpec configuration class
+  #
+  # @!attribute results_directory
+  #   @return [String]
+  # @!attribute clean_results_directory
+  #   @return [Boolean]
+  # @!attribute link_issue_pattern
+  #   @return [String]
+  # @!attribute link_tms_pattern
+  #   @return [String]
+  # @!attribute logging_level
+  #   @return [Integer]
+  # @!attribute [r] logger
+  #   @return [Logger]
+  # @!attribute environment
+  #   @return [String]
+  class RspecConfig
+    include Singleton
+    extend Forwardable
+
+    # @return [Symbol] default tms tag
+    DEFAULT_TMS_TAG = :tms
+    # @return [Symbol] default issue tag
+    DEFAULT_ISSUE_TAG = :issue
+    # @return [Symbol] default severity tag
+    DEFAULT_SEVERITY_TAG = :severity
+    # @return [Symbol] default epic tag
+    DEFAULT_EPIC_TAG = :epic
+    # @return [Symbol] default feature tag
+    DEFAULT_FEATURE_TAG = :feature
+    # @return [Symbol] default story tag
+    DEFAULT_STORY_TAG = :story
+
+    def_delegators :@allure_config,
+                   :clean_results_directory,
+                   :clean_results_directory=,
+                   :link_issue_pattern,
+                   :link_issue_pattern=,
+                   :link_tms_pattern,
+                   :link_tms_pattern=,
+                   :logging_level,
+                   :logging_level=,
+                   :logger,
+                   :logger=,
+                   :results_directory,
+                   :results_directory=,
+                   :environment,
+                   :environment=,
+                   :environment_properties,
+                   :environment_properties=,
+                   :categories,
+                   :categories=
+
+    def initialize
+      @allure_config = Allure.configuration
+    end
+
+    attr_writer :tms_tag,
+                :issue_tag,
+                :severity_tag,
+                :epic_tag,
+                :feature_tag,
+                :story_tag,
+                :ignored_tags
+
+    # @return [Symbol]
+    def tms_tag
+      @tms_tag || DEFAULT_TMS_TAG
+    end
+
+    # @return [Symbol]
+    def issue_tag
+      @issue_tag || DEFAULT_ISSUE_TAG
+    end
+
+    # @return [Symbol]
+    def severity_tag
+      @severity_tag || DEFAULT_SEVERITY_TAG
+    end
+
+    # @return [Symbol]
+    def epic_tag
+      @epic_tag || DEFAULT_EPIC_TAG
+    end
+
+    # @return [Symbol]
+    def feature_tag
+      @feature_tag || DEFAULT_FEATURE_TAG
+    end
+
+    # @return [Symbol]
+    def story_tag
+      @story_tag || DEFAULT_STORY_TAG
+    end
+
+    # @return [Array]
+    def ignored_tags
+      @ignored_tags || []
+    end
+  end
+end

data/lib/allure_rspec/formatter.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require "rspec/core/formatters/base_formatter"
+
+# Main allure-rspec module
+module AllureRspec
+  # Main rspec formatter class translating rspec events to allure lifecycle
+  class RSpecFormatter < RSpec::Core::Formatters::BaseFormatter
+    include Utils
+
+    # @return [Hash] allure statuses mapping
+    ALLURE_STATUS = {
+      failed: Allure::Status::FAILED,
+      pending: Allure::Status::SKIPPED,
+      passed: Allure::Status::PASSED
+    }.freeze
+
+    RSpec::Core::Formatters.register(
+      self,
+      :start,
+      :stop,
+      :example_group_started,
+      :example_group_finished,
+      :example_started,
+      :example_finished
+    )
+
+    RSpec.configure do |config|
+      ids = Allure::TestPlan.test_ids
+      names = Allure::TestPlan.test_names
+
+      config.filter_run_when_matching(*ids.map { |id| { allure_id: id } }) if ids
+      config.full_description = names if names
+    end
+
+    def initialize(output)
+      super
+
+      @allure_config = AllureRspec.configuration
+      Allure.lifecycle = @lifecycle = Allure::AllureLifecycle.new(@allure_config)
+    end
+
+    # Start test run
+    # @param [RSpec::Core::Notifications::StartNotification] _start_notification
+    # @return [void]
+    def start(_start_notification)
+      lifecycle.clean_results_dir
+      lifecycle.write_categories
+
+      RSpec::Core::Example.class_eval do
+        include Allure
+      end
+    end
+
+    # Start test run
+    # @param [RSpec::Core::Notifications::StopNotification] _stop_notification
+    # @return [void]
+    def stop(_stop_notification)
+      lifecycle.write_environment
+    end
+
+    # Starts example group
+    # @param [RSpec::Core::Notifications::GroupNotification] example_group_notification
+    # @return [void]
+    def example_group_started(example_group_notification)
+      description = example_group_notification.group.description.yield_self do |desc|
+        desc.empty? ? "Anonymous" : desc
+      end
+      lifecycle.start_test_container(Allure::TestResultContainer.new(name: description))
+    end
+
+    # Starts example
+    # @param [RSpec::Core::Notifications::ExampleNotification] example_notification
+    # @return [void]
+    def example_started(example_notification)
+      lifecycle.start_test_case(test_result(example_notification.example))
+    end
+
+    # Finishes example
+    # @param [RSpec::Core::Notifications::ExampleNotification] example_notification
+    # @return [void]
+    def example_finished(example_notification)
+      lifecycle.update_test_case(&update_test_proc(example_notification.example.execution_result))
+      lifecycle.stop_test_case
+    end
+
+    # Starts example group
+    # @param [RSpec::Core::Notifications::GroupNotification] _example_group_notification
+    # @return [void]
+    def example_group_finished(_example_group_notification)
+      lifecycle.stop_test_container
+    end
+
+    private
+
+    attr_reader :lifecycle, :allure_config
+
+    # Transform example to <Allure::TestResult>
+    # @param [RSpec::Core::Example] example
+    # @return [Allure::TestResult]
+    def test_result(example)
+      parser = RspecMetadataParser.new(example, allure_config)
+
+      Allure::TestResult.new(
+        name: example.description,
+        description: "Location - #{strip_relative(example.location)}",
+        description_html: "Location - #{strip_relative(example.location)}",
+        history_id: example.id,
+        full_name: example.full_description,
+        labels: parser.labels,
+        links: parser.links,
+        status_details: parser.status_details,
+        environment: allure_config.environment
+      )
+    end
+
+    # Update test status on finish
+    # @param [RSpec::Core::Example::ExecutionResult] result
+    # @return [Proc]
+    def update_test_proc(result)
+      Allure::ResultUtils.status_details(result.exception).yield_self do |status_detail|
+        proc do |test_case|
+          test_case.stage = Allure::Stage::FINISHED
+          test_case.status = status(result)
+          test_case.status_details.message = status_detail.message
+          test_case.status_details.trace = status_detail.trace
+        end
+      end
+    end
+
+    # Get allure status from result
+    # @param [RSpec::Core::Example::ExecutionResult] result
+    # @return [Symbol]
+    def status(result)
+      return Allure::ResultUtils.status(result.exception) if result.status == :failed
+
+      ALLURE_STATUS[result.status]
+    end
+  end
+end