✨ RSpec shared context: "with rake"

Author: pboling

CHANGELOG.md

@@ -18,6 +18,7 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ## [Unreleased]
 ### Added
+- RSpec shared context: "with rake"
 ### Changed
 ### Deprecated
 ### Removed

README.md

@@ -38,19 +38,19 @@ and concordant releases of JRuby, and TruffleRuby.
 
 ## 💡 Info you can shake a stick at
 
-| Tokens to Remember      | [![Gem name][⛳️name-img]][⛳️gem-name] [![Gem namespace][⛳️namespace-img]][⛳️gem-namespace]                                                                                                                                                                                                                                             |
-|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Works with JRuby        | ![JRuby 9.1 Compat][💎jruby-9.1i] ![JRuby 9.2 Compat][💎jruby-9.2i] ![JRuby 9.3 Compat][💎jruby-9.3i] <br/> [![JRuby 9.4 Compat][💎jruby-9.4i]][🚎10-j-wf] [![JRuby 10.0 Compat][💎jruby-c-i]][🚎11-c-wf] [![JRuby HEAD Compat][💎jruby-headi]][🚎3-hd-wf]                                                                             |
-| Works with Truffle Ruby | ![Truffle Ruby 22.3 Compat][💎truby-22.3i] ![Truffle Ruby 23.0 Compat][💎truby-23.0i] <br/> [![Truffle Ruby 23.1 Compat][💎truby-23.1i]][🚎9-t-wf] [![Truffle Ruby 24.1 Compat][💎truby-c-i]][🚎11-c-wf]                                                                                                                               |
-| Works with MRI Ruby 3   | [![Ruby 3.0 Compat][💎ruby-3.0i]][🚎4-lg-wf] [![Ruby 3.1 Compat][💎ruby-3.1i]][🚎6-s-wf] [![Ruby 3.2 Compat][💎ruby-3.2i]][🚎6-s-wf] [![Ruby 3.3 Compat][💎ruby-3.3i]][🚎6-s-wf] [![Ruby 3.4 Compat][💎ruby-c-i]][🚎11-c-wf] [![Ruby HEAD Compat][💎ruby-headi]][🚎3-hd-wf]                                                            |
-| Works with MRI Ruby 2   |    <br/> [![Ruby 2.3 Compat][💎ruby-2.3i]][🚎1-an-wf] [![Ruby 2.4 Compat][💎ruby-2.4i]][🚎1-an-wf] [![Ruby 2.5 Compat][💎ruby-2.5i]][🚎1-an-wf] [![Ruby 2.6 Compat][💎ruby-2.6i]][🚎7-us-wf] [![Ruby 2.7 Compat][💎ruby-2.7i]][🚎7-us-wf] |
-| Source                  | [![Source on GitLab.com][📜src-gl-img]][📜src-gl] [![Source on CodeBerg.org][📜src-cb-img]][📜src-cb] [![Source on Github.com][📜src-gh-img]][📜src-gh] [![The best SHA: dQw4w9WgXcQ!][🧮kloc-img]][🧮kloc]                                                                                                                            |
-| Documentation           | [![Current release on RubyDoc.info][📜docs-cr-rd-img]][🚎yard-current] [![YARD on Galtzo.com][📜docs-head-rd-img]][🚎yard-head] [![Maintainer Blog][🚂maint-blog-img]][🚂maint-blog] [![Wiki][📜wiki-img]][📜wiki]                                                                                                                     |
-| Compliance              | [![License: MIT][📄license-img]][📄license-ref] [![📄ilo-declaration-img]][📄ilo-declaration] [![Security Policy][🔐security-img]][🔐security] [![Contributor Covenant 2.1][🪇conduct-img]][🪇conduct] [![SemVer 2.0.0][📌semver-img]][📌semver]                                                                                       |
-| Style                   | [![Enforced Code Style Linter][💎rlts-img]][💎rlts] [![Keep-A-Changelog 1.0.0][📗keep-changelog-img]][📗keep-changelog] [![Gitmoji Commits][📌gitmoji-img]][📌gitmoji] [![Compatibility appraised by: appraisal2][💎appraisal2-img]][💎appraisal2]                                                                                     |
-| Support                 | [![Live Chat on Discord][✉️discord-invite-img]][✉️discord-invite] [![Get help from me on Upwork][👨🏼‍🏫expsup-upwork-img]][👨🏼‍🏫expsup-upwork] [![Get help from me on Codementor][👨🏼‍🏫expsup-codementor-img]][👨🏼‍🏫expsup-codementor]                                                                                          |
-| Maintainer 🎖️          | [![Follow Me on LinkedIn][💖🖇linkedin-img]][💖🖇linkedin] [![Follow Me on Ruby.Social][💖🐘ruby-mast-img]][💖🐘ruby-mast] [![Follow Me on Bluesky][💖🦋bluesky-img]][💖🦋bluesky] [![Contact Maintainer][🚂maint-contact-img]][🚂maint-contact] [![My technical writing][💖💁🏼‍♂️devto-img]][💖💁🏼‍♂️devto]                         |
-| `...` 💖                | [![Find Me on WellFound:][💖✌️wellfound-img]][💖✌️wellfound] [![Find Me on CrunchBase][💖💲crunchbase-img]][💖💲crunchbase] [![My LinkTree][💖🌳linktree-img]][💖🌳linktree] [![More About Me][💖💁🏼‍♂️aboutme-img]][💖💁🏼‍♂️aboutme] [🧊][💖🧊berg] [🐙][💖🐙hub]  [🛖][💖🛖hut] [🧪][💖🧪lab]                                      |
+| Tokens to Remember      | [![Gem name][⛳️name-img]][⛳️gem-name] [![Gem namespace][⛳️namespace-img]][⛳️gem-namespace]                                                                                                                                                                                                                                           |
+|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Works with JRuby        | ![JRuby 9.1 Compat][💎jruby-9.1i] ![JRuby 9.2 Compat][💎jruby-9.2i] ![JRuby 9.3 Compat][💎jruby-9.3i] <br/> [![JRuby 9.4 Compat][💎jruby-9.4i]][🚎10-j-wf] [![JRuby 10.0 Compat][💎jruby-c-i]][🚎11-c-wf] [![JRuby HEAD Compat][💎jruby-headi]][🚎3-hd-wf]                                                                           |
+| Works with Truffle Ruby | ![Truffle Ruby 22.3 Compat][💎truby-22.3i] ![Truffle Ruby 23.0 Compat][💎truby-23.0i] <br/> [![Truffle Ruby 23.1 Compat][💎truby-23.1i]][🚎9-t-wf] [![Truffle Ruby 24.1 Compat][💎truby-c-i]][🚎11-c-wf]                                                                                                                             |
+| Works with MRI Ruby 3   | [![Ruby 3.0 Compat][💎ruby-3.0i]][🚎4-lg-wf] [![Ruby 3.1 Compat][💎ruby-3.1i]][🚎6-s-wf] [![Ruby 3.2 Compat][💎ruby-3.2i]][🚎6-s-wf] [![Ruby 3.3 Compat][💎ruby-3.3i]][🚎6-s-wf] [![Ruby 3.4 Compat][💎ruby-c-i]][🚎11-c-wf] [![Ruby HEAD Compat][💎ruby-headi]][🚎3-hd-wf]                                                          |
+| Works with MRI Ruby 2   | [![Ruby 2.3 Compat][💎ruby-2.3i]][🚎1-an-wf] [![Ruby 2.4 Compat][💎ruby-2.4i]][🚎1-an-wf] [![Ruby 2.5 Compat][💎ruby-2.5i]][🚎1-an-wf] [![Ruby 2.6 Compat][💎ruby-2.6i]][🚎7-us-wf] [![Ruby 2.7 Compat][💎ruby-2.7i]][🚎7-us-wf] |
+| Source                  | [![Source on GitLab.com][📜src-gl-img]][📜src-gl] [![Source on CodeBerg.org][📜src-cb-img]][📜src-cb] [![Source on Github.com][📜src-gh-img]][📜src-gh] [![The best SHA: dQw4w9WgXcQ!][🧮kloc-img]][🧮kloc]                                                                                                                          |
+| Documentation           | [![Current release on RubyDoc.info][📜docs-cr-rd-img]][🚎yard-current] [![YARD on Galtzo.com][📜docs-head-rd-img]][🚎yard-head] [![Maintainer Blog][🚂maint-blog-img]][🚂maint-blog] [![Wiki][📜wiki-img]][📜wiki]                                                                                                                   |
+| Compliance              | [![License: MIT][📄license-img]][📄license-ref] [![📄ilo-declaration-img]][📄ilo-declaration] [![Security Policy][🔐security-img]][🔐security] [![Contributor Covenant 2.1][🪇conduct-img]][🪇conduct] [![SemVer 2.0.0][📌semver-img]][📌semver]                                                                                     |
+| Style                   | [![Enforced Code Style Linter][💎rlts-img]][💎rlts] [![Keep-A-Changelog 1.0.0][📗keep-changelog-img]][📗keep-changelog] [![Gitmoji Commits][📌gitmoji-img]][📌gitmoji] [![Compatibility appraised by: appraisal2][💎appraisal2-img]][💎appraisal2]                                                                                   |
+| Support                 | [![Live Chat on Discord][✉️discord-invite-img]][✉️discord-invite] [![Get help from me on Upwork][👨🏼‍🏫expsup-upwork-img]][👨🏼‍🏫expsup-upwork] [![Get help from me on Codementor][👨🏼‍🏫expsup-codementor-img]][👨🏼‍🏫expsup-codementor]                                                                                        |
+| Maintainer 🎖️          | [![Follow Me on LinkedIn][💖🖇linkedin-img]][💖🖇linkedin] [![Follow Me on Ruby.Social][💖🐘ruby-mast-img]][💖🐘ruby-mast] [![Follow Me on Bluesky][💖🦋bluesky-img]][💖🦋bluesky] [![Contact Maintainer][🚂maint-contact-img]][🚂maint-contact] [![My technical writing][💖💁🏼‍♂️devto-img]][💖💁🏼‍♂️devto]                       |
+| `...` 💖                | [![Find Me on WellFound:][💖✌️wellfound-img]][💖✌️wellfound] [![Find Me on CrunchBase][💖💲crunchbase-img]][💖💲crunchbase] [![My LinkTree][💖🌳linktree-img]][💖🌳linktree] [![More About Me][💖💁🏼‍♂️aboutme-img]][💖💁🏼‍♂️aboutme] [🧊][💖🧊berg] [🐙][💖🐙hub]  [🛖][💖🛖hut] [🧪][💖🧪lab]                                    |
 
 ### Compatibility
 
@@ -251,6 +251,26 @@ end
 
 ## 🔧 Basic Usage
 
+### Shared Context "with rake"
+
+Make sure to require "rake" before you require "kettle/test" (or "kettle/dev" since it will require this library).
+
+If you do the shared context will be available to use in your specs automatically.
+
+```ruby
+include_context "with rake", "demo" do
+  let(:tmp_rakelib) do
+    Dir.mktmpdir("with_rake_spec_")
+  end
+  let(:task_dir) { tmp_rakelib }
+  let(:rakelib) { tmp_rakelib }
+  # Provide args for the rake task invocation
+  let(:task_args) { ["Bob"] }
+end
+```
+
+See the spec for a more complete example: See for more details: [with_rake_spec.rb](spec/kettle/text/support/shared_contexts/with_rake_spec.rb)
+
 ### RSpec Time Machine Tags :freeze and :travel
 
 Timecop.travel/freeze any RSpec (describe|context|example) with

lib/kettle/test/config/int/rspec/timecop_rspec.rb

@@ -1,5 +1,3 @@
-require "timecop/rspec"
-
 # Ensure a consistent time for all tests
 #
 # Integrates timecop-rspec and provides metadata-based time travel/freeze.

lib/kettle/test/external.rb

@@ -22,6 +22,7 @@
 require "rspec/block_is_expected" # Usage: see https://github.com/galtzo-floss/rspec-block_is_expected#example
 require "rspec_junit_formatter"
 require "silent_stream"
+require "timecop/rspec"
 
 # Configs of external libraries
 require_relative "config/version_gem"

lib/kettle/test/rspec.rb

@@ -5,3 +5,7 @@
 require "kettle/test"
 
 require_relative "internal"
+
+# A gem's test harness should do require "rake" if it is their dependency,
+#   and they define a rake task they want to test.
+require_relative "support/shared_contexts/with_rake" if defined?(Rake)

lib/kettle/test/support/shared_contexts/with_rake.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# rubocop:disable RSpec/MultipleMemoizedHelpers
+
+# Inspired by: https://thoughtbot.com/blog/test-rake-tasks-like-a-boss
+# This version doesn't require a Rails app!
+# This file will only be required if Rake is defined
+# require "rake"
+
+# Usage:
+#     include_context "with rake", "demo" do
+#       let(:tmp_rakelib) do
+#         Dir.mktmpdir("with_rake_spec_")
+#       end
+#       # Required by the shared context (override the raising defaults)
+#       let(:task_dir) { tmp_rakelib }
+#       let(:rakelib) { tmp_rakelib }
+#       # Provide args for the rake task invocation
+#       let(:task_args) { ["Bob"] }
+#     end
+#
+# See for more details: spec/kettle/text/support/shared_contexts/with_rake_spec.rb
+#
+RSpec.shared_context("with rake") do |task_base_name|
+  let(:rake_app) { Rake::Application.new }
+  let(:task_name) { self.class.top_level_description.sub(/\Arake /, "") }
+  # A gem depending on this gem, and using this shared context must define task_dir
+  # let(:task_dir) { "lib/gem_checksums/rakelib" }
+  let(:task_dir) { raise ArgumentError, "define task_dir in the block of `include_context 'with rake', basename do ... end`" }
+  let(:task_args) { [] }
+  let(:invoke) { rake_task.invoke(*task_args) }
+  # A gem depending on this gem, and using this shared context must define rakelib
+  # let(:rakelib) { File.join(__dir__, "..", "..", "..", task_dir) }
+  let(:rakelib) { raise ArgumentError, "define rakelib in the block of `include_context 'with rake', basename do ... end`" }
+  let(:rake_task) { Rake::Task[task_name] }
+
+  include_context "with stubbed env"
+
+  def loaded_files_excluding_current_rake_file(task_base_name)
+    $".reject { |file| file == File.join(rakelib, "#{task_base_name}.rake").to_s }
+  end
+
+  before do
+    Rake.application = rake_app
+    Rake.application.rake_require(task_base_name, [rakelib], loaded_files_excluding_current_rake_file(task_base_name))
+  end
+end
+# rubocop:enable RSpec/MultipleMemoizedHelpers

spec/kettle/test/support/shared_contexts/with_rake_spec.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# We need Rake loaded so that kettle/test/rspec (and thus the shared context) can be required.
+require "rake"
+# In case spec_helper loaded kettle/test/rspec before Rake was defined, load the context directly here.
+require "kettle/test/support/shared_contexts/with_rake"
+
+RSpec.describe "rake demo:print" do # rubocop:disable RSpec/DescribeClass
+  context "with a temporary rakelib and a demo task", :check_output do
+    require "tmpdir"
+
+    # Include the shared context first so that our overriding lets below take precedence.
+    include_context "with rake", "demo" do
+      let(:tmp_rakelib) do
+        Dir.mktmpdir("with_rake_spec_")
+      end
+      # Required by the shared context (override the raising defaults)
+      let(:task_dir) { tmp_rakelib }
+      let(:rakelib) { tmp_rakelib }
+      # Provide args for the rake task invocation
+      let(:task_args) { ["Bob"] }
+    end
+
+    around do |example|
+      require "fileutils"
+      # Create a rake file BEFORE the shared context's before(:each) runs
+      File.open(File.join(tmp_rakelib, "demo.rake"), "w") do |f|
+        f.write(<<~'RAKE')
+          namespace :demo do
+            desc "Print a greeting"
+            task :print, [:name] do |_t, args|
+              puts "Hello #{args[:name] || 'world'}"
+            end
+          end
+        RAKE
+      end
+
+      begin
+        example.run
+      ensure
+        # Cleanup tasks loaded into the Rake application for isolation
+        Rake::Task.tasks.each { |t| t.clear }
+        # Remove the temp directory and its contents
+        FileUtils.rm_rf(tmp_rakelib) if File.directory?(tmp_rakelib)
+      end
+    end
+
+    it "derives task_name from the top-level description by stripping the 'rake ' prefix" do
+      expect(task_name).to eq("demo:print")
+    end
+
+    it "sets Rake.application to the isolated rake_app instance" do
+      expect(Rake.application).to be(rake_app)
+    end
+
+    it "loads the rake file and defines the target task" do
+      expect(rake_task).to be_a(Rake::Task)
+      expect(rake_task.name).to eq("demo:print")
+    end
+
+    it "invokes the task with provided arguments and prints expected output" do
+      expect { invoke }.to output(/Hello Bob/).to_stdout
+    end
+
+    it "excludes the current rake file from the loaded files list via helper" do
+      required_path = File.join(rakelib, "demo.rake").to_s
+
+      # Simulate the scenario where the rake file is already in $LOADED_FEATURES
+      added = false
+      unless $LOADED_FEATURES.include?(required_path)
+        $LOADED_FEATURES << required_path
+        added = true
+      end
+
+      begin
+        excluded = loaded_files_excluding_current_rake_file("demo")
+        # The helper should exclude exactly this file path
+        expect(excluded).not_to include(required_path)
+      ensure
+        # Clean up our simulation
+        $LOADED_FEATURES.delete(required_path) if added
+      end
+    end
+  end
+end