rspec-tracer 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9aaeb8a00f4cebc311367e6a61d59526014849df9f7fe890455d64cef16d435f
-  data.tar.gz: b803d5104a0a35f783bdd15b7a43252a1cfddcdd56d9f0a26c5a07bb8c36ef5e
+  metadata.gz: 5e89ead4a61c2b6d881fe8ca3fbcfec3ab94e7d8b78f759de5fe64e4e22b693d
+  data.tar.gz: 8993bc089a6185bdd7f0e20f71ad69b13fbd96c679bf67878c69b4f52dacd12f
 SHA512:
-  metadata.gz: 56acd78d6d4bf7b6270e8517a82d0bb1237dd78518a22d1a84a96de29e00c59379092cd725cc276d3f59ca2916306835c38426917747dcaf278e45d611c99389
-  data.tar.gz: a4e026b2c6fdaad653bd48063c9d0b771e7e7bc8876f653cc2e32279930d6a043b546ab1c7a713e12aac934f1f069497decdb5856246d4ee8033e905577be1db
+  metadata.gz: 91dc8066a66b706cfc02e9cb1050c61fc2e6bfa15d7353d056b11edb854ac493a99770516ce57e9ef4649494a0d99573b9dc8e441ead128b9e28abce9e2e21c1
+  data.tar.gz: 21a2cceab3b2cd3f1c3051542a1267d03a7cb499417f9501502a8c1bac3ac62e96821a1c07ea977768adca4b806a1fffca13b0e2946db95f031e877bc5bc4ebd

data/CHANGELOG.md

@@ -1,3 +1,72 @@
+## [1.1.1] - 2026-04-23
+
+### Fixed
+
+- **parallel_tests at-exit deadlock** — `parallel_tests_last_process?`
+  relied on a lock file written during `RSpecTracer.start` to identify
+  the last worker. If a fast worker reached `at_exit` before a slower
+  peer had loaded `spec_helper` and registered its `TEST_ENV_NUMBER`,
+  both workers could self-elect as the last process, both entered
+  `::ParallelTests.wait_for_other_processes_to_finish`, and deadlocked
+  on each other's pid. The elector now delegates to
+  `::ParallelTests.first_process?`, which reads immutable env vars set
+  by the parent at worker spawn. Exactly one worker is elected per run,
+  regardless of boot-time ordering or runner CPU count. No public-API
+  change — the `rspec_tracer.lock` file is still written and cleaned
+  up, just no longer consulted.
+
+## [1.1.0] - 2026-04-20
+
+### Added
+
+- Ruby 3.1, 3.2, 3.3, 3.4, 4.0 are now CI-gated.
+- Rails 7.0, 7.1, 7.2 are CI-gated via a reference sample app.
+- Regression specs for four crash bugs (B1–B4) under
+  `spec/lib/rspec_tracer/`.
+
+### Fixed
+
+- **B1** — `Cache#cached_examples_coverage` returns `{}` (not `nil`)
+  when `last_run.json` is present but `examples_coverage.json` is
+  missing; previously this leaked nil into the missed-coverage merge.
+- **B2** — `Runner#generate_missed_coverage` tolerates a nil cached
+  coverage map and nil line-strength entries; both are treated as
+  empty / zero.
+- **B3** — `Runner#register_{file,example_file}_dependency` skips
+  (logs debug, returns false) when `SourceFile.from_path` /
+  `.from_name` cannot resolve the file (e.g. gem-generated examples
+  or files deleted between runs).
+- **B4** — `CoverageReporter#merge_coverage` treats nil existing
+  line coverage as 0 when summing skipped-test contributions.
+- Custom filter and coverage-filter blocks now reach
+  `RSpecTracer::Filter.register` — the DSL wrappers were dropping
+  the block, causing `add_filter { |sf| … }` to raise
+  `ArgumentError`.
+- `load_global_config.rb` wraps `Dir.home` / `Etc.getpwuid.dir` /
+  `File.expand_path("~user")` in `rescue ArgumentError` so gem
+  load never crashes in minimal containers where HOME is unset and
+  the passwd database has no matching entry.
+
+### Changed
+
+- **Behavior change (default filters)** — the default dependency
+  and coverage filter lists now exclude Ruby installation /
+  toolchain paths: `/lib/rspec_tracer/`, `/lib/rspec_tracer.rb`,
+  `/usr/local/lib/ruby/`, `/usr/local/bundle/`,
+  `/opt/hostedtoolcache/`, `/.rbenv/versions/`,
+  `/.asdf/installs/ruby/`, `/.rvm/`. Previously only
+  `/vendor/bundle/` was filtered. A test that previously recorded
+  a dependency on a gem file or Ruby stdlib file (because of a
+  custom install path like rbenv or asdf) will no longer record
+  that dependency — those paths are handled by `Gemfile.lock` /
+  the Ruby version file, not by coverage tracking. If you relied
+  on the old narrow default, add your own `add_filter` /
+  `add_coverage_filter` to clear the extras.
+
+### Removed
+
+- Support for Ruby ≤ 3.0 and Rails ≤ 6.x (EOL).
+
 ## [1.0.0] - 2021-10-21
 
 ### Added

data/README.md

@@ -1,10 +1,10 @@
 ![](./readme_files/rspec_tracer.png)
 
-[![Discord](https://badgen.net/badge/icon/discord?icon=discord&label)](https://discord.gg/H2G9yWeuRZ)
-[![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)
+[![Open Source Helpers](https://www.codetriage.com/avmnu-sng/rspec-tracer/badges/users.svg)](https://www.codetriage.com/avmnu-sng/rspec-tracer)
 [![Gem Version](https://badge.fury.io/rb/rspec-tracer.svg)](https://badge.fury.io/rb/rspec-tracer)
 
+![](./readme_files/next_run.gif)
+
 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.
@@ -25,90 +25,39 @@ we can also analyze the coupling between different components and much more.
 
 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
+recommended to use **simplecov >= 0.17.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 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)
 * [Getting Started](#getting-started)
   * [Working with JRuby](#working-with-jruby)
   * [Working with Parallel Tests](#working-with-parallel-tests)
-* [Configuring CI Caching](#configuring-ci-caching)
+* [Configuring CI](#configuring-ci)
 * [Advanced Configuration](#advanced-configuration)
+  * [Available Settings](#available-settings)
 * [Filters](#filters)
-* [Environment Variables](#environment-variables)
 * [Duplicate Examples](#duplicate-examples)
-
-## Demo
-
-**First Run**
-![](./readme_files/first_run.gif)
-
-**Next Run**
-![](./readme_files/next_run.gif)
-
-You get the following three reports:
-
-### All Examples Report
-
-These reports provide basic test information:
-
-**First Run**
-
-![](./readme_files/examples_report_first_run.png)
-
-**Next Run**
-
-![](./readme_files/examples_report_next_run.png)
-
-### Duplicate Examples Report
-
-These reports provide duplicate tests information.
-
-![](./readme_files/duplicate_examples_report.png)
-
-### Flaky Examples Report
-
-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 Report
-
-These reports show a list of dependent files for each test.
-
-![](./readme_files/examples_dependency_report.png)
-
-### Files Dependency Report
-
-These reports provide information on the total number of tests that will run after changing this particular file.
-
-![](./readme_files/files_dependency_report.png)
-
+* [Demo](#demo)
 
 ## Getting Started
 
 1. Add this line to your `Gemfile` and `bundle install`:
     ```ruby
-    gem 'rspec-tracer', '~> 0.9', group: :test, require: false
+    gem 'rspec-tracer', '~> 1.0', group: :test, require: false
     ```
 
     And, add the followings to your `.gitignore`:
     ```
-    /rspec_tracer_cache/
-    /rspec_tracer_coverage/
-    /rspec_tracer_report/
+    rspec_tracer.lock
+    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
@@ -151,16 +100,16 @@ objectspace.enabled=true
 ### Working with Parallel Tests
 
 The Rspec tracer, by default, supports working with [parallel_tests](https://github.com/grosser/parallel_tests/)
-gem. It maintains a lock file `/tmp/parallel_tests.lock` to identify the last
+gem. It maintains a lock file `rspec_tracer.lock` to identify the last
 running process. Usually, you are not required to do anything special unless you
 interrupt the execution in between and the process did not complete correctly.
 In such a case, you must delete the lock file before the next run.
 
 ```sh
-rm -f /tmp/parallel_tests.lock && bundle exec parallel_rspec
+rm -f rspec_tracer.lock && bundle exec parallel_rspec
 ```
 
-## Configuring CI Caching
+## Configuring CI
 
 To enable RSpec Tracer to share cache between different builds on CI, update the
 Rakefile in your project to have the following:
@@ -180,52 +129,97 @@ After running tests, upload the local cache using the following rake task:
 bundle exec rake rspec_tracer:remote_cache:upload
 ```
 
-You must set the following two environment variables:
+You must set the following environment variables:
+
+- **`GIT_DEFAULT_BRANCH`** is the default branch name for the repo, e.g., `main` or `master`.
 
 - **`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.
+
+- **`TEST_SUITES`** is the total number of different test suites you are running.
   ```sh
-  export RSPEC_TRACER_S3_URI=s3://ci-artifacts-bucket/rspec-tracer-cache
+  export TEST_SUITES=8
   ```
 
-## Advanced Configuration
+- **`TEST_SUITE_ID`** is the CI build 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
+  ```
 
-Configuration settings can be applied in three formats, which are completely equivalent:
+## Advanced Configuration
 
-- 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'
-  ```
+Configuration settings must be defined in **`.rspec-tracer`** file:
+```ruby
+RSpecTracer.configure do
+  config_option 'foo'
+end
+```
 
-- 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
-  ```
+You can additionally define a global config file `~/.rspec-tracer` to share the
+common settings across projects.
 
-The available configuration options are:
+### Available Settings
 
 - **`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.
+
+- **`project_name name`** to set the project name. The default value is the last
+part of the project root directory.
+
+- **`cache_dir dir`** to set the cache directory. The default value is `./rspec_tracer_cache`.
+You can also set the **`RSPEC_TRACER_CACHE_DIR`** environment variable.
+
+- **`coverage_dir dir`** to set the coverage reports directory. The default is the
+`./rspec_tracer_coverage`. You can also set the **`RSPEC_TRACER_COVERAGE_DIR`**
+environment variable.
+
+- **`report_dir dir`** to set the HTML reports directory. The default is the
+`./rspec_tracer_report`.  You can also set the **`RSPEC_TRACER_REPORT_DIR`**
+environment variable.
+
+- **`reports_s3_path uri`** to set the AWS S3 URI for all the reports from the current
+run. You can also set the **`RSPEC_TRACER_REPORTS_S3_PATH`** environment variable.
+
+- **`use_local_aws bool_flag`** to use the `awslocal` AWS CLI with `LocalStack`. You can
+also set the **`RSPEC_TRACER_USE_LOCAL_AWS`** environment variable.
+
+- **`upload_non_ci_reports bool_flag`** to upload execution reports in a non-CI
+environment. You can also set the **`RSPEC_TRACER_UPLOAD_NON_CI_REPORTS`** environment
+variable.
+
+- **`run_all_examples bool_flag`** to always run all the examples irrespective of cache.
+You can also set the **`RSPEC_TRACER_RUN_ALL_EXAMPLES`** environment variable.
+
+- **`fail_on_duplicates bool_flag`** to fail with a non-zero exit code in case of
+duplicate examples. The default value is `true`. You can also set the **`RSPEC_TRACER_FAIL_ON_DUPLICATES`** 
+environment variable.
+
+- **`lock_file file`** to set the lock file when executing with `parallel_tests`. The default
+value is `./rspec_tracer.lock`. You can also set the **`RSPEC_TRACER_LOCK_FILE`** environment
+variable.
+
+- **`log_level level`** to set the log level. The default value is `info`. The possible
+values are `off`, `debug`, `info`, `warn`, and `error`. You can also set the
+**`RSPEC_TRACER_LOG_LEVEL`** environment variable.
+
+- **`add_filter filter`** to apply filters on the source files to exclude them
+from the dependent files list.
+
+- **`filters.clear`** to remove the configured dependent files filters so far.
+
+- **`add_coverage_filter filter`** to apply filters on the source files to exclude
+them from the coverage report.
+
+- **`coverage_filters.clear`** to remove the configured coverage files filters so far.
+
 - **`coverage_track_files glob`** to include files in the given glob pattern in
 the coverage report if these files are not already present.
 
 ```ruby
-RSpecTracer.start do
+RSpecTracer.configure do
   # Configure project root
   root '/tmp/my_project'
 
@@ -244,25 +238,6 @@ RSpecTracer.start do
 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_COVERAGE_DIR=/tmp/rspec_tracer_coverage
-  ```
-- **`RSPEC_TRACER_REPORT_DIR`** to update the default html reports directory (`rspec_tracer_report`).
-  ```sh
-  export RSPEC_TRACER_REPORT_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, RSpec Tracer ignores all the files outside of the project root directory -
@@ -270,6 +245,8 @@ otherwise you would end up with the source files in the gems you are using in th
 project. It also applies the following filters:
 ```ruby
 RSpecTracer.configure do
+  log_level 'warn'
+
   add_filter '/vendor/bundle/'
 
   add_coverage_filter %w[
@@ -292,7 +269,7 @@ a block or by passing in your own Filter class.
 in their name. For example, the following string filter will remove all files that
 have `"/helpers/"` in their name.
   ```ruby
-  RSpecTracer.start do
+  RSpecTracer.configure do
     add_filter '/helpers/'
   end
   ```
@@ -301,7 +278,7 @@ have `"/helpers/"` in their 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
+  RSpecTracer.configure do
     add_filter %r{^/helpers/}
   end
   ```
@@ -311,7 +288,7 @@ to return either **true** (if the file is to be removed from the result) or **fa
 (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
+  RSpecTracer.configure do
     add_filter do |source_file|
       source_file[:file_path].include?('/helpers/')
     end
@@ -323,50 +300,11 @@ files that match `"/helpers/"` in their path.
 
 - **Array Filter**: You can pass in an array containing any of the other filter types:
   ```ruby
-  RSpecTracer.start do
+  RSpecTracer.configure do
     add_filter ['/helpers/', %r{^/utils/}]
   end
   ```
 
-## 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_FAIL_ON_DUPLICATES (default: true)`:** By default, RSpec Tracer
-exits with one if there are [duplicate examples](#duplicate-examples).
-
-- **`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
-  ```
-
 ## Duplicate Examples
 
 To uniquely identify the examples is one of the requirements for the correctness
@@ -478,6 +416,59 @@ RSpec tracer could not uniquely identify the following 10 examples:
       * Calculator#sub performs subtraction (spec/calculator_spec.rb:24)
 ```
 
+## Demo
+
+**First Run**
+![](./readme_files/first_run.gif)
+
+**Next Run**
+![](./readme_files/next_run.gif)
+
+You get the following three reports:
+
+### All Examples Report
+
+These reports provide basic test information:
+
+**First Run**
+
+![](./readme_files/examples_report_first_run.png)
+
+**Next Run**
+
+![](./readme_files/examples_report_next_run.png)
+
+### Duplicate Examples Report
+
+These reports provide duplicate tests information.
+
+![](./readme_files/duplicate_examples_report.png)
+
+### Flaky Examples Report
+
+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 Report
+
+These reports show a list of dependent files for each test.
+
+![](./readme_files/examples_dependency_report.png)
+
+### Files Dependency Report
+
+These reports provide information on the total number of tests that will run after changing this particular file.
+
+![](./readme_files/files_dependency_report.png)
+
 ## Contributing
 
 Read the [contribution guide](https://github.com/avmnu-sng/rspec-tracer/blob/main/.github/CONTRIBUTING.md).

data/lib/rspec_tracer/cache.rb

@@ -15,8 +15,28 @@ module RSpecTracer
       @flaky_examples = Set.new
       @failed_examples = Set.new
       @pending_examples = Set.new
+      @skipped_examples = Set.new
       @all_files = {}
       @dependency = Hash.new { |hash, key| hash[key] = Set.new }
+      @examples_coverage = {}
+    end
+
+    # Public populate-from-disk surface for ReportMerger. Replaces ten
+    # separate `cache.send(:load_*_cache, ...)` pokes at the private
+    # interface with a single contract.
+    def populate_from_disk(cache_dir, discard_run_reason: true)
+      load_all_examples_cache(cache_dir, discard_run_reason: discard_run_reason)
+      load_duplicate_examples_cache(cache_dir)
+      load_interrupted_examples_cache(cache_dir)
+      load_flaky_examples_cache(cache_dir)
+      load_failed_examples_cache(cache_dir)
+      load_pending_examples_cache(cache_dir)
+      load_skipped_examples_cache(cache_dir)
+      load_all_files_cache(cache_dir)
+      load_dependency_cache(cache_dir)
+      load_examples_coverage_cache(cache_dir)
+
+      self
     end
 
     def load_cache_for_run
@@ -46,27 +66,29 @@ module RSpecTracer
 
       elapsed = RSpecTracer::TimeFormatter.format_time(ending - starting)
 
-      puts "RSpec tracer loaded cache from #{cache_dir} (took #{elapsed})"
+      RSpecTracer.logger.debug "RSpec tracer loaded cache from #{cache_dir} (took #{elapsed})"
     end
 
     def cached_examples_coverage
-      return @examples_coverage if defined?(@examples_coverage)
+      return @examples_coverage if @examples_coverage_loaded
+
+      @examples_coverage_loaded = true
 
       cache_path = RSpecTracer.cache_path
       cache_path = File.dirname(cache_path) if RSpecTracer.parallel_tests?
       run_id = last_run_id(cache_path)
 
-      return @examples_coverage = {} if run_id.nil?
+      return @examples_coverage if run_id.nil?
 
       starting = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       cache_dir = File.join(cache_path, run_id)
-      coverage = load_examples_coverage_cache(cache_dir)
+      load_examples_coverage_cache(cache_dir)
       ending = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       elapsed = RSpecTracer::TimeFormatter.format_time(ending - starting)
 
-      puts "RSpec tracer loaded cached examples coverage (took #{elapsed})" if RSpecTracer.verbose?
+      RSpecTracer.logger.debug "RSpec tracer loaded cached examples coverage (took #{elapsed})"
 
-      coverage
+      @examples_coverage
     end
 
     private