README.md in insecure_random-1.0.0 vs README.md in insecure_random-2.0.0
- old
+ new
@@ -1,14 +1,11 @@
# InsecureRandom
-[](http://badge.fury.io/rb/insecure_random)
-[](https://travis-ci.org/laserlemon/insecure_random)
-[](https://codeclimate.com/github/laserlemon/insecure_random)
-[](https://coveralls.io/r/laserlemon/insecure_random)
-[](https://gemnasium.com/laserlemon/insecure_random)
+[](http://rubygems.org/gems/insecure_random)
+[](https://github.com/laserlemon/insecure_random/actions/workflows/rake.yml)
-InsecureRandom overwrites SecureRandom to enable predictability via seeding.
+InsecureRandom hooks into SecureRandom to enable predictability via seeding.
## Why?
### RSpec
@@ -31,14 +28,14 @@
rspec --seed=93487
```
RSpec does this by seeding and using `Kernel.rand` to order your specs. This has
the handy side effect of making other random test data reproducible as well. For
-example, your Factory Girl factories might use random data via Faker.
+example, your Factory Bot factories might use random data via Faker.
```ruby
-FactoryGirl.define do
+FactoryBot.define do
factory :user do
name { Faker::Name.name }
age { rand(100) }
end
end
@@ -62,22 +59,70 @@
isn't seedable, which means that RSpec isn't able to rerun your tests in a
predictable way.
### The Solution
-Fortunately, SecureRandom only defines a handful of methods so it's easy to
-override them to be backed by `Kernel.rand`.
+Fortunately, SecureRandom only defines a handful of methods so it's relatively
+easy to override them to be backed by `Kernel.rand`.
-And it gets even better. All of SecureRandom's methods are derived from
-`SecureRandom.random_bytes` so overriding just that one method does the trick!
+And it gets even better. All of SecureRandom's methods are derived from just
+one method: `SecureRandom.gen_random`. So overriding that one method does the
+trick!
+```ruby
+Kernel.srand(123)
+SecureRandom.alphanumeric # => "kMupcJV93fBPd34p"
+SecureRandom.alphanumeric # => "WTiAHSCC3JeqYAdJ"
+Kernel.srand(123)
+SecureRandom.alphanumeric # => "jID3bLAGYx2FHi27"
+
+InsecureRandom.enable!
+
+Kernel.srand(123)
+SecureRandom.alphanumeric # => "2YmG5zns39eGRfKQ"
+SecureRandom.alphanumeric # => "c58d341u4OJzkTyD"
+Kernel.srand(123)
+SecureRandom.alphanumeric # => "2YmG5zns39eGRfKQ"
+```
+
## Installation
Add InsecureRandom to your Gemfile's test group:
```ruby
group :development, :test do
gem "insecure_random"
end
```
-**Make sure that InsecureRandom is not loaded in production!**
+## Usage
+
+As of InsecureRandom 2.0, SecureRandom's behavior remains entirely unchanged
+until you explicitly enable InsecureRandom by adding the following to your
+test/spec helper:
+
+```ruby
+InsecureRandom.enable!
+```
+
+The `enable!` method globally enables repeatable results from SecureRandom via
+`Kernel.srand` seeding and can be disabled again with `InsecureRandom.disable!`.
+
+You may also use the `enable` method to _temporarily_ enable SecureRandom
+repeatability, only during execution of the given block. For example, RSpec
+can be configured to enable InsecureRandom for each individual example:
+
+```ruby
+RSpec.configure do |config|
+ config.around(:example) do |example|
+ InsecureRandom.enable do
+ example.run
+ end
+ end
+end
+```
+
+:star: InsecureRandom does not change SecureRandom's behavior until either the
+`InsecureRandom.enable!` or `InsecureRandom.enable` method is explicitly called.
+That said…
+
+:warning: **Make sure that InsecureRandom is not enabled in production!** :warning: