kettle-test 1.0.0

data/RUBOCOP.md

@@ -0,0 +1,71 @@
+# RuboCop Usage Guide
+
+## Overview
+
+A tale of two RuboCop plugin gems.
+
+### RuboCop Gradual
+
+This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
+
+### RuboCop LTS
+
+This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
+RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
+
+## Checking RuboCop Violations
+
+To check for RuboCop violations in this project, always use:
+
+```bash
+bundle exec rake rubocop_gradual:check
+```
+
+**Do not use** the standard RuboCop commands like:
+- `bundle exec rubocop`
+- `rubocop`
+
+## Understanding the Lock File
+
+The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
+
+1. Prevent new violations while gradually fixing existing ones
+2. Track progress on code style improvements
+3. Ensure CI builds don't fail due to pre-existing violations
+
+## Common Commands
+
+- **Check violations**
+    - `bundle exec rake rubocop_gradual`
+    - `bundle exec rake rubocop_gradual:check`
+- **(Safe) Autocorrect violations, and update lockfile if no new violations**
+  - `bundle exec rake rubocop_gradual:autocorrect`
+- **Force update the lock file (w/o autocorrect) to match violations present in code**
+  - `bundle exec rake rubocop_gradual:force_update`
+
+## Workflow
+
+1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
+   a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
+2. If there are new violations, either:
+   - Fix them in your code
+   - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
+3. Commit the updated `.rubocop_gradual.lock` file along with your changes
+
+## Never add inline RuboCop disables
+
+Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
+
+- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
+- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
+  - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
+
+In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
+
+## Benefits of rubocop_gradual
+
+- Allows incremental adoption of code style rules
+- Prevents CI failures due to pre-existing violations
+- Provides a clear record of code style debt
+- Enables focused efforts on improving code quality over time

data/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+| Version  | Supported |
+|----------|-----------|
+| 1.latest | ✅         |
+
+## Security contact information
+
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.
+
+## Additional Support
+
+If you are interested in support for versions older than the latest release,
+please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
+or find other sponsorship links in the [README].
+
+[README]: README.md

data/checksums/kettle-test-1.0.0.gem.sha256

@@ -0,0 +1 @@
+9e529e9db55bdb257b7e16929e09a2704c7453cc3ed4811ed48aa6a681b3a634

data/checksums/kettle-test-1.0.0.gem.sha512

@@ -0,0 +1 @@
+8968cc13a3547f3a36a24ff8e307a66b4bc6f6c317db9e9677f4a8f0f5f22648ae7d563f4eb5617580987f45817c2efa96e253dc55e38c1dde20a90f4377e9fc

data/lib/kettle/test/config/ext/rspec/rspec_stubbed_env.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+RSpec.configure do |config|
+  config.include_context("with stubbed env")
+end

data/lib/kettle/test/config/ext/rspec/silent_stream.rb

@@ -0,0 +1,5 @@
+require "silent_stream"
+
+RSpec.configure do |config|
+  config.include(SilentStream)
+end

data/lib/kettle/test/config/ext/timecop.rb

@@ -0,0 +1,17 @@
+require "timecop"
+
+# NOTE: Instead of using Timecop directly, prefer to use the utilities provided by Timecop::Rspec.
+#       See spec/support/config/timecop_rspec.rb
+#       We will only use Timecop directly when we need to travel inside a single example.
+#
+# Run Tests with a specific time.
+#
+# Example:
+#   back_to_the_future = Time.local(2224, 12, 12, 12, 12, 12)
+#   Timecop.freeze(back_to_the_future) do
+#     expect("something").to eq("something")
+#   end
+#
+
+# turn on safe mode
+Timecop.safe_mode = true

data/lib/kettle/test/config/int/rspec/rspec_core.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+RSpec.configure do |config|
+  # Settings that only exist in RSpec v3+ are unavailable during transpec's RSpec syntax upgrade.
+  # Other settings may be easier to upgrade to modern defaults after the uograde,
+  #   so we leave them alone during transpec.
+  # :nocov:
+  if Kettle::Test::TRANSPEC
+    config.expect_with(:rspec) do |c|
+      c.syntax = [:expect, :should]
+    end
+    config.treat_symbols_as_metadata_keys_with_true_values = true
+  else
+    config.expect_with(:rspec) do |c|
+      c.syntax = :expect
+    end
+
+    # Enable flags like --only-failures and --next-failure
+    config.example_status_persistence_file_path = ".rspec_status"
+
+    # Disable RSpec exposing methods globally on `Module` and `main`
+    config.disable_monkey_patching!
+
+    # Optionally turn on full backtrace
+    config.full_backtrace = Kettle::Test::FULL_BACKTRACE
+
+    # Profile Slowest Specs?
+    config.profile_examples = Kettle::Test::RSPEC_PROFILE_EXAMPLES_NUM if Kettle::Test::RSPEC_PROFILE_EXAMPLES
+
+    # Exclude examples/groups tagged with :skip_ci when running on CI
+    # Usage: add `:skip_ci` to any example or group you want to skip on CI
+    if Kettle::Test::IS_CI
+      config.filter_run_excluding(skip_ci: true)
+    end
+  end
+  # :nocov:
+end

data/lib/kettle/test/config/int/rspec/silent_stream.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+RSpec.configure do |config|
+  # RSpec ships with a standard solution.
+  #   See: https://www.rubydoc.info/gems/rspec-expectations/RSpec%2FMatchers:output
+  # But it has limitations, so the old non-threadsafe approach of SilentStream is still useful.
+  config.include(SilentStream)
+
+  config.around do |example|
+    # Allow tests to run normally when debugging or tagged with check_output
+    if Kettle::Test::DEBUG || example.metadata[:check_output]
+      example.run
+    # Make tests run silently, with shunted STDOUT & STDERR, if ENV var KETTLE_TEST_SILENT == "true"
+    else
+      silence_all(Kettle::Test::SILENT) do
+        example.run
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+require "timecop/rspec"
+
+# Ensure a consistent time for all tests
+#
+# Integrates timecop-rspec and provides metadata-based time travel/freeze.
+# Global baseline time derives from Kettle::Test::GLOBAL_DATE via
+# ENV["GLOBAL_TIME_TRAVEL_TIME"]. See README for sequential mode behaviors.
+#
+# Timecop.travel/freeze any RSpec (describe|context|example) with `:travel` or `:freeze` metadata.
+#
+# ```ruby
+# # Timecop.travel
+# it "some description", :travel => Time.new(2014, 11, 15) do
+#   Time.now # 2014-11-15 00:00:00
+#   sleep 6
+#   Time.now # 2014-11-15 00:00:06 (6 seconds later)
+# end
+#
+# # Timecop.freeze
+# it "some description", :freeze => Time.new(2014, 11, 15) do
+#   Time.now # 2014-11-15 00:00:00
+#   sleep 6
+#   Time.now # 2014-11-15 00:00:00 (Ruby's time hasn't advanced)
+# end
+# ```
+# If the ENV variable isn't set it will default to today
+ENV["GLOBAL_TIME_TRAVEL_TIME"] ||= Kettle::Test::GLOBAL_DATE
+
+RSpec.configure do |config|
+  config.around do |example|
+    Timecop::Rspec.time_machine(sequential: Kettle::Test::TIME_MACHINE_SEQUENTIAL).run(example)
+  end
+end

data/lib/kettle/test/config/int/rspec_block_is_expected.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Support RSpec v2 => transpec => v3 syntax
+# :nocov:
+require "rspec/block_is_expected/matchers/not" unless Kettle::Test::TRANSPEC
+# :nocov:

data/lib/kettle/test/config/version_gem.rb

@@ -0,0 +1,6 @@
+require "version_gem/rspec"
+
+# External RSpec Matchers
+require "version_gem/rspec"
+# Handy Helpers for querying the Ruby version
+require "version_gem/ruby"

data/lib/kettle/test/external.rb

@@ -0,0 +1,42 @@
+# External-no-config-needed gems
+#
+# Provides external helpers used by specs, including:
+# - rspec/stubbed_env: safe ENV stubbing
+# - rspec/block_is_expected: block expectations helper
+# - rspec_junit_formatter: JUnit XML formatter
+# - silent_stream: output silencing helpers
+#
+# Files in config/ext may not depend on this library's internals.
+# They are auto-required to wire up RSpec configuration.
+# Usage:
+# describe 'my stubbed test' do
+#   before do
+#     stub_env('FOO' => 'is bar')
+#   end
+#   it 'has a value' do
+#     expect(ENV['FOO']).to eq('is bar')
+#   end
+# end
+require "rspec/mocks"
+require "rspec/stubbed_env"
+require "rspec/block_is_expected" # Usage: see https://github.com/galtzo-floss/rspec-block_is_expected#example
+require "rspec_junit_formatter"
+require "silent_stream"
+
+# Configs of external libraries
+require_relative "config/version_gem"
+
+# Automatically load any config added to subdirectories of config/ext
+# These are **not** allowed to depend on this library's internals.
+path = File.expand_path(__dir__)
+
+# NOTE: Remove #sort when dropping Ruby v2 support; Ruby v3 Dir.globs are pre-sorted
+# Load non-rspec library configs
+Dir.glob("#{path}/config/ext/*.rb")
+  .sort
+  .each { |f| require f }
+
+# NOTE: Remove #sort when dropping Ruby v2 support; Ruby v3 Dir.globs are pre-sorted
+Dir.glob("#{path}/config/ext/{rspec,filters,helpers,matchers}/**/*.rb")
+  .sort
+  .each { |f| require f }

data/lib/kettle/test/internal.rb

@@ -0,0 +1,23 @@
+# Configs of external libraries that depend on this library's internals
+#
+# Auto-loads internal RSpec configuration and any additional integrations under
+# config/int and its subfolders.
+# Files in config/ext may depend on this library's internals.
+require_relative "config/int/rspec_block_is_expected"
+require_relative "config/int/rspec/rspec_core"
+require_relative "config/int/rspec/silent_stream"
+
+# Automatically load any config added to subdirectories of config/int
+# These are allowed to depend on this library's internals.
+path = File.expand_path(__dir__)
+
+# NOTE: Remove #sort when dropping Ruby v2 support; Ruby v3 Dir.globs are pre-sorted
+# Load non-rspec library configs
+Dir.glob("#{path}/config/int/*.rb")
+  .sort
+  .each { |f| require f }
+
+# NOTE: Remove #sort when dropping Ruby v2 support; Ruby v3 Dir.globs are pre-sorted
+Dir.glob("#{path}/config/int/{rspec,filters,helpers,matchers}/**/*.rb")
+  .sort
+  .each { |f| require f }

data/lib/kettle/test/rspec.rb

@@ -0,0 +1,7 @@
+require_relative "external"
+
+# Entry point for RSpec integrations provided by kettle-test.
+# Requires external helpers, this library, then wires internal configuration.
+require "kettle/test"
+
+require_relative "internal"

data/lib/kettle/test/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Kettle
+  module Test
+    # Version namespace
+    module Version
+      # The current version of kettle-test.
+      # @return [String]
+      VERSION = "1.0.0"
+    end
+  end
+end

data/lib/kettle/test.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "test/version"
+
+module Kettle
+  # Test support and RSpec integration for kettle-rb ecosystem.
+  #
+  # Exposes environment-controlled constants and helpers that tune RSpec behavior
+  # (profiling, backtraces, output silencing, CI filters) and provides a minimal
+  # API for detecting parallel test execution.
+  #
+  # See README for configuration and usage examples.
+  module Test
+    # Base error class for kettle-test specific failures.
+    class Error < StandardError; end
+
+    # String#casecmp? was added in Ruby 2.4, so fallback to String#casecmp
+    # @return [Boolean] whether debug mode is enabled (disables silencing)
+    DEBUG = ENV.fetch("KETTLE_TEST_DEBUG", ENV.fetch("DEBUG", "false")).casecmp("true").zero?
+    # @return [Boolean] whether running in a CI environment (CI=true)
+    IS_CI = ENV.fetch("CI", "").casecmp("true").zero?
+    # @return [Boolean] when true, enables full backtraces in RSpec
+    FULL_BACKTRACE = ENV.fetch("KETTLE_TEST_FULL_BACKTRACE", "false").casecmp("true").zero?
+    # @return [Integer] number of examples to profile (0 disables profiling)
+    RSPEC_PROFILE_EXAMPLES_NUM = ENV.fetch("KETTLE_TEST_RSPEC_PROFILE_EXAMPLES", "0").to_i
+    # @return [Boolean] whether profiling is enabled
+    RSPEC_PROFILE_EXAMPLES = RSPEC_PROFILE_EXAMPLES_NUM > 0
+    # If RSpec's version is < 3, enable `transpec` to facilitate the upgrade.
+    # @return [Gem::Version] active RSpec version
+    RSPEC_VERSION = ::Gem::Version.new(RSpec::Core::Version::STRING)
+    # @return [Boolean] when true, STDOUT/STDERR are silenced during specs (unless :check_output or DEBUG)
+    SILENT = ENV.fetch("KETTLE_TEST_SILENT", IS_CI.to_s).casecmp("true").zero?
+    # @return [Boolean] whether transpec compatibility mode should be enabled
+    TRANSPEC = ::Gem::Version.new("3.0") > RSPEC_VERSION
+    # @return [Boolean] whether the environment signals a parallel test run
+    TREAT_AS_PARALLEL = ENV.fetch("PARALLEL_TEST_FIRST_IS_1", "").casecmp("true").zero?
+    # @return [Boolean] reserved for verbose logging toggles
+    VERBOSE = ENV.fetch("KETTLE_TEST_VERBOSE", "false").casecmp("true").zero?
+    # time starts at midnight on GLOBAL_DATE
+    # @return [String] global travel time or date used as a baseline for timecop
+    GLOBAL_DATE = ENV.fetch("GLOBAL_TIME_TRAVEL_TIME", ENV.fetch("GLOBAL_TIME_TRAVEL_DATE", Date.today.to_s))
+    # @return [Boolean] when true, use sequential time machine mode for timecop-rspec
+    TIME_MACHINE_SEQUENTIAL = ENV.fetch("KETTLE_TEST_TM_SEQUENTIAL", "true").casecmp("true").zero?
+
+    class << self
+      # Detects whether tests are running in parallel.
+      #
+      # Many parallel test runners set PARALLEL_TEST_FIRST_IS_1=true and provide
+      # TEST_ENV_NUMBER for each worker. This helper checks those signals.
+      # @return [Boolean]
+      def is_parallel_test?
+        TREAT_AS_PARALLEL && !ENV.fetch("TEST_ENV_NUMBER", "").empty?
+      end
+    end
+  end
+end
+
+Kettle::Test::Version.class_eval do
+  extend VersionGem::Basic
+end

data/sig/kettle/test.rbs

@@ -0,0 +1,27 @@
+module Kettle
+  module Test
+    class Error < StandardError
+    end
+
+    # Environment-driven constants
+    DEBUG: bool
+    IS_CI: bool
+    FULL_BACKTRACE: bool
+    RSPEC_PROFILE_EXAMPLES_NUM: untyped
+    RSPEC_PROFILE_EXAMPLES: bool
+    RSPEC_VERSION: untyped
+    SILENT: bool
+    TRANSPEC: bool
+    TREAT_AS_PARALLEL: bool
+    VERBOSE: bool
+    GLOBAL_DATE: untyped
+    TIME_MACHINE_SEQUENTIAL: bool
+
+    # Class methods
+    def self.is_parallel_test?: () -> bool
+
+    module Version
+      VERSION: untyped
+    end
+  end
+end