Add Faker::Date.in_date_period (faker-ruby#1755)

* Add new class method in_date_period to Faker::Date

* Add unit test cases for Faker::Date.in_date_period class method

* Add YARD documentation for Faker::Date.in_date_period class method

* Add more documentation for Faker::Date.in_date_period class method

* Fix method version to be next instead of 2.3.0

* Fix documentation description

Co-Authored-By: Connor Shea <connor.james.shea@gmail.com>

* Fix documentation description

Co-Authored-By: Connor Shea <connor.james.shea@gmail.com>

* Update the documentation examples

* revert commit b3ba644 for updating docs

* Remove extra lines

doc/default/date.md

@@ -20,4 +20,16 @@ Faker::Date.backward(days: 14) #=> "Fri, 19 Sep 2014"
 # Random birthday date (maximum age between 18 and 65)
 # Keyword arguments: min_age, max_age
 Faker::Date.birthday(min_age: 18, max_age: 65) #=> "Mar, 28 Mar 1986"
+
+# Random date in current year
+Faker::Date.in_date_period #=> #<Date: 2019-09-01>
+
+# Random date for range of year 2018 and month 2
+# Keyword arguments: year, month 
+Faker::Date.in_date_period(year: 2018, month: 2) #=> #<Date: 2018-02-26>
+
+# Random date for range of current year and month 2
+# Keyword arguments: month 
+Faker::Date.in_date_period(month: 2) #=> #<Date: 2019-02-26>
+
 ```

lib/faker/default/date.rb

@@ -133,6 +133,30 @@ def birthday(legacy_min_age = NOT_GIVEN, legacy_max_age = NOT_GIVEN, min_age: 18
         between(from: from, to: to).to_date
       end
 
+      ##
+      # Produces a date in the year and/or month specified.
+      #
+      # @param month [Integer] represents the month of the date
+      # @param year [Integer] represents the year of the date
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.in_date_period #=> #<Date: 2019-09-01>
+      #
+      # @example
+      #   Faker::Date.in_date_period(year: 2018, month: 2) #=> #<Date: 2018-02-26>
+      #
+      # @example
+      #   Faker::Date.in_date_period(month: 2) #=> #<Date: 2019-02-26>
+      #
+      # @faker.version next
+      def in_date_period(month: nil, year: ::Date.today.year)
+        from = ::Date.new(year, month || 1, 1)
+        to = ::Date.new(year, month || 12, ::Date.civil(year, month || 12, -1).day)
+
+        between(from: from, to: to).to_date
+      end
+
       private
 
       def birthday_date(date, age)

test/faker/default/test_faker_date.rb

@@ -144,4 +144,40 @@ def test_default_birthday
       assert birthday < birthdate_max, "Expect < \"#{birthdate_max}\", but got #{birthday}"
     end
   end
+
+  def test_default_in_date_period
+    current_year = Date.today.year
+    10.times do
+      date = @tester.in_date_period
+      assert date.year == current_year
+    end
+  end
+
+  def test_in_date_period_with_year
+    year = 2015
+    10.times do
+      date = @tester.in_date_period(year: year)
+      assert date.year == year
+    end
+  end
+
+  def test_in_date_period_with_month
+    month = 2
+    current_year = Date.today.year
+    10.times do
+      date = @tester.in_date_period(month: month)
+      assert date.month == month
+      assert date.year == current_year
+    end
+  end
+
+  def test_in_date_period_date
+    year = 2008
+    month = 3
+    10.times do
+      date = @tester.in_date_period(year: year, month: month)
+      assert date.month == month
+      assert date.year == year
+    end
+  end
 end