Merge branch 'main' into dependabot/bundler/yard-0.9.37

Author: stefannibrasil

Gemfile

@@ -6,11 +6,11 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'benchmark'
-gem 'minitest', '5.25.0'
+gem 'minitest', '5.25.1'
 gem 'pry', '0.14.2'
 gem 'rake', '13.2.1'
 gem 'rubocop', '1.65.1'
-gem 'rubocop-minitest', '0.35.1'
+gem 'rubocop-minitest', '0.36.0'
 gem 'rubocop-rake', '0.6.0'
 gem 'simplecov', '0.22.0'
 gem 'test-unit', '3.6.2'

Gemfile.lock

@@ -17,9 +17,9 @@ GEM
     json (2.7.2)
     language_server-protocol (3.17.0.3)
     method_source (1.0.0)
-    minitest (5.25.0)
-    parallel (1.25.1)
-    parser (3.3.4.0)
+    minitest (5.25.1)
+    parallel (1.26.3)
+    parser (3.3.5.0)
       ast (~> 2.4.1)
       racc
     power_assert (2.0.3)
@@ -30,8 +30,7 @@ GEM
     rainbow (3.1.1)
     rake (13.2.1)
     regexp_parser (2.9.2)
-    rexml (3.3.4)
-      strscan
+    rexml (3.3.7)
     rubocop (1.65.1)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
@@ -43,9 +42,9 @@ GEM
       rubocop-ast (>= 1.31.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.31.3)
+    rubocop-ast (1.32.3)
       parser (>= 3.3.1.0)
-    rubocop-minitest (0.35.1)
+    rubocop-minitest (0.36.0)
       rubocop (>= 1.61, < 2.0)
       rubocop-ast (>= 1.31.1, < 2.0)
     rubocop-rake (0.6.0)
@@ -57,7 +56,6 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
-    strscan (3.1.0)
     test-unit (3.6.2)
       power_assert
     timecop (0.9.10)
@@ -71,11 +69,11 @@ PLATFORMS
 DEPENDENCIES
   benchmark
   faker!
-  minitest (= 5.25.0)
+  minitest (= 5.25.1)
   pry (= 0.14.2)
   rake (= 13.2.1)
   rubocop (= 1.65.1)
-  rubocop-minitest (= 0.35.1)
+  rubocop-minitest (= 0.36.0)
   rubocop-rake (= 0.6.0)
   simplecov (= 0.22.0)
   test-unit (= 3.6.2)

lib/faker.rb

@@ -249,6 +249,10 @@ def shuffle(list)
         list.shuffle(random: Faker::Config.random)
       end
 
+      def shuffle!(list)
+        list.shuffle!(random: Faker::Config.random)
+      end
+
       def rand(max = nil)
         if max.nil?
           Faker::Config.random.rand

lib/faker/default/alphanumeric.rb

@@ -60,7 +60,7 @@ def alphanumeric(number: 32, min_alpha: 0, min_numeric: 0)
         randoms = Array.new(random_count) { sample(ALPHANUMS) }
 
         combined = alphas + numbers + randoms
-        combined.shuffle.join
+        shuffle!(combined).join
       end
     end
   end

lib/helpers/deprecator.rb

@@ -1,17 +1,70 @@
 # frozen_string_literal: true
 
 # Based on Rails ActiveSupport Deprecator
-# https://github.com/rails/rails/blob/6f0d1ad14b92b9f5906e44740fce8b4f1c7075dc/activesupport/lib/active_support/deprecation/constant_accessor.rb
+# https://github.com/rails/rails/blob/main/activesupport/lib/active_support/deprecation/constant_accessor.rb
 
 # rubocop:disable Style/ClassVars
 module Faker
+  # Provides a way to rename generators, including their namespaces, with a deprecation cycle in which
+  # both the old and new names work, but using the old one prints a deprecation message.
+  #
+  # Deprecator provides a deprecate_generator method to be used when
+  # renaming a generator. For example, let's say we want to change the following Generator's
+  # name to <tt>Faker::NewGenerator</tt>:
+  #
+  #   module Faker
+  #     class Generator
+  #       def self.generate
+  #         "be kind"
+  #       end
+  #     end
+  #   end
+  #
+  # To rename it, you need to do the update the name and declare the deprecation by
+  # including the <tt>Deprecator</tt> module and using the deprecate_generator method:
+  #
+  #   module Faker
+  #     class NewGenerator
+  #       def self.generate
+  #         "be kind"
+  #       end
+  #     end
+  #
+  #     include Deprecator
+  #     deprecate_generator('DeprecatedGenerator', NewGenerator)
+  #   end
+  #
+  # The first argument is a constant name (no colons) as a string. It is the name of
+  # the constant you want to deprecate.
+  #
+  # The second argument is the constant path of the replacement (no colons) as a constant.
+  #
+  # For this to work, a +const_missing+ hook is installed. When users
+  # reference the deprecated constant, the callback prints the
+  # message and constantizes the replacement.
+  #
+  # With that in place, references to <tt>Faker::Deprecator</tt> still work, they
+  # evaluate to <tt>Faker::NewGenerator</tt> now, and trigger a deprecation warning:
+  #
+  #   Faker::Generator.generate
+  #   # DEPRECATION WARNING: Faker::Generator is deprecated. Use Faker::NewGenerator instead
+  #   # "be kind"
+  #
+  # For testing the deprecations, we provide <tt>assert_deprecated</tt>
+  # and <tt>assert_not_deprecated</tt> matchers.
+  #
+  # There's also a <tt>Faker::Deprecator.skip_warning</tt> helper to silence
+  # the deprecation messages in the *test* output. Use it for generators that have lots of tests
+  # to avoid too many noise when running the tests.
   module Deprecator
     def self.included(base)
       extension = Module.new do
         def const_missing(missing_const_name)
           if class_variable_defined?(:@@_deprecated_constants) && (replacement = class_variable_get(:@@_deprecated_constants)[missing_const_name.to_s])
             unless Faker::Deprecator.skip_warning?
-              $stdout.puts("DEPRECATION WARNING: #{name}::#{replacement[:old_generator]} is deprecated. Use #{replacement[:new_constant]} instead.")
+              deprecated_message = "#{name}::#{replacement[:old_generator]} is deprecated."
+              replacement_message = "Use #{replacement[:new_constant]} instead."
+              $stdout.puts("DEPRECATION WARNING: #{deprecated_message} #{replacement_message}")
             end
 
             return replacement[:new_constant]
@@ -22,13 +75,25 @@ def const_missing(missing_const_name)
 
         def deprecate_generator(old_generator_name, new_generator_constant)
           class_variable_set(:@@_deprecated_constants, {}) unless class_variable_defined?(:@@_deprecated_constants)
-          class_variable_get(:@@_deprecated_constants)[old_generator_name] = { new_constant: new_generator_constant, old_generator: old_generator_name }
+          class_variable_get(:@@_deprecated_constants)[old_generator_name] = {
+            new_constant: new_generator_constant,
+            old_generator: old_generator_name
+          }
         end
       end
 
       base.singleton_class.prepend extension
     end
 
+    # Silence deprecation warnings within the block.
+    #
+    #   Faker::Generator.generate
+    #   # => DEPRECATION WARNING: Faker::Generator is deprecated. Use Faker::NewGenerator instead.
+    #
+    #   Faker::Deprecator.skip_warning do
+    #     Faker::Generator.generate
+    #   end
+    #   # => nil
     def self.skip_warning
       original = Faker::Deprecator.skip
       Faker::Deprecator.skip = true

test/faker/default/test_alphanum.rb

@@ -48,4 +48,12 @@ def test_alphanumeric_with_min_numeric
 
     assert_operator numbers.compact.size, :>=, 4
   end
+
+  def test_alphanumeric_with_min_alpha_and_min_numeric
+    deterministically_verify -> { @tester.alphanumeric(number: 10, min_alpha: 5, min_numeric: 5) } do |alphanum|
+      assert_equal 10, alphanum.size
+      assert_equal 5, alphanum.scan(/[[:alpha:]]/).size
+      assert_equal 5, alphanum.scan(/[[:digit:]]/).size
+    end
+  end
 end

test/helpers/test_faker_deprecator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative '../test_helper'
+
+class TestFakerDeprecation < Test::Unit::TestCase
+  def test_using_a_deprecated_generator_returns_a_warning_message
+    assert_deprecated do
+      Faker::Dogs.say
+    end
+
+    assert_equal 'meow', Faker::Dogs.say
+  end
+
+  def test_using_a_non_deprecated_generator_does_not_return_a_warning_message
+    assert_not_deprecated do
+      Faker::Cats.say
+    end
+    assert_equal 'meow', Faker::Cats.say
+  end
+
+  def test_testing_a_deprecated_generator_with_skip_warning_does_not_return_a_warning_message
+    actual_stdout, actual_stderr = capture_output do
+      Faker::Deprecator.skip_warning do
+        Faker::Dogs.say
+      end
+    end
+
+    assert_empty(actual_stdout)
+    assert_empty(actual_stderr)
+    assert_equal 'meow', Faker::Dogs.say
+  end
+
+  def test_deprecated_with_skip_warning_does_not_generate_message
+    Faker::Deprecator.skip_warning do
+      assert_not_deprecated do
+        Faker::Dogs.say
+      end
+    end
+
+    assert_equal 'meow', Faker::Dogs.say
+  end
+end
+
+module Faker
+  class Cats < Base
+    def self.say
+      'meow'
+    end
+  end
+
+  include Faker::Deprecator
+  deprecate_generator('Dogs', Cats)
+end

test/support/deprecation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Based on Rails Testing Deprecator
+# https://github.com/rails/rails/blob/main/activesupport/lib/active_support/testing/deprecation.rb
+
+# Asserts that a matching deprecation warning was emitted during the execution of the yielded block.
+#
+#   assert_deprecated do
+#     DeprecatedGenerator.generate
+#   end
+#
+def assert_deprecated(&block)
+  warning = with_captured_stdout(&block)
+  result = yield block
+
+  refute_predicate warning, :empty?, 'Expected a deprecation warning within the block but received none'
+
+  result
+end
+
+# Asserts that no deprecation warnings are emitted during the execution of the yielded block.
+#
+#   assert_not_deprecated do
+#     Faker::Internet.email
+#   end
+def assert_not_deprecated(&block)
+  warning = with_captured_stdout(&block)
+  result = yield block
+
+  assert_predicate warning, :empty?, "Expected no deprecation warning within the block but received a deprecation: #{warning}"
+  result
+end
+
+def with_captured_stdout(&block)
+  original_stdout = $stdout
+  $stdout = StringIO.new
+  yield block
+  $stdout.string
+ensure
+  $stdout = original_stdout
+end

test/test_faker_deprecator.rb

@@ -11,6 +11,7 @@
 
 require_relative 'support/assert_not_english'
 require_relative 'support/assert_email_regex'
+require_relative 'support/deprecation'
 require 'minitest/autorun'
 require 'test/unit'
 require 'rubygems'