rspec-pipeline 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0994ec575ad37311fc3cef61fedf84e2eced1e7d5b7069717b387838c0f804de'
-  data.tar.gz: 003f757294cc81f56042d4efd31d0c765d5fe040a8db32b4cd785fee6c401def
+  metadata.gz: f14148b4cb5d701e8e2807e9022233f137b98d215f4f4653a0c4c1f4dc79b2fb
+  data.tar.gz: 7eb882d5a10c2b37f7385cde684ace19dcf2d43adca80cdca001601592fa3ee7
 SHA512:
-  metadata.gz: cfe45a6df025111cbacd21d6b63c7540f3df06900ed04e0085b4c97df57f52ffd920b0defceedbb5519bf523bcc6b11d9c8868804ba60c1c4da7040dd3359d3a
-  data.tar.gz: 2851300fcb763ade4649d1f8546ab4df971795b3c5d3d60540bfee6a30b057be7685b211107d699ea676822c84ca37cadf4292d66be4632baa7d3b434894d4ab
+  metadata.gz: b3bae63d085cdb5324eb9f98e1b8f172f76f75acfd859aff88e54b88798f0a529f13fa3a8c03f88fad62a396a66f43428efed5b0ed0b24eb0bb1560d8889ac9d
+  data.tar.gz: 82a39c6fb1001234c702da8ae800e91e3fb18d3e9218b24d9e30ae63313d87452fa57fc2167418aed08dffbdd884d8a3db313ea4dedb5d219042d5913a2fff52

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# CHANGELOG
+
+## [0.1.0] - 2021-10-18
+
+- Initial release
+- Verify stage and job dependecy
+- Verify when something is limited to run from a specific branch
+- Verify when a step is limited to run when a previous step failed or got succeeded
+
+## [0.2.0] - 2021-10-30
+- Evaluate and render local templates
+- Validate template parameters
+
+## [0.3.0] - 2120-10-31
+
+- Evaluate and render remote templates by fetching remote repositories using git

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Thiago Marinho
+
+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,81 @@
+# RSpec tests for your pipelines
+
+Create tests for your pipelines to validate dependencies between blocks and other characteristics.
+
+> Only Azure YAML Pipelines are supported at the moment.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rspec-pipeline'
+```
+
+And then execute:
+
+```shell
+$ bundle install
+```
+
+Or install it yourself as:
+
+```shell
+$ gem install rspec-pipeline
+```
+
+## Usage
+
+Add this at the beginning of your spec_helper.rb:
+
+```ruby
+require 'rspec-pipeline'
+```
+
+When writing your test you can use the keywords `pipeline`, `stage`, `job` and `step` as example groups, and the example's `subject` will be the corresponding item, filtered by its description. For example:
+
+```ruby
+pipeline 'pipeline.yml' do
+  stage 'DeployToDev' do
+    it { is_expected.to run_after('Build') }
+  end
+end
+```
+
+The test will pass if your pipeline is defined like this:
+
+```yaml
+stages:
+- stage: Build
+  jobs:
+  - job: Build
+    steps:
+      - bash: echo "Build"
+
+- stage: DeployToDev
+  dependsOn: Build
+  jobs:
+  - job: B1
+    steps:
+    - bash: echo "Deploy to Dev"
+```
+
+Please go to the `examples` folder to see a few more use cases.
+
+### About remote templates
+
+Note that if you try to use a template from a remote git repository you need to have clone permission and your git credentials configured if it is a private repository.
+
+## 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.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/thiagomarinho/rspec-pipeline.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'rspec-pipeline'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/rspec/pipeline/context.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+shared_context 'pipeline context', type: :pipeline do
+  let!(:pipeline_name) { self.class.top_level_description }
+end
+
+shared_context 'stage context', type: :stage do
+  subject { stage(RSpec.current_example.metadata[:example_group][:description]) }
+end
+
+shared_context 'job context', type: :job do
+  subject do
+    job(RSpec.current_example.metadata[:example_group][:parent_example_group][:description],
+        RSpec.current_example.metadata[:example_group][:description])
+  end
+end
+
+shared_context 'step context', type: :step do
+  subject do
+    step(RSpec.current_example.metadata[:example_group][:parent_example_group][:parent_example_group][:description],
+         RSpec.current_example.metadata[:example_group][:parent_example_group][:description],
+         RSpec.current_example.metadata[:example_group][:description])
+  end
+end

data/lib/rspec/pipeline/fixture_loader.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module RSpec::Pipeline # rubocop:disable Style/ClassAndModuleChildren
+  # This class configures and loads fixtures. It this moment, the only fixtures we have are repositories usually
+  # utilized for remote templates.
+  class FixtureLoader
+    def self.load(verbose: true)
+      ['spec', File.join('spec', 'fixtures')].each { |dir| safe_mkdir(dir, verbose: verbose) }
+
+      RSpec.configuration.fixtures_repos.each do |repo_definition|
+        if repo_definition[:path]
+          safe_cp_r(repo_definition[:path], File.join('spec', 'fixtures', repo_definition[:name]), verbose: verbose)
+        elsif repo_definition[:repo]
+          safe_git_clone(repo_definition, verbose: verbose)
+        else
+          warn "!! invalid fixture repository definition: #{repo_definition}"
+        end
+      end
+    end
+
+    def self.safe_mkdir(dir, verbose: true)
+      if File.exist? dir
+        warn "!! #{dir} already exists and is not a directory" unless File.directory? dir
+      else
+        begin
+          FileUtils.mkdir dir
+        rescue Errno::EEXIST => e
+          raise e unless File.directory? dir
+        end
+
+        puts " + #{dir}/" if verbose
+      end
+    end
+
+    def self.safe_cp_r(src, dest, verbose: true) # rubocop:disable Metrics/MethodLength
+      if File.exist? dest
+        warn "!! #{dest} already exists and is not a directory" unless File.directory? dest
+      elsif !File.exist? src
+        warn "!! #{src} not found"
+      else
+        begin
+          FileUtils.cp_r src, dest
+        rescue Errno::EEXIST => e
+          raise e unless File.directory? dest
+        end
+
+        puts " + #{dest}/" if verbose
+      end
+    end
+
+    def self.safe_git_clone(repo_definition, verbose: true) # rubocop:disable Metrics/MethodLength
+      dest = File.join('spec', 'fixtures', repo_definition[:name])
+
+      if File.exist? dest
+        if File.directory? dest
+          if File.exist? "#{dest}/.git"
+            git_pull_and_checkout(repo_definition, dest)
+          else
+            warn "!! #{dest} already exists and is not a git repo"
+          end
+        else
+          warn "!! #{dest} already exists and is not a directory"
+        end
+      else
+        `git clone #{repo_definition[:repo]} #{dest}`
+
+        puts " + #{dest}/" if verbose
+      end
+    end
+
+    def self.git_pull_and_checkout(repo_definition, dest)
+      `git -C #{dest} pull`
+
+      ref_to_checkout = (repo_definition[:ref] || 'main')
+      `git -C #{dest} checkout #{ref_to_checkout}`
+    end
+  end
+end

data/lib/rspec/pipeline/helper/type.rb

@@ -0,0 +1,2 @@
+# frozen_string_literal: true
+# TODO

data/lib/rspec/pipeline/helper.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'pipeline_loader'
+require_relative 'template_loader'
+
+def pipeline
+  pipeline = RSpec::Pipeline::PipelineLoader.new(pipeline_name)
+
+  pipeline.load
+end
+
+def stage(name)
+  stage = pipeline['stages'].find { |item| item['stage'] == name }
+
+  raise "Stage not found: #{name}" if stage.nil?
+
+  stage['blockType'] = 'Stage'
+  stage['blockName'] = stage['stage']
+
+  stage
+end
+
+def job(stage_name, name)
+  job = stage(stage_name)['jobs'].find { |item| item['job'] == name }
+
+  raise "Job not found: #{name}" if job.nil?
+
+  job['blockType'] = 'Job'
+  job['blockName'] = job['job']
+
+  job
+end
+
+def step(stage_name, job_name, name)
+  job_to_search = job(stage_name, job_name)
+  raise "Job #{job_name} doesn't have steps" unless job_to_search['steps']
+
+  step = job_to_search['steps'].find { |item| item['name'] == name }
+  raise "Step not found: #{name} (available: #{job_to_search['steps'].map { |item| item['name'] }})" if step.nil?
+
+  step['blockType'] = 'Step'
+  step['blockName'] = step['name']
+
+  step
+end
+
+# events
+def push_to_branch(name)
+  {
+    'type' => :push,
+    'branch' => name,
+    'condition' => "eq(variables['build.sourceBranch'], 'refs/heads/#{name}'"
+  }
+end
+
+def push_to_master
+  push_to_branch 'master'
+end
+
+def pull_request
+  # TODO
+end

data/lib/rspec/pipeline/matcher/run_after.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define :run_after do |thing|
+  match do |actual|
+    if actual['dependsOn'].is_a?(Array)
+      actual['dependsOn'].include?(thing)
+    else
+      actual['dependsOn'] == thing
+    end
+  end
+
+  failure_message do |_event|
+    "#{actual['blockType']} \"#{actual['blockName']}\" was expected to depend on #{actual['blockType']} \"#{thing}\"" \
+      "but depends on \"#{actual['dependsOn']}\" instead."
+  end
+end

data/lib/rspec/pipeline/matcher/run_always.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define :run_always do
+  match do |actual|
+    actual['condition'].include?('always()')
+  end
+
+  failure_message do |_event|
+    'Failure!'
+  end
+end

data/lib/rspec/pipeline/matcher/run_on_failure.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define :run_on_failure do
+  match do |actual|
+    actual['condition'].include?('failure()')
+  end
+
+  failure_message do |_event|
+    'Failure!'
+  end
+end

data/lib/rspec/pipeline/matcher/run_on_success.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define :run_on_success do
+  match do |actual|
+    !actual['condition'] || actual['condition'].include?('succeeded()')
+  end
+
+  failure_message do |_event|
+    "Expected condition to include succeeded() but the actual value is #{actual['condition']} instead"
+  end
+end

data/lib/rspec/pipeline/matcher/run_on_success_or_failure.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define :run_on_success_or_failure do
+  match do |actual|
+    actual['condition'].include?('succeededOrFailed()')
+  end
+
+  failure_message do |_event|
+    'Failure!'
+  end
+end

data/lib/rspec/pipeline/matcher/run_when.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define :run_when do |event|
+  match do |actual|
+    actual['condition'].include?(event['condition'])
+  end
+
+  failure_message do |_event|
+    'Failure!'
+  end
+end

data/lib/rspec/pipeline/matcher.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'rspec/pipeline/matcher/run_when'
+require 'rspec/pipeline/matcher/run_on_success'
+require 'rspec/pipeline/matcher/run_on_failure'
+require 'rspec/pipeline/matcher/run_on_success_or_failure'
+require 'rspec/pipeline/matcher/run_always'
+require 'rspec/pipeline/matcher/run_after'

data/lib/rspec/pipeline/pipeline_loader.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module RSpec::Pipeline # rubocop:disable Style/ClassAndModuleChildren
+  # This class loads the pipeline from a YAML file, also calling required methods to
+  # evaluate templates.
+  class PipelineLoader
+    def initialize(pipeline_name)
+      @pipeline_name = pipeline_name
+      @template_loader = TemplateLoader.new
+    end
+
+    def load
+      pipeline = YAML.load_file(@pipeline_name)
+
+      pipeline['stages'] = evaluate_stages(pipeline)
+
+      pipeline['stages'].each do |stage|
+        stage['jobs'] = evaluate_jobs(stage, pipeline)
+
+        stage['jobs'].each do |job|
+          job['steps'] = evaluate_steps(job, stage, pipeline)
+        end
+      end
+
+      pipeline
+    end
+
+    private
+
+    def evaluate_stages(pipeline)
+      templated_items = pipeline['stages'].map do |item|
+        if item['template']
+          load_template(item, 'stages', [pipeline])
+        else
+          item
+        end
+      end
+
+      templated_items.flatten.compact
+    end
+
+    def evaluate_jobs(stage, pipeline)
+      templated_items = stage['jobs'].map do |item|
+        if item['template']
+          load_template(item, 'jobs', [stage, pipeline])
+        else
+          item
+        end
+      end
+
+      templated_items.flatten.compact
+    end
+
+    def evaluate_steps(job, stage, pipeline)
+      templated_steps = job['steps'].map do |step|
+        if step['template']
+          load_template(step, 'steps', [job, stage, pipeline])
+        else
+          step
+        end
+      end
+
+      templated_steps.flatten.compact
+    end
+
+    def load_template(template, type, context)
+      template_name, template_repo = parse_template_metadata(template, context)
+
+      @template_loader.load(type, template_name, template_repo, template['parameters'])
+    end
+
+    def parse_template_metadata(template, context)
+      if template['template'].include? '@'
+        template['template'].split '@'
+      else
+        item_with_metadata = context.detect { |item| item['_meta'] && item['_meta']['repo'] }
+
+        if item_with_metadata
+          [template['template'], item_with_metadata['_meta']['repo']]
+        else
+          [template['template'], '.']
+        end
+      end
+    end
+  end
+end

data/lib/rspec/pipeline/template_loader.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+# TODO: handle parameter default values
+# TODO: validate parameters
+# - throw SyntaxError: parameter used but not defined
+module RSpec::Pipeline # rubocop:disable Style/ClassAndModuleChildren
+  # This class loads and validates templates from YAML files.
+  class TemplateLoader
+    def initialize
+      @repo_stack = ['.']
+    end
+
+    def load(type, template, repo, parameters) # rubocop:disable Metrics/MethodLength
+      template_content = load_template_file(repo, template)
+
+      parameters&.each do |key, value|
+        template_content = template_content.gsub("${{ parameters.#{key} }}", value)
+      end
+
+      yaml_template = YAML.safe_load(template_content)
+
+      validate_parameters_not_found(parameters, yaml_template)
+      validate_required_parameters_not_defined(parameters, yaml_template)
+
+      yaml_template[type]&.map do |item|
+        item['_meta'] = {
+          'repo' => repo
+        }
+      end
+
+      yaml_template[type]
+    end
+
+    private
+
+    def load_template_file(repo, template)
+      template_file = if repo == '.'
+                        template
+                      else
+                        "spec/fixtures/#{repo}/#{template}"
+                      end
+
+      raise "Expected to have a template file called #{template_file}" unless File.exist? template_file
+
+      File.read template_file
+    end
+
+    def validate_parameters_not_found(parameters, yaml_template)
+      parameters_not_found = (parameters || {}).keys -
+                             (yaml_template['parameters'] || []).map { |parameter| parameter['name'] }
+
+      unless parameters_not_found.empty? # rubocop:disable Style/GuardClause
+        raise 'These parameters have been defined when you called the template but ' \
+          "they are not in the template: #{parameters_not_found.join(', ')}"
+      end
+    end
+
+    def validate_required_parameters_not_defined(parameters, yaml_template)
+      required_parameters_not_defined = (yaml_template['parameters'] || []).map { |parameter| parameter['name'] } -
+                                        (parameters || {}).keys
+
+      unless required_parameters_not_defined.empty? # rubocop:disable Style/GuardClause
+        raise "These parameters doesn't have default values but are not being defined when you called the " \
+          "template: #{required_parameters_not_defined.join(', ')}"
+      end
+    end
+  end
+end

data/lib/rspec/pipeline/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Pipeline
+    VERSION = '0.4.1'
+  end
+end

data/lib/rspec/pipeline.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'pipeline/version'
+
+module RSpec::Pipeline # rubocop:disable Style/ClassAndModuleChildren
+  class Error < StandardError; end
+end
+
+RSpec.configure do |config|
+  config.alias_example_group_to :pipeline, detailed: true, type: :pipeline, include_shared: true
+  config.alias_example_group_to :stage, detailed: true, type: :stage, include_shared: true
+  config.alias_example_group_to :job, detailed: true, type: :job, include_shared: true
+  config.alias_example_group_to :step, detailed: true, type: :step, include_shared: true
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+
+  config.add_setting :setup_fixtures, default: true
+  config.add_setting :fixtures_repos, default: []
+
+  config.before(:all) do
+    RSpec::Pipeline::FixtureLoader.load if RSpec.configuration.setup_fixtures? &&
+                                           RSpec.configuration.fixtures_repos.any?
+  end
+end

data/lib/rspec-pipeline.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'rspec/pipeline'
+
+require 'rspec/pipeline/matcher'
+require 'rspec/pipeline/helper'
+require 'rspec/pipeline/context'
+require 'rspec/pipeline/fixture_loader'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-pipeline
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Thiago Marinho
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-10-31 00:00:00.000000000 Z
+date: 2021-11-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug
@@ -30,7 +30,28 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- bin/console
+- bin/setup
+- lib/rspec-pipeline.rb
+- lib/rspec/pipeline.rb
+- lib/rspec/pipeline/context.rb
+- lib/rspec/pipeline/fixture_loader.rb
+- lib/rspec/pipeline/helper.rb
+- lib/rspec/pipeline/helper/type.rb
+- lib/rspec/pipeline/matcher.rb
+- lib/rspec/pipeline/matcher/run_after.rb
+- lib/rspec/pipeline/matcher/run_always.rb
+- lib/rspec/pipeline/matcher/run_on_failure.rb
+- lib/rspec/pipeline/matcher/run_on_success.rb
+- lib/rspec/pipeline/matcher/run_on_success_or_failure.rb
+- lib/rspec/pipeline/matcher/run_when.rb
+- lib/rspec/pipeline/pipeline_loader.rb
+- lib/rspec/pipeline/template_loader.rb
+- lib/rspec/pipeline/version.rb
 homepage: https://github.com/thiagomarinho/rspec-pipeline
 licenses:
 - MIT