rspec-tracer 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c266f7b90880f1c3ab8c9e272f5abee4834154c6c9b6541d50fe7701655da6e7
-  data.tar.gz: ce2101a5c35cc334c5e3c061842c0ba27e0c9e7f8ce77e109a047f0eda108a82
+  metadata.gz: 34f47b6527f2c8f3c1cb3524adf8d81a9fe7e3833c202605a206598dee8758b2
+  data.tar.gz: e647137006f5f8af18999ea8f2665c09d703bf2cd8ea1e84dec85e66f87ba5e2
 SHA512:
-  metadata.gz: 5a7152dc475afb4e2ab42aeaf3798108edce0580fcc00a1c2a03b0f319f925633bae59245b7a570938d34372cbb4d134daff5909adf2785325794edcfab36fcd
-  data.tar.gz: 6a30e7b361d877404692229f60bd63d6e19088c4ac627838aae40af357851a0f2757b4561c843b4d91d6e3f41a6a3c3a29989bd94e1fde33efde701b735852fb
+  metadata.gz: 05c204bd00cfa15258a1770790360184c9481d670cc8ef3542b06024976a9e13cf3595e79ecefa0d22c8337d35dee9ef6963b145cf1aa16268f3de467c7d171b
+  data.tar.gz: b2f7e88fbf404793a9e2daaade7448d51bd63150701a6735c9ae8bdcb17eaf25c926bde411cd61bc5dd20133829d1576d16b7588336f05ec968ae4f3d82a5453

data/CHANGELOG.md

@@ -1,6 +1,8 @@
-## [Unreleased]
+## [0.4.0] - 2021-09-03
 
-**[WIP]** Support for CI
+### Added
+
+- Support for CI
 
 ## [0.3.0] - 2021-08-30
 

data/README.md

@@ -14,15 +14,41 @@ Knowing the examples and files dependency gives us a better insight into the cod
 and we have **a clear idea of what to test for when making any changes**. With this data,
 we can also analyze the coupling between different components and much more.
 
-Read more on the intention and the implementation idea [here](./RSPEC_TRACER.md).
-
 ## Note
 
-**RSpec Tracer is currently available for use in the local development
-environment only.** Support for CI is work in progress.
-
-**If you find this gem could be a helpful addition to your project, give it a try
-on local and report any issues you encountered.**
+You should take some time and go through the [document](./RSPEC_TRACER.md) describing
+the **intention** and implementation details of **skipping tests**, **managing coverage**,
+and **caching on CI**, etc.
+
+## Table of Contents
+
+* [Demo](#demo)
+* [Installation](#installation)
+  * [Compatibility](#compatibility)
+  * [Additional Tools](#additional-tools)
+* [Getting Started](#getting-started)
+* [Environment Variables](#environment-variables)
+  * [CI](#ci)
+  * [LOCAL_AWS](#local_aws)
+  * [RSPEC_TRACER_NO_SKIP](#rspec_tracer_no_skip)
+  * [RSPEC_TRACER_S3_URI](#rspec_tracer_s3_uri)
+  * [RSPEC_TRACER_UPLOAD_LOCAL_CACHE](#rspec_tracer_upload_local_cache)
+  * [TEST_SUITE_ID](#test_suite_id)
+  * [TEST_SUITES](#test_suites)
+* [Sample Reports](#sample-reports)
+    * [Examples](#examples)
+    * [Examples Dependency](#examples-dependency)
+    * [Files Dependency](#files-dependency)
+* [Configuring RSpec Tracer](#configuring-rspec-tracer)
+* [Filters](#filters)
+  * [Defining Custom Filteres](#defining-custom-filteres)
+    * [String Filter](#string-filter)
+    * [Regex Filter](#regex-filter)
+    * [Block Filter](#block-filter)
+    * [Array Filter](#array-filter)
+* [Contributing](#contributing)
+* [License](#license)
+* [Code of Conduct](#code-of-conduct)
 
 ## Demo
 
@@ -53,6 +79,11 @@ RSpec Tracer requires **Ruby 2.5+** and **rspec-core >= 3.6.0**. To use with **R
 make sure to use **rspec-rails >= 4.0.0**. If you are using SimpleCov, it is
 recommended to use **simplecov >= 0.12.0**.
 
+### Additional Tools
+
+To use RSpec Tracer on CI, you need to have an **S3 bucket** and
+**[AWS CLI](https://aws.amazon.com/cli/)** installed.
+
 ## Getting Started
 
 1. **Load and Start RSpec Tracer**
@@ -87,14 +118,43 @@ recommended to use **simplecov >= 0.12.0**.
         RSpecTracer.start
         ```
 
-2. Run the tests with RSpec using `bundle exec rspec`.
-3. After running your tests, open `rspec_tracer_report/index.html` in the
+2. To enable RSpec Tracer to share cache between different builds on CI, update the
+Rakefile in your project to have the following:
+
+    ```ruby
+    spec = Gem::Specification.find_by_name('rspec-tracer')
+
+    load "#{spec.gem_dir}/lib/rspec_tracer/remote_cache/Rakefile"
+    ```
+3. Before running tests, download the remote cache using the following rake task:
+
+    ```ruby
+    bundle exec rake rspec_tracer:remote_cache:download
+    ```
+4. Run the tests with RSpec using `bundle exec rspec`.
+5. After running tests, upload the local cache using the following rake task:
+
+    ```ruby
+    bundle exec rake rspec_tracer:remote_cache:upload
+    ```
+6. After running your tests, open `rspec_tracer_report/index.html` in the
 browser of your choice.
 
 ## Environment Variables
 
 To get better control on execution, you can use the following two environment variables:
 
+### CI
+
+Mostly all the CI have `CI=true`. If not, you should explicitly set it to `true`.
+
+### LOCAL_AWS
+
+In case you want to test out the caching feature in the local development environment.
+You can install [localstack](https://github.com/localstack/localstack) and
+[awscli-local](https://github.com/localstack/awscli-local) and then invoke the
+rake tasks with `LOCAL_AWS=true`.
+
 ### RSPEC_TRACER_NO_SKIP
 
 The default value is `false.` If set to `true`, the RSpec Tracer will not skip
@@ -104,6 +164,19 @@ any tests. Note that it will continue to maintain cache files and generate repor
 RSPEC_TRACER_NO_SKIP=true bundle exec rspec
 ```
 
+### RSPEC_TRACER_S3_URI
+
+You should provide the S3 bucket path to store the cache files.
+
+```ruby
+export RSPEC_TRACER_S3_URI=s3://ci-artifacts-bucket/rspec-tracer-cache
+```
+
+### RSPEC_TRACER_UPLOAD_LOCAL_CACHE
+
+By default, RSpec Tracer does not upload local cache files. You can set this
+environment variable to `true` to upload the local cache to S3.
+
 ### TEST_SUITE_ID
 
 If you have a large set of tests to run, it is recommended to run them in
@@ -116,6 +189,15 @@ TEST_SUITE_ID=1 bundle exec rspec spec/models
 TEST_SUITE_ID=2 bundle exec rspec spec/helpers
 ```
 
+### TEST_SUITES
+
+Set this environment variable when using test suite id. It determines the total
+number of different test suites you are running.
+
+```ruby
+export TEST_SUITES=8
+```
+
 ## Sample Reports
 
 You get the following three reports:

data/lib/rspec_tracer/remote_cache/cache.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative 'git'
+
+module RSpecTracer
+  module RemoteCache
+    class Cache
+      class CacheDownloadError < StandardError; end
+
+      class CacheUploadError < StandardError; end
+
+      class LocalCacheNotFoundError < StandardError; end
+
+      CACHE_FILES_PER_TEST_SUITE = 8
+
+      def initialize
+        @s3_uri = ENV['RSPEC_TRACER_S3_URI']
+        @aws_s3 = if ENV.fetch('LOCAL_AWS', 'false') == 'true'
+                    'awslocal'
+                  else
+                    'aws'
+                  end
+        @test_suite_id = ENV['TEST_SUITE_ID'].to_s
+        @test_suites = ENV.fetch('TEST_SUITES', '1').to_i
+        @total_objects = CACHE_FILES_PER_TEST_SUITE * @test_suites
+      end
+
+      def download
+        if @s3_uri.nil?
+          puts 'S3 URI is not configured'
+
+          return
+        end
+
+        @git = RSpecTracer::RemoteCache::Git.new
+        @git.prepare_for_download
+
+        @cache_sha = nearest_cache_sha
+
+        if @cache_sha.nil?
+          puts 'Could not find a suitable cache sha to download'
+
+          return
+        end
+
+        download_files
+
+        puts "Downloaded cache from #{@download_prefix} to #{@download_path}"
+      rescue StandardError => e
+        puts "Errored: #{e.message}"
+      end
+
+      def upload
+        if @s3_uri.nil?
+          puts 'S3 URI is not configured'
+
+          return
+        end
+
+        @run_id = last_run_id
+        @git = RSpecTracer::RemoteCache::Git.new
+
+        upload_files
+
+        puts "Uploaded cache from #{@upload_path} to #{@upload_prefix}"
+      rescue CacheUploadError => e
+        puts "Errored: #{e.message}"
+      end
+
+      private
+
+      def nearest_cache_sha
+        @git.ref_list.detect do |ref|
+          prefix = "#{@s3_uri}/#{ref}/#{@test_suite_id}/".sub(%r{/+$}, '/')
+
+          puts "Testing prefix #{prefix}"
+
+          command = <<-COMMAND.strip.gsub(/\s+/, ' ')
+            #{@aws_s3} s3 ls #{prefix}
+              --recursive
+              --summarize
+            | grep 'Total Objects'
+          COMMAND
+
+          @total_objects == `#{command}`.chomp.split('Total Objects:').last.to_s.strip.to_i
+        end
+      end
+
+      def download_files
+        @download_prefix = "#{@s3_uri}/#{@cache_sha}/#{@test_suite_id}/".sub(%r{/+$}, '/')
+        @download_path = RSpecTracer.cache_path
+
+        return if system(
+          @aws_s3, 's3', 'cp',
+          @download_prefix,
+          @download_path,
+          '--recursive',
+          out: File::NULL, err: File::NULL
+        )
+
+        FileUtils.rm_rf(@download_path)
+
+        raise CacheDownloadError, 'Failed to download cache files'
+      end
+
+      def last_run_id
+        file_name = File.join(RSpecTracer.cache_path, 'last_run.json')
+
+        return unless File.file?(file_name)
+
+        run_id = JSON.parse(File.read(file_name))['run_id']
+
+        raise LocalCacheNotFoundError, 'Could not find any local cache to upload' if run_id.nil?
+
+        run_id
+      end
+
+      def upload_files
+        @upload_prefix = "#{@s3_uri}/#{@git.branch_ref}/#{@test_suite_id}/".sub(%r{/+$}, '/')
+        @upload_path = RSpecTracer.cache_path
+
+        return if system(
+          @aws_s3, 's3', 'cp',
+          File.join(@upload_path, 'last_run.json'),
+          @upload_prefix,
+          out: File::NULL, err: File::NULL
+        ) && system(
+          @aws_s3, 's3', 'cp',
+          File.join(@upload_path, @run_id),
+          "#{@upload_prefix}/#{@run_id}",
+          '--recursive',
+          out: File::NULL, err: File::NULL
+        )
+
+        raise CacheUploadError, 'Failed to upload cache files'
+      end
+    end
+  end
+end

data/lib/rspec_tracer/remote_cache/git.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module RSpecTracer
+  module RemoteCache
+    class Git
+      class GitOperationError < StandardError; end
+
+      attr_reader :branch_ref, :ref_list
+
+      def initialize
+        fetch_head_ref
+        fetch_branch_ref
+      end
+
+      def prepare_for_download
+        fetch_unreachable_refs
+        fetch_ancestry_refs
+        fetch_ordered_refs
+      end
+
+      private
+
+      def fetch_head_ref
+        @head_ref = `git rev-parse HEAD`.chomp
+
+        raise GitOperationError, 'Could not find HEAD commit sha' unless $CHILD_STATUS.success?
+      end
+
+      def fetch_branch_ref
+        @merged_parents = []
+        @ignored_refs = []
+
+        unless merged?
+          @branch_ref = @head_ref
+
+          return
+        end
+
+        @ignored_refs << @head_ref
+
+        fetch_merged_parents
+        fetch_merged_branch_ref
+      end
+
+      def merged?
+        system('git', 'rev-parse', 'HEAD^2', out: File::NULL, err: File::NULL)
+      end
+
+      def fetch_merged_parents
+        first_parent = `git rev-parse HEAD^1`.chomp
+        @merged_parents << first_parent if $CHILD_STATUS.success?
+
+        second_parent = `git rev-parse HEAD^2`.chomp
+        @merged_parents << second_parent if $CHILD_STATUS.success?
+
+        raise GitOperationError, 'Could not find merged commit parents' if @merged_parents.length != 2
+      end
+
+      def fetch_merged_branch_ref
+        @origin_head_ref = `git rev-parse origin/HEAD`.chomp
+        @branch_ref = nil
+
+        if @merged_parents.first != @origin_head_ref
+          @branch_ref = @head_ref
+          @ignored_refs = []
+
+          return
+        end
+
+        @branch_ref = @merged_parents.last
+        @ignored_refs = @ignored_refs.to_set | `git rev-list #{@branch_ref}..origin/HEAD`.chomp.split
+
+        raise GitOperationError, 'Could not find ignored refs' unless $CHILD_STATUS.success?
+      end
+
+      def fetch_unreachable_refs
+        command = <<-COMMAND.strip.gsub(/\s+/, ' ')
+          git fsck
+              --no-progress
+              --unreachable
+              --connectivity-only #{@branch_ref}
+            | awk '/commit/ { print $3 }'
+            | head -n 25
+        COMMAND
+
+        @unreachable_refs = `#{command}`.chomp.split
+
+        raise GitOperationError, 'Could not find unreachable refs' unless $CHILD_STATUS.success?
+      end
+
+      def fetch_ancestry_refs
+        @ancestry_refs = `git rev-list --max-count=25 #{@branch_ref}`.chomp.split
+
+        raise GitOperationError, 'Could not find ancestry refs' unless $CHILD_STATUS.success?
+      end
+
+      def fetch_ordered_refs
+        unordered_refs = (@unreachable_refs.to_set | @ancestry_refs) - @ignored_refs
+
+        command = <<-COMMAND.strip.gsub(/\s+/, ' ')
+          git rev-list
+            --topo-order
+            --no-walk=sorted
+            #{unordered_refs.to_a.join(' ')}
+        COMMAND
+
+        @ref_list = `#{command}`.chomp.split
+
+        raise GitOperationError, 'Could not find refs to download cache' unless $CHILD_STATUS.success?
+      end
+    end
+  end
+end

data/lib/rspec_tracer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RSpecTracer
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/lib/rspec_tracer.rb

@@ -17,6 +17,7 @@ require_relative 'rspec_tracer/coverage_reporter'
 require_relative 'rspec_tracer/defaults'
 require_relative 'rspec_tracer/example'
 require_relative 'rspec_tracer/html_reporter/reporter'
+require_relative 'rspec_tracer/remote_cache/cache'
 require_relative 'rspec_tracer/rspec_reporter'
 require_relative 'rspec_tracer/rspec_runner'
 require_relative 'rspec_tracer/ruby_coverage'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-tracer
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Abhimanyu Singh
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-08-30 00:00:00.000000000 Z
+date: 2021-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: docile
@@ -91,6 +91,8 @@ files:
 - lib/rspec_tracer/html_reporter/views/examples_dependency.erb
 - lib/rspec_tracer/html_reporter/views/files_dependency.erb
 - lib/rspec_tracer/html_reporter/views/layout.erb
+- lib/rspec_tracer/remote_cache/cache.rb
+- lib/rspec_tracer/remote_cache/git.rb
 - lib/rspec_tracer/reporter.rb
 - lib/rspec_tracer/rspec_reporter.rb
 - lib/rspec_tracer/rspec_runner.rb
@@ -103,7 +105,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/avmnu-sng/rspec-tracer
-  source_code_uri: https://github.com/avmnu-sng/rspec-tracer/tree/v0.3.0
+  source_code_uri: https://github.com/avmnu-sng/rspec-tracer/tree/v0.4.0
   changelog_uri: https://github.com/avmnu-sng/rspec-tracer/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/avmnu-sng/rspec-tracer/issues
 post_install_message: