rspec-tracer 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4825c225fdac05b09d4c56c5b6b191d0b32ad4198fc39b72a215bef3d066f7bd
-  data.tar.gz: 4bdcb243ed2cf200f6dae4b00b4dfd50fbc8bb70b9f59552056059ec3be643b1
+  metadata.gz: 675be2bd6603501deb282508ea234808f0bbdf60c2b626611919f84c32bb4ba9
+  data.tar.gz: 591be21b4e97c50f33385111ac758665a97e83ca82e154cd3b86d32133f7ef52
 SHA512:
-  metadata.gz: 80dff35e9e15e2b28bd5c0658fdc027b659a9a1cf4265e17d7207ce0327bc975b05890d9e23fd9b22faa81b6a471d9a3d68d5bec0e501314907534796ff6088c
-  data.tar.gz: 77d1e9a4a9c4fe26713da06d594e7c6088655a2bc84c7e38ccd145c27f60247a9554043631c526c4a262637304c730c59ae767b3d4e8462ebc4e7e397e330055
+  metadata.gz: 1ab8ca453da65dd7185fa4869633d9b9ab85fb5c73cfb45929928a492d58d0e16d24e3bcef2466ceae4408c7e1ad2e5ab3f10137061ab684b1decf885809607d
+  data.tar.gz: 8dc1d3078f2c16c8ee5142c03d05222dd0bd458c979bca0a35ee1b1e44fead38ed2c1a6d84795a93f2a4d7a15c58da40562f4dae360f22e65f1518fc0ddecf75

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.8.0] - 2021-09-13
+
+### Fixed
+
+Unable to find cache in case of history rewrites (#33)
+
 ## [0.7.0] - 2021-09-10
 
 ### Fixed

data/README.md

@@ -1,8 +1,12 @@
 ![](./readme_files/rspec_tracer.png)
 
-RSpec Tracer is a **specs dependency analysis tool** and a **test skipper for RSpec**.
-It maintains a list of files for each test, enabling itself to skip tests in the
-subsequent runs if none of the dependent files are changed.
+[![Maintainability](https://api.codeclimate.com/v1/badges/eabce2757839c08d8f8d/maintainability)](https://codeclimate.com/github/avmnu-sng/rspec-tracer/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/eabce2757839c08d8f8d/test_coverage)](https://codeclimate.com/github/avmnu-sng/rspec-tracer/test_coverage)
+[![Gem Version](https://badge.fury.io/rb/rspec-tracer.svg)](https://badge.fury.io/rb/rspec-tracer)
+
+RSpec Tracer is a **specs dependency analyzer**, **flaky tests detector**, **tests accelerator**,
+and **coverage reporter** tool. It maintains a list of files for each test, enabling
+itself to skip tests in the subsequent runs if none of the dependent files are changed.
 
 It uses [Ruby's built-in coverage library](https://ruby-doc.org/stdlib/libdoc/coverage/rdoc/Coverage.html)
 to keep track of the coverage for each test. For each test executed, the coverage
@@ -18,45 +22,24 @@ 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.
 
-## Note
+RSpec Tracer requires **Ruby 2.5+** and **rspec-core >= 3.6.0**. To use with **Rails 5+**,
+make sure to use **rspec-rails >= 4.0.0**. If you are using SimpleCov, it is
+recommended to use **simplecov >= 0.12.0**. To use RSpec Tracer **cache on CI**, you
+need to have an **S3 bucket** and **[AWS CLI](https://aws.amazon.com/cli/)**
+installed.
 
-You should take some time and go through the **[document](./RSPEC_TRACER.md)** describing
-the **intention** and implementation details of **managing dependency**, **managing flaky tests**,
-**skipping tests**, and **caching on CI**. You must go through the README file before
-integrating the gem into your project to better understand what is happening.
+You should take some time and go through the **[document](./RSPEC_TRACER.md)**
+describing the **intention** and implementation details of **managing dependency**,
+**managing flaky tests**, **skipping tests**, and **caching on CI**.
 
 ## Table of Contents
 
 * [Demo](#demo)
-* [Installation](#installation)
-  * [Compatibility](#compatibility)
-  * [Additional Tools](#additional-tools)
 * [Getting Started](#getting-started)
-* [Environment Variables](#environment-variables)
-  * [BUNDLE_PATH](#bundle_path)
-  * [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)
-  * [RSPEC_TRACER_VERBOSE](#rspec_tracer_verbose)
-  * [TEST_SUITES](#test_suites)
-  * [TEST_SUITE_ID](#test_suite_id)
-* [Sample Reports](#sample-reports)
-    * [Examples](#examples)
-    * [Flaky Examples](#flaky-examples)
-    * [Examples Dependency](#examples-dependency)
-    * [Files Dependency](#files-dependency)
-* [Configuring RSpec Tracer](#configuring-rspec-tracer)
+* [Configuring CI Caching](#configuring-ci-caching)
+* [Advanced Configuration](#advanced-configuration)
 * [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)
+* [Environment Variables](#environment-variables)
 
 ## Demo
 
@@ -66,267 +49,210 @@ integrating the gem into your project to better understand what is happening.
 **Next Run**
 ![](./readme_files/next_run.gif)
 
+You get the following three reports:
 
-## Installation
+### All Examples Report
 
-Add this line to your `Gemfile` and `bundle install`:
-```ruby
-gem 'rspec-tracer', '~> 0.6', group: :test, require: false
-```
+These reports provide basic test information:
 
-And, add the followings to your `.gitignore`:
-```
-/rspec_tracer_cache/
-/rspec_tracer_coverage/
-/rspec_tracer_report/
-```
+**First Run**
 
-### Compatibility
+![](./readme_files/examples_report_first_run.png)
 
-RSpec Tracer requires **Ruby 2.5+** and **rspec-core >= 3.6.0**. To use with **Rails 5+**,
-make sure to use **rspec-rails >= 4.0.0**. If you are using SimpleCov, it is
-recommended to use **simplecov >= 0.12.0**.
+**Next Run**
 
-### Additional Tools
+![](./readme_files/examples_report_next_run.png)
 
-To use RSpec Tracer on CI, you need to have an **S3 bucket** and
-**[AWS CLI](https://aws.amazon.com/cli/)** installed.
+### Flaky Examples Report
 
-## Getting Started
+These reports provide flaky tests information. Assuming **the following two tests
+failed in the first run.**
 
-1. **Load and Start RSpec Tracer**
+**Next Run**
 
-    - **With SimpleCov**
+![](./readme_files/flaky_examples_report_first_run.png)
 
-        If you are using `SimpleCov`, load RSpec Tracer right after the SimpleCov load
-        and launch:
+**Another Run**
 
-        ```ruby
-        require 'simplecov'
-        SimpleCov.start
+![](./readme_files/flaky_examples_report_next_run.png)
 
-        # Load RSpec Tracer
-        require 'rspec_tracer'
-        RSpecTracer.start
-        ```
+### Examples Dependency Report
 
-        Currently using RSpec Tracer with SimpleCov has the following two limitations:
-        - SimpleCov **won't be able to provide branch coverage report** even when enabled.
-        - RSpec Tracer **nullifies the `SimpleCov.at_exit`** callback.
+These reports show a list of dependent files for each test.
 
-    - **Without SimpleCov**
+![](./readme_files/examples_dependency_report.png)
 
-        Load and launch RSpec Tracer at the very top of `spec_helper.rb` (or `rails_helper.rb`,
-        `test/test_helper.rb`). Note that `RSpecTracer.start` must be issued **before loading
-        any of the application code.**
+### Files Dependency Report
 
-        ```ruby
-        # Load RSpec Tracer
-        require 'rspec_tracer'
-        RSpecTracer.start
-        ```
+These reports provide information on the total number of tests that will run after changing this particular file.
 
-2. To enable RSpec Tracer to share cache between different builds on CI, update the
-Rakefile in your project to have the following:
+![](./readme_files/files_dependency_report.png)
 
-    ```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:
+## Getting Started
 
-    ```sh
-    bundle exec rake rspec_tracer:remote_cache:download
+1. Add this line to your `Gemfile` and `bundle install`:
+    ```ruby
+    gem 'rspec-tracer', '~> 0.7', group: :test, require: false
     ```
-4. Run the tests with RSpec using `bundle exec rspec`.
-5. After running tests, upload the local cache using the following rake task:
 
-    ```sh
-    bundle exec rake rspec_tracer:remote_cache:upload
+    And, add the followings to your `.gitignore`:
     ```
-6. After running your tests, open `rspec_tracer_report/index.html` in the
-browser of your choice.
-
-## Environment Variables
+    /rspec_tracer_cache/
+    /rspec_tracer_coverage/
+    /rspec_tracer_report/
+    ```
+2. Load and launch RSpec Tracer at the very top of `spec_helper.rb` (or `rails_helper.rb`,
+`test/test_helper.rb`). Note that `RSpecTracer.start` must be issued **before loading
+any of the application code.**
 
-To get better control on execution, you can use the following environment variables
-whenever required.
+    ```ruby
+    # Load RSpec Tracer
+    require 'rspec_tracer'
+    RSpecTracer.start
+    ```
 
-### BUNDLE_PATH
+    **If you are using SimpleCov**, load RSpec Tracer right after the SimpleCov load
+    and launch:
 
-Since the bundler uses a vendor directory inside the project, it might cause slowness
-depending on the vendor size. You can configure the bundle path outside of the project
-using `BUNDLE_PATH` environment variable, for example, `BUNDLE_PATH=$HOME/vendor/bundle`.
-Make sure to cache this directory in the CI configuration.
+    ```ruby
+    require 'simplecov'
+    SimpleCov.start
 
-### CI
+    # Load RSpec Tracer
+    require 'rspec_tracer'
+    RSpecTracer.start
+    ```
 
-Mostly all the CI have `CI=true`. If not, you should explicitly set it to `true`.
+    Currently using RSpec Tracer with SimpleCov has the following two limitations:
 
-### LOCAL_AWS
+    - SimpleCov **won't be able to provide branch coverage report** even when enabled.
+    - RSpec Tracer **nullifies the `SimpleCov.at_exit`** callback.
 
-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`.
+3. After running your tests, open `rspec_tracer_report/index.html` in the browser
+of your choice.
 
-### RSPEC_TRACER_NO_SKIP
-
-The default value is `false.` If set to `true`, the RSpec Tracer will not skip
-any tests. Note that it will continue to maintain cache files and generate reports.
+## Configuring CI Caching
 
+To enable RSpec Tracer to share cache between different builds on CI, update the
+Rakefile in your project to have the following:
 ```ruby
-RSPEC_TRACER_NO_SKIP=true bundle exec rspec
-```
-
-### RSPEC_TRACER_S3_URI
+spec = Gem::Specification.find_by_name('rspec-tracer')
 
-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
+load "#{spec.gem_dir}/lib/rspec_tracer/remote_cache/Rakefile"
 ```
 
-### 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.
-
-### RSPEC_TRACER_VERBOSE
-
-To print the intermediate steps and time taken, use this environment variable:
-
+Before running tests, download the remote cache using the following rake task:
 ```sh
-export RSPEC_TRACER_VERBOSE=true
+bundle exec rake rspec_tracer:remote_cache:download
 ```
 
-### 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
-```
-
-### TEST_SUITE_ID
-
-If you have a large set of tests to run, it is recommended to run them in
-separate groups. This way, RSpec Tracer is not overwhelmed with loading massive
-cached data in the memory. Also, it generates and uses cache for specific test suites
-and not merge them.
-
-```ruby
-TEST_SUITE_ID=1 bundle exec rspec spec/models
-TEST_SUITE_ID=2 bundle exec rspec spec/helpers
-```
-
-If you run parallel builds on the CI, you should specify the test suite ID and
-the total number of test suites when downloading the cache files.
-
+After running tests, upload the local cache using the following rake task:
 ```sh
-$ TEST_SUITES=5 TEST_SUITE_ID=1 bundle exec rake rspec_tracer:remote_cache:download
+bundle exec rake rspec_tracer:remote_cache:upload
 ```
 
-In this case, the appropriate cache should have all the cache files available on
-the S3 for each test suite, not just for the current one. Also, while uploading,
-make sure to provide the test suite id.
+You must set the following two environment variables:
 
-```sh
-$ TEST_SUITE_ID=1 bundle exec rake rspec_tracer:remote_cache:upload
-```
+- **`GIT_BRANCH`** is the git branch name you are running the CI build on.
+- **`RSPEC_TRACER_S3_URI`** is the S3 bucket path to store the cache files.
+  ```sh
+  export RSPEC_TRACER_S3_URI=s3://ci-artifacts-bucket/rspec-tracer-cache
+  ```
 
-## Sample Reports
-
-You get the following three reports:
-
-### Examples
-
-These reports provide basic test information:
-
-**First Run**
-
-![](./readme_files/examples_report_first_run.png)
-
-**Next Run**
-
-![](./readme_files/examples_report_next_run.png)
-
-### Flaky Examples
-
-These reports provide flaky tests information. Assuming **the following two tests
-failed in the first run.**
-
-**Next Run**
-
-![](./readme_files/flaky_examples_report_first_run.png)
-
-**Another Run**
-
-![](./readme_files/flaky_examples_report_next_run.png)
-
-### Examples Dependency
-
-These reports show a list of dependent files for each test.
-
-![](./readme_files/examples_dependency_report.png)
-
-### Files Dependency
-
-These reports provide information on the total number of tests that will run after changing this particular file.
-
-![](./readme_files/files_dependency_report.png)
-
-## Configuring RSpec Tracer
+## Advanced Configuration
 
 Configuration settings can be applied in three formats, which are completely equivalent:
 
 - The most common way is to configure it directly in your start block:
-
-    ```ruby
-    RSpecTracer.start do
-      config_option 'foo'
-    end
-    ```
+  ```ruby
+  RSpecTracer.start do
+    config_option 'foo'
+  end
+  ```
 - You can also set all configuration options directly:
-
-    ```ruby
-    RSpecTracer.config_option 'foo'
-    ```
+  ```ruby
+  RSpecTracer.config_option 'foo'
+  ```
 
 - If you do not want to start tracer immediately after launch or want to add
 additional configuration later on in a concise way, use:
+  ```ruby
+  RSpecTracer.configure do
+    config_option 'foo'
+  end
+  ```
 
-    ```ruby
-    RSpecTracer.configure do
-      config_option 'foo'
-    end
-    ```
+The available configuration options are:
 
-## Filters
+- **`root dir`** to set the project root. The default value is the current working
+directory.
+- **`add_filter filter`** to apply [filters](#filters) on the source files to
+exclude them from the dependent files list.
+- **`filters.clear`** to remove the default configured dependent files filters.
+- **`add_coverage_filter filter`** to apply [filters](#filters) on the source files
+to exclude them from the coverage report.
+- **`coverage_filters.clear`** to remove the default configured coverage files filters.
+- **`coverage_track_files glob`** to include files in the given glob pattern in
+the coverage report if these files are not already present.
 
-RSpec Tracer supports two types of filters:
+```ruby
+RSpecTracer.start do
+  # Configure project root
+  root '/tmp/my_project'
 
-- To exclude selected files from the dependency list of tests:
+  # Clear existing filters
+  filters.clear
+  # Add dependent files filter
+  add_filter %r{^/tasks/}
 
-    ```ruby
-    RSpecTracer.start do
-      add_filter %r{^/helpers/}
-    end
-    ```
-- To exclude selected files from the coverage data. You should only use this
-when not using SimpleCov.
+  # Clear existing coverage filters
+  coverage_filters.clear
+  # Add coverage files filter
+  add_coverage_filter %w[/features/ /spec/ /tests/]
 
-    ```ruby
-    RSpecTracer.start do
-      add_coverage_filter %r{^/tasks/}
-    end
-    ```
+  # Define glob to track files in the coverage report
+  coverage_track_files '{app,lib}/**/*.rb'
+end
+```
+
+You can configure the RSpec Tracer reports directories using the following environment
+variables:
+
+- **`RSPEC_TRACER_CACHE_DIR`** to update the default cache directory (`rspec_tracer_cache`).
+  ```sh
+  export RSPEC_TRACER_CACHE_DIR=/tmp/rspec_tracer_cache
+  ```
+- **`RSPEC_TRACER_COVERAGE_DIR`** to update the default coverage directory (`rspec_tracer_coverage`).
+  ```sh
+  export RSPEC_TRACER_CACHE_DIR=/tmp/rspec_tracer_coverage
+  ```
+- **`RSPEC_TRACER_REPORT_DIR`** to update the default html reports directory (`rspec_tracer_report`).
+  ```sh
+  export RSPEC_TRACER_CACHE_DIR=/tmp/rspec_tracer_report
+  ```
+
+These settings are available through environment variables because the rake tasks
+to download and upload the cache files need to use the same directories.
+
+## Filters
 
-By default, a filter is applied that removes all files OUTSIDE of your project's
-root directory - otherwise you'd end up with the source files in the gems you are
-using as tests dependency.
+By default, RSpec Tracer ignores all the files outside of the project root directory -
+otherwise you would end up with the source files in the gems you are using in the
+project. It also applies the following filters:
+```ruby
+RSpecTracer.configure do
+  add_filter '/vendor/bundle/'
+
+  add_coverage_filter %w[
+    /autotest/
+    /features/
+    /spec/
+    /test/
+    /vendor/bundle/
+  ].freeze
+end
+```
 
 ### Defining Custom Filteres
 
@@ -378,6 +304,42 @@ end
 
 You can pass in an array containing any of the other filter types.
 
+## Environment Variables
+
+To get better control on execution, you can use the following environment variables
+whenever required.
+
+- **`LOCAL_AWS (default: false)`:** 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 (default: false)`:** Use this environment variables to
+not skip any tests. Note that it will continue to maintain cache files and generate
+reports.
+
+- **`RSPEC_TRACER_UPLOAD_LOCAL_CACHE (default: false)`:** 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.
+
+- **`RSPEC_TRACER_VERBOSE (default: false)`:** To print the intermediate steps
+and time taken, use this environment variable.
+
+- **`TEST_SUITES`:** Set this environment variable when running parallel builds
+in the CI. It determines the total number of different test suites you are running.
+  ```sh
+  export TEST_SUITES=8
+  ```
+
+- **`TEST_SUITE_ID`:** If you have a large set of tests to run, it is recommended
+to run them in separate groups. This way, RSpec Tracer is not overwhelmed with
+loading massive cached data in the memory. Also, it generates and uses cache for
+specific test suites and not merge them.
+  ```sh
+  TEST_SUITE_ID=1 bundle exec rspec spec/models
+  TEST_SUITE_ID=2 bundle exec rspec spec/helpers
+  ```
+
 ## Contributing
 
 Read the [contribution guide](https://github.com/avmnu-sng/rspec-tracer/blob/main/.github/CONTRIBUTING.md).