rspec-tracer 0.6.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4dff7e48382045aef3821a6f863521c9f74823b5bbd12c16b09c41b47277124e
-  data.tar.gz: cff630db632b7fa96be3d3de675b994325f815c69613b84d891bc8313688ab67
+  metadata.gz: 1df1d0c90323ae123f24629f74f654bce0fff93bba8e8b052388d582dfb64d8f
+  data.tar.gz: 5caabede1fb71ffcbbd70f0e9bfe8ca355303e843dbb99cacf14f146149afe5a
 SHA512:
-  metadata.gz: 83348356f2a12e930d73cec63e867a13ffab85e428696fc3d91dfeab5a691bac4641d848330d0225e08bc7156d0902faffc8ecd8f4a8871b24c093513c6a8b0d
-  data.tar.gz: 2cc9084dbeb9ca0fa26997b33b486360e3c1fe8b7efbb91f28b3a1786bf0e966b32f75b5d7b98a3488c5ced8d1704005f1c1a5972e876e25d3877a40d8068379
+  metadata.gz: 5ad9ec360d867ed745039fc2cf2a4aef314912a5b6a596c8c79e9d6615b00f2b578f5d3a164c2725ed710d9b0aa055855c607eebe52f7b032d1b959d483cb079
+  data.tar.gz: 347236ad3e59372ff1cf33aa3c812ae5a22911ff6b46bfdfced44b96ef80161c4da0798a9afecf96846bc44963713bac4aa625c714266431b975c3152ebd92b1

data/CHANGELOG.md

@@ -1,3 +1,29 @@
+## [0.9.0] - 2021-09-15
+
+### Added
+
+- Handling all examples filtered by RSpec (#34)
+- Warn on incorrect analysis to stop using RSpec Tracer (#35)
+- Run `SimpleCov.at_exit` hook (#36)
+
+## [0.8.0] - 2021-09-13
+
+### Fixed
+
+Unable to find cache in case of history rewrites (#33)
+
+## [0.7.0] - 2021-09-10
+
+### Fixed
+
+Missing spec files for the gem
+
+## [0.6.2] - 2021-09-07
+
+### Added
+
+Improvements towards reducing dependency and coverage processing time (#26)
+
 ## [0.6.1] - 2021-09-06
 
 ### 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,25 @@ 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)
+* [When Should You Not Use RSpec Tracer](#when-should-you-not-use-rspec-tracer)
 
 ## Demo
 
@@ -66,317 +50,406 @@ 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', 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.9', 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
-
-To get better control on execution, you can use the following environment variables
-whenever required.
-
-### BUNDLE_PATH
-
-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.
-
-### 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
-any tests. Note that it will continue to maintain cache files and generate reports.
-
-```ruby
-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_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.**
 
-### RSPEC_TRACER_UPLOAD_LOCAL_CACHE
+    ```ruby
+    # Load RSpec Tracer
+    require 'rspec_tracer'
+    RSpecTracer.start
+    ```
 
-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.
+    **If you are using SimpleCov**, load RSpec Tracer right after the SimpleCov load
+    and launch:
 
-### RSPEC_TRACER_VERBOSE
+    ```ruby
+    require 'simplecov'
+    SimpleCov.start
 
-To print the intermediate steps and time taken, use this environment variable:
+    # Load RSpec Tracer
+    require 'rspec_tracer'
+    RSpecTracer.start
+    ```
 
-```sh
-export RSPEC_TRACER_VERBOSE=true
-```
+    If you use RSpec Tracer with SimpleCov, then **SimpleCov would not report branch
+    coverage results even when enabled**.
 
-### TEST_SUITES
+3. After running your tests, open `rspec_tracer_report/index.html` in the browser
+of your choice.
 
-Set this environment variable when using test suite id. It determines the total
-number of different test suites you are running.
+## 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
-export TEST_SUITES=8
-```
-
-### TEST_SUITE_ID
+spec = Gem::Specification.find_by_name('rspec-tracer')
 
-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
+load "#{spec.gem_dir}/lib/rspec_tracer/remote_cache/Rakefile"
 ```
 
-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.
-
+Before running tests, download the remote 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:download
 ```
 
-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.
-
+After running tests, upload the local cache using the following rake task:
 ```sh
-$ TEST_SUITE_ID=1 bundle exec rake rspec_tracer:remote_cache:upload
+bundle exec rake rspec_tracer:remote_cache:upload
 ```
 
-## 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)
+You must set the following two environment variables:
 
-### Flaky Examples
+- **`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
+  ```
 
-These reports provide flaky tests information. Assuming **the following two tests
-failed in the first run.**
+## Advanced Configuration
 
-**Next Run**
+Configuration settings can be applied in three formats, which are completely equivalent:
 
-![](./readme_files/flaky_examples_report_first_run.png)
+- The most common way is to configure it directly in your start block:
+  ```ruby
+  RSpecTracer.start do
+    config_option 'foo'
+  end
+  ```
+- You can also set all configuration options directly:
+  ```ruby
+  RSpecTracer.config_option 'foo'
+  ```
 
-**Another Run**
+- 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
+  ```
 
-![](./readme_files/flaky_examples_report_next_run.png)
+The available configuration options are:
 
-### Examples Dependency
+- **`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.
 
-These reports show a list of dependent files for each test.
+```ruby
+RSpecTracer.start do
+  # Configure project root
+  root '/tmp/my_project'
 
-![](./readme_files/examples_dependency_report.png)
+  # Clear existing filters
+  filters.clear
+  # Add dependent files filter
+  add_filter %r{^/tasks/}
 
-### Files Dependency
+  # Clear existing coverage filters
+  coverage_filters.clear
+  # Add coverage files filter
+  add_coverage_filter %w[/features/ /spec/ /tests/]
 
-These reports provide information on the total number of tests that will run after changing this particular file.
+  # Define glob to track files in the coverage report
+  coverage_track_files '{app,lib}/**/*.rb'
+end
+```
 
-![](./readme_files/files_dependency_report.png)
+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.
 
-## Configuring RSpec Tracer
+## Filters
 
-Configuration settings can be applied in three formats, which are completely equivalent:
+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
+```
 
-- The most common way is to configure it directly in your start block:
+### Defining Custom Filteres
 
-    ```ruby
-    RSpecTracer.start do
-      config_option 'foo'
+You can currently define a filter using either a String or Regexp (that will then
+be Regexp-matched against each source file's name relative to the project root),
+a block or by passing in your own Filter class.
+
+- **String Filter**: The string filter matches files that have the given string
+in their name. For example, the following string filter will remove all files that
+have `"/helpers/"` in their name.
+  ```ruby
+  RSpecTracer.start do
+    add_filter '/helpers/'
+  end
+  ```
+
+- **Regex Filter**: The regex filter removes all files that have a successful name
+match against the given regex expression. This simple regex filter will remove
+all files that start with `%r{^/helper/}` in their name:
+  ```ruby
+  RSpecTracer.start do
+    add_filter %r{^/helpers/}
+  end
+  ```
+
+- **Block Filter**: Block filters receive a `Hash` object and expect your block
+to return either **true** (if the file is to be removed from the result) or **false**
+(if the result should be kept). In the below example, the filter will remove all
+files that match `"/helpers/"` in their path.
+  ```ruby
+  RSpecTracer.start do
+    add_filter do |source_file|
+      source_file[:file_path].include?('/helpers/')
     end
-    ```
-- You can also set all configuration options directly:
-
-    ```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:
+  end
+  ```
 
-    ```ruby
-    RSpecTracer.configure do
-      config_option 'foo'
-    end
-    ```
+  You can also use `source_file[:name]` to define the return value of the block
+  filter for the given source file.
 
-## Filters
+- **Array Filter**: You can pass in an array containing any of the other filter types:
+  ```ruby
+  RSpecTracer.start do
+    add_filter ['/helpers/', %r{^/utils/}]
+  end
+  ```
 
-RSpec Tracer supports two types of filters:
+## Environment Variables
 
-- To exclude selected files from the dependency list of tests:
+To get better control on execution, you can use the following environment variables
+whenever required.
 
-    ```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.
+- **`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`.
 
-    ```ruby
-    RSpecTracer.start do
-      add_coverage_filter %r{^/tasks/}
-    end
-    ```
+- **`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.
 
-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.
+- **`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.
 
-### Defining Custom Filteres
+- **`RSPEC_TRACER_VERBOSE (default: false)`:** To print the intermediate steps
+and time taken, use this environment variable.
 
-You can currently define a filter using either a String or Regexp (that will then
-be Regexp-matched against each source file's path), a block or by passing in your
-own Filter class.
+- **`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
+  ```
 
-#### String Filter
+- **`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
+  ```
 
-```ruby
-RSpecTracer.start do
-  add_filter '/helpers/'
-end
-```
+## When Should You Not Use RSpec Tracer
 
-This simple string filter will remove all files that match "/helpers/" in their path.
+To uniquely identify the examples is one of the requirements for the correctness
+of the RSpec Tracer. Sometimes, it would not be possible to do so depending upon
+how we have written the specs. The following attributes determine the uniqueness:
 
-#### Regex Filter
+- The example group
+- The example full description
+- The spec file location, i.e., file name and line number
+- All the shared examples and contexts
 
+Consider the following `Calculator` module:
 ```ruby
-RSpecTracer.start do
-  add_filter %r{^/helpers/}
+module Calculator
+  module_function
+
+  def add(a, b) a + b; end
+  def sub(a, b) a - b; end
+  def mul(a, b) a * b; end
 end
 ```
 
-This simple regex filter will remove all files that start with /helper/ in their path.
+And the corresponding spec file `spec/calculator_spec.rb`:
+```ruby
+RSpec.describe Calculator do
+  describe '#add' do
+    [
+      [1, 2, 3],
+      [0, 0, 0],
+      [5, 32, 37],
+      [-1, -8, -9],
+      [10, -10, 0]
+    ].each { |a, b, r| it { expect(described_class.add(a, b)).to eq(r) } }
+  end
 
-#### Block Filter
+  describe '#sub' do
+    [
+      [1, 2, -1],
+      [10, 0, 10],
+      [37, 5, 32],
+      [-1, -8, 7],
+      [10, 10, 0]
+    ].each do |a, b, r|
+      it 'performs subtraction' do
+        expect(described_class.sub(a, b)).to eq(r)
+      end
+    end
+  end
 
-```ruby
-RSpecTracer.start do
-  add_filter do |source_file|
-    source_file[:file_path].include?('/helpers/')
+  describe '#mul' do
+    [
+      [1, 2, -2],
+      [10, 0, 0],
+      [5, 7, 35],
+      [-1, -8, 8],
+      [10, 10, 100]
+    ].each do |a, b, r|
+      it "multiplies #{a} and #{b} to #{r}" do
+        expect(described_class.mul(a, b)).to eq(r)
+      end
+    end
   end
 end
 ```
 
-Block filters receive a `Hash` object and expect your block to return either true
-(if the file is to be removed from the result) or false (if the result should be kept).
-In the above example, the filter will remove all files that match "/helpers/" in their path.
+Running the spec with `bundle exec rspec spec/calculator_spec.rb` generates the
+following output:
+```
+Calculator
+  #mul
+    multiplies 5 and 7 to 35
+    multiplies 10 and 10 to 100
+    multiplies 10 and 0 to 0
+    multiplies 1 and 2 to -2 (FAILED - 1)
+    multiplies -1 and -8 to 8
+  #add
+    example at ./spec/calculator_spec.rb:13
+    example at ./spec/calculator_spec.rb:13
+    example at ./spec/calculator_spec.rb:13
+    example at ./spec/calculator_spec.rb:13
+    example at ./spec/calculator_spec.rb:13
+  #sub
+    performs subtraction
+    performs subtraction
+    performs subtraction
+    performs subtraction
+    performs subtraction
+```
 
-#### Array Filter
+In this scenario, RSpec Tracer cannot determine the `Calculator#add` and
+`Calculator#sub` group examples. Also, it will ask you not to use the gem unless
+you have made some changes to your spec files.
 
-```ruby
-RSpecTracer.start do
-  add_filter ['/helpers/', %r{^/utils/}]
-end
 ```
-
-You can pass in an array containing any of the other filter types.
+================================================================================
+                IMPORTANT NOTICE -- DO NOT USE RSPEC TRACER
+================================================================================
+    It would be best to make changes so that the RSpec tracer can uniquely
+    identify all the examples, and then you can enable the RSpec tracer back.
+================================================================================
+
+RSpec tracer could not uniquely identify the following 10 examples:
+  - Example ID: eabd51a899db4f64d5839afe96004f03 (5 examples)
+      * Calculator#add (spec/calculator_spec.rb:13)
+      * Calculator#add (spec/calculator_spec.rb:13)
+      * Calculator#add (spec/calculator_spec.rb:13)
+      * Calculator#add (spec/calculator_spec.rb:13)
+      * Calculator#add (spec/calculator_spec.rb:13)
+  - Example ID: 72171b502c5a42b9aa133f165cf09ec2 (5 examples)
+      * Calculator#sub performs subtraction (spec/calculator_spec.rb:24)
+      * Calculator#sub performs subtraction (spec/calculator_spec.rb:24)
+      * Calculator#sub performs subtraction (spec/calculator_spec.rb:24)
+      * Calculator#sub performs subtraction (spec/calculator_spec.rb:24)
+      * Calculator#sub performs subtraction (spec/calculator_spec.rb:24)
+```
 
 ## Contributing