Shopify Deprecation Toolkit

Deprecation Toolkit uses a "shitlist approach" to manage code deprecations. It works in two phases:

1. Recording: The gem records all existing deprecations into .yml files.
2. Enforcement: When running tests, if a deprecation is encountered that was not in the recorded files, the gem triggers a configured behavior (by default, it raises an error).

This allows teams to progressively resolve existing deprecations while ensuring no new ones are introduced to the codebase.

To use the toolkit with RSpec instead of the default Minitest, follow these steps:

1. Set the test runner in your configuration:

   DeprecationToolkit::Configuration.test_runner = :rspec

2. Require the RSpec hooks in your spec_helper.rb or rails_helper.rb:

   require "deprecation_toolkit/rspec"

3. To record deprecations during an RSpec run, set the DEPRECATION_BEHAVIOR environment variable to record, r, or record-deprecations.

DEPRECATION_BEHAVIOR="record" bundle exec rspec path/to/file_spec.rb

# In your configuration
DeprecationToolkit::Configuration.test_runner = :rspec

# In spec_helper.rb or rails_helper.rb
require "deprecation_toolkit/rspec"

To record existing deprecations into .yml files, you can use either the CLI flag during test execution or set the behavior in your configuration.

Using the CLI flag: Run your tests with the --record-deprecations flag or the -r shortcut.

rails test <path_to_my_test.rb> -r

Using Configuration: Set the DeprecationToolkit::Configuration.behavior to DeprecationToolkit::Behaviors::Record.

The deprecation_toolkit provides a Minitest plugin that allows you to record deprecations during your test suite execution using a command-line flag. When the flag is present, the toolkit sets the global behavior to DeprecationToolkit::Behaviors::Record and initializes notification and subscription mechanisms.

minitest --record-deprecations

To use the Deprecation Toolkit within an RSpec test suite, include the DeprecationToolkit::RSpecPlugin module. The plugin automatically configures an RSpec before(:suite) hook to initialize the toolkit's behaviors, attach subscribers, and set up notification behaviors.

If you want the toolkit to record deprecations during your test run, set the DEPRECATION_BEHAVIOR environment variable to r, record, or record-deprecations.

# Ensure the plugin is loaded in your spec_helper.rb or rails_helper.rb
require 'deprecation_toolkit/rspec_plugin'

# To enable recording mode via the environment:
# DEPRECATION_BEHAVIOR=record bundle exec rspec

You can control where recorded deprecations are saved and read from using deprecation_path. By default, they are stored in test/deprecations.

deprecation_path accepts:

• A String: A static path.
• A Proc: A proc that receives the path of the running test file as an argument, allowing for dynamic pathing (e.g., separating admin and storefront deprecations).

DeprecationToolkit::Configuration.deprecation_path = 'test/deprecations'

DeprecationToolkit::Configuration.deprecation_path = -> (test_location) do
  if test_location == 'admin_test.rb'
    'test/deprecations/admin'
  else
    'test/deprecations/storefront'
  end
end

If your dependencies use Kernel#warn instead of ActiveSupport::Deprecation, you can treat those warnings as deprecations using warnings_treated_as_deprecation. This setting accepts an array of matchers (Regexps or objects responding to ===, such as Procs).

To match all warnings, use an empty regex //.

# Match all warnings
DeprecationToolkit::Configuration.warnings_treated_as_deprecation = [//]

# Match using a Proc
DeprecationToolkit::Configuration.warnings_treated_as_deprecation = [
  ->(warning) { !warning.match?(/not a deprecation/) }
]

Use allowed_deprecations to whitelist specific deprecations so they are ignored by the toolkit. This setting accepts an array of Regexp or Procs.

• Regexp: Matches against the deprecation message.
• Proc: Receives the message and the stack (callstack). This is useful for whitelisting based on the specific method triggering the deprecation.

# Ignore by message pattern
DeprecationToolkit::Configuration.allowed_deprecations = [/Hello World/]

# Ignore by message and callstack
DeprecationToolkit::Configuration.allowed_deprecations = [
  ->(message, stack) { message =~ 'Foo' && stack.first.label == 'method_triggering_deprecation' }
]

You can customize how the .yml files are named and located using deprecation_file_path_format. This setting accepts a Proc that is called with the instance of the test.

Default Formats:

• Minitest: Uses the class name (e.g., test/deprecations/deprecation_toolkit/behaviors/raise_test.yml).
• RSpec: Uses the file location with the spec prefix removed (e.g., /models/user.yml).

# Custom format using a proc
Configuration.deprecation_file_path_format = -> (test) do
  Kernel.const_source_location(test.class.name)[0].sub(%r{^./test/}, "").sub(/_test.rb$/, "")
end