Factory Sequence: bug-fix + new methods for setting, generating and rewinding (#1742)

* Sequences refactored for generating, rewinding, setting & bugfix.

:generate and :generate_list expanded to work with factory sequences:
  - generate(:sequence_name)
  - generate(:factory_name, :sequence_name)
  - generate_list(:sequence_name, 3)
  - generate_list(:factory_name, :sequence_name, 3)

:rewind_seqence added to rewind individual sequences
  - rewind_sequence(:factory_name, :trait_name, :sequence_name)

:set_sequence added to set the sequence to a new value:
  - set_sequence(:sequence_name, new_value)
  - set_sequence(:factory_name, :sequence_name, new_value)

Test coverage at 100% & docs updated.

* Conflict with Truffleruby and RSpec

When calling :peek on the Enumerator class, internally it calls :next.
There was an issue when stubbing the :next method to raise an exception, then
triggering it when calling :peek.

This was only an issue in Truffleruby.

Co-authored-by: Neil Carvalho <me@neil.pro>

Author: CodeMeister

.gitignore

@@ -9,5 +9,6 @@ coverage
 tmp
 bin
 .rubocop-https*
+.zed
 
 gemfiles/*.lock

docs/src/SUMMARY.md

@@ -61,11 +61,14 @@
   - [Global sequences](sequences/global-sequences.md)
   - [With dynamic attributes](sequences/with-dynamic-attributes.md)
   - [As implicit attributes](sequences/as-implicit-attributes.md)
-  - [Inline sequences](sequences/inline-sequences.md)
+  - [Factory sequences](sequences/factory-sequences.md)
   - [Initial value](sequences/initial-value.md)
   - [Without a block](sequences/without-a-block.md)
   - [Aliases](sequences/aliases.md)
+  - [Sequence URIs](sequences/sequence-uris.md)
   - [Rewinding](sequences/rewinding.md)
+  - [Setting the value](sequences/setting-the-value.md)
+  - [Generating a sequence](sequences/generating.md)
   - [Uniqueness](sequences/uniqueness.md)
 - [Traits](traits/summary.md)
   - [As implicit attributes](traits/as-implicit-attributes.md)

docs/src/sequences/inline-sequences.md renamed to docs/src/sequences/factory-sequences.md

@@ -1,6 +1,6 @@
-# Inline sequences
+# Factory sequences
 
-And it's also possible to define an in-line sequence that is only used in
+And it's also possible to define a sequence that is only used in
 a particular factory:
 
 ```ruby

docs/src/sequences/generating.md

@@ -0,0 +1,76 @@
+# Generating a Sequence
+
+Being able to diectly generate a sequence, without having to build the object can really speed up testing. This can be achieved by passing the [sequence URI](sequence-uris.md) to `:generate` for a single value or `:generate_list` for an Array of sequential values.
+
+```ruby
+FactoryBot.define do
+  sequence(:char, 'a') {|c| "global_character_#{c}" }
+
+  factory :user do
+    sequence(:name, %w[Jane Joe Josh Jayde John].to_enum)
+
+    trait :with_age do
+      sequence(:age, 21)
+    end
+  end
+end
+
+##
+# char
+generate(:char) # "global_character_a"
+generate_list(:char, 2) # ["global_character_b", "global_character_c"]
+generate(:char) # "global_character_d"
+
+##
+# user name
+generate(:user, :name) # "Jane"
+generate_list(:user, :name, 3) # ['Joe', 'Josh', 'Jayde']
+generate(:user, :name) # "John"
+
+##
+# user age
+generate(:user, :with_age, :age) # 21
+generate_list(:user, :with_age, :age, 5) # [22, 23, 24, 25, 26]
+generate(:user, :with_age, :age) # 27
+```
+
+## Scope
+
+On occasion a sequence block may refer to a scoped attribute. In this case, the scope must be provided, or else an exception will be raised:
+
+```ruby
+FactoryBot.define do
+  factory :user do
+    sequence(:email) { |n| "#{name}-#{n}@example.com" }
+  end
+end
+
+generate(:user, :email)
+# ArgumentError, Sequence user:email failed to return a value. Perhaps it needs a scope to operate? (scope: <object>)
+
+jester = build(:user, name: "Jester")
+jester.email # "Jester-1@example.com"
+
+generate(:user, :email, scope: jester)
+# "Jester-2@example.com"
+
+generate_list(:user, :email, 2, scope: jester)
+# ["Jester-3@example.com", "Jester-4@example.com"]
+```
+
+When testing, the scope can be any object that responds to the referrenced attributes:
+
+```ruby
+require 'ostruct'
+
+FactoryBot.define
+  factory :user do
+    sequence(:info) { |n| "#{name}-#{n}-#{age + n}" }
+  end
+end
+
+test_scope = OpenStruct.new(name: "Jester", age: 23)
+
+generate_list('user/info', 3, scope: test_scope)
+# ["Jester-1-24", "Jester-2-25", "Jester-3-26"]
+```

docs/src/sequences/rewinding.md

@@ -1,17 +1,52 @@
 # Rewinding
 
-Sequences can also be rewound with `FactoryBot.rewind_sequences`:
+Sequences can also be rewound to their starting value:
+
+## All sequences
+
+Rewind all global and factory sequences with `FactoryBot.rewind_sequences`:
 
 ```ruby
-sequence(:email) {|n| "person#{n}@example.com" }
+FactoryBot.define do
+  sequence(:email) {|n| "person#{n}@example.com" }
+
+  factory :user do
+    sequence(:email) {|n| "user#{n}@example.com" }
+  end
+end
 
 generate(:email) # "person1@example.com"
 generate(:email) # "person2@example.com"
 generate(:email) # "person3@example.com"
 
+generate(:user, :email) # "user1@example.com"
+generate(:user, :email) # "user2@example.com"
+generate(:user, :email) # "user3@example.com"
+
 FactoryBot.rewind_sequences
 
-generate(:email) # "person1@example.com"
+generate(:email)        # "person1@example.com"
+generate(:user, :email) # "user1@example.com"
 ```
 
-This rewinds all registered sequences.
+## Individual sequences
+
+An individual sequence can be rewound by passing the [sequence URI](sequence-uris.md) to `FactoryBot.rewind_sequence`:
+
+```ruby
+FactoryBot.define do
+  sequence(:email) {|n| "global_email_#{n}@example.com" }
+
+  factory :user do
+    sequence(:email) {|n| "user_email_#{n}@example.com" }
+  end
+end
+
+FactoryBot.rewind_sequence(:email)
+generate(:email)
+#=> "global_email_1@example.com"
+
+factoryBot.rewind_sequence(:user, :email)
+generate(:user, :email)
+#=> "user_email_1@example.com"
+```

docs/src/sequences/sequence-uris.md

@@ -0,0 +1,105 @@
+# Sequence URIs
+
+There are many reasons to manipulate a specific sequence:
+
+- generating a single value with: `generate`
+- generating multiple values with: `generate_list`
+- setting it to a new value with `FactoryBot.set_sequence`
+- rewinding it with: `rewind_sequence`
+
+To accomplish this we need to be able to reference the desired sequence. This is achieved with its unique URI.
+
+## URI Composition
+
+Each URI is composed of up to three names:
+
+| position | name           | required                                                             |
+| :------: | -------------- | -------------------------------------------------------------------- |
+|    1.    | factory name:  | **if** - the sequence is defined within a Factory or a Factory Trait |
+|    2.    | trait name:    | **if** - the sequence is defined within a Trait                      |
+|    3.    | sequence name: | **always required**                                                  |
+
+The URI can be entered as individual symbols:
+
+```ruby
+generate(:my_factory_name, :my_trait_name, :my_sequence_name)
+```
+
+**or** as individual strings:
+
+```ruby
+generate('my_factory_name', 'my_trait_name', 'my_sequence_name')
+```
+
+**or** as a single resource string:
+
+```ruby
+generate("my_factory_name/my_trait_name/my_sequence_name")
+```
+
+## Full URI example
+
+This example details all the possible scenarios, with the comments showing the URI used to generate a value for each specific sequence:
+
+```ruby
+FactoryBot.define do
+  sequence(:sequence) {|n| "global_sequence_#{n}"}
+  # generate(:sequence)
+
+  trait :global_trait do
+    sequence(:sequence) {|n| "global_trait_sequence_#{n}"}
+    # generate(:global_trait, :sequence)
+  end
+
+  factory :user do
+    sequence(:sequence) {|n| "user_sequence_#{n}"}
+    # generate(:user, :sequence)
+
+    trait :user_trait do
+      sequence(:sequence) {|n| "user_trait_sequence_#{n}"}
+      # generate(:user, :user_trait, :sequence)
+    end
+
+    factory :author do
+      sequence(:sequence) {|n| "author_sequence_#{n}"}
+      # generate(:author, :sequence)
+
+      trait :author_trait do
+        sequence(:sequence) {|n| "author_trait_sequence_#{n}"}
+        # generate(:author, :author_trait, :sequence)
+      end
+    end
+  end
+end
+```
+
+## Multi URIs
+
+It is possible for a single sequence to have multiple URIs.
+
+If the factory or trait has aliases, the sequence will have an additional URI for each alias, or combination of aliases.
+
+In this example, the same sequence can referenced in four different ways:
+
+```ruby
+factory :user, aliases: [:author] do
+  trait :user_trait, aliases: [:author_trait] do
+    sequence(:sequence) {|n| "author_trait_sequence_#{n}"}
+  end
+end
+
+# generate(:user,   :user_trait,   :sequence)
+# generate(:user,   :author_trait, :sequence)
+# generate(:author, :user_trait,   :sequence)
+# generate(:author, :author_trait, :sequence)
+```
+
+<div class='warning'>
+
+## Important
+
+- No matter how deeply nested, the factory name component of the URI is always the factory where the sequence is defined, not any parent factories.
+
+- If a factory inherits a sequence, the URI must reference the factory where it was defined, not the one in which it is used.
+
+</div>

docs/src/sequences/setting-the-value.md

@@ -0,0 +1,55 @@
+# Setting the value
+
+When testing or working in the console, being able to set the sequence to a specific value, is incredibly helpful. This can be achieved by passing the [sequence URI](sequence-uris.md) and the new value to `FactoryBot.set_sequence`:
+
+## Global Sequences
+
+Global sequences are set with the sequence name and the new value:
+
+```ruby
+FactoryBot.define do
+  sequence(:char, 'a') {|c| "global_character_#{c}" }
+
+  factory :user do
+    sequence(:name, %w[Jane Joe Josh Jayde John].to_enum)
+
+    trait :with_email do
+      sequence(:email) {|n| "user_#{n}@example.com" }
+    end
+  end
+end
+
+##
+# char
+generate(:char) # "global_character_a"
+FactoryBot.set_sequence(:char, 'z')
+generate(:char) # "global_character_z"
+
+##
+# user name
+generate(:user, :name) # "Jane"
+FactoryBot.set_sequence(:user, :name, 'Jayde')
+generate(:user, :name) # "Jayde"
+
+##
+# user email
+generate(:user, :with_email, :email) # "user_1@example.com"
+FactoryBot.set_sequence(:user, :with_email, :email, 1_234_567)
+generate(:user, :with_email, :email) # "user_1234567@example.com"
+```
+
+<div class='warning'>
+
+## Note
+
+- The new value must match the sequence collection: You cannot pass a String to an Integer based sequence!
+
+- An integer based sequence, such as a record ID, can accept any positive integer as the value.
+
+- A fixed collection sequence can accept any value within the collection.
+
+- An unlimited sequence, such as a character `sequence(:unlimited,'a')` will timeout if not found within the default maximum search time of three seconds.
+
+- The timeout can be configured with: `FactoryBot.sequence_setting_timeout = 1.5`
+
+</div>

lib/factory_bot.rb

@@ -46,6 +46,7 @@
 require "factory_bot/decorator/disallows_duplicates_registry"
 require "factory_bot/decorator/invocation_tracker"
 require "factory_bot/decorator/new_constructor"
+require "factory_bot/uri_manager"
 require "factory_bot/linter"
 require "factory_bot/version"
 
@@ -58,6 +59,9 @@ module FactoryBot
   mattr_accessor :automatically_define_enum_traits, instance_accessor: false
   self.automatically_define_enum_traits = true
 
+  mattr_accessor :sequence_setting_timeout, instance_accessor: false
+  self.sequence_setting_timeout = 3
+
   # Look for errors in factories and (optionally) their traits.
   # Parameters:
   # factories - which factories to lint; omit for all factories
@@ -73,17 +77,43 @@ def self.lint(*args)
 
   # Set the starting value for ids when using the build_stubbed strategy
   #
-  # Arguments:
-  # * starting_id +Integer+
-  #   The new starting id value.
+  # @param [Integer] starting_id The new starting id value.
   def self.build_stubbed_starting_id=(starting_id)
     Strategy::Stub.next_id = starting_id - 1
   end
 
   class << self
+    # @!method rewind_sequence(*uri_parts)
+    #   Rewind an individual global or inline sequence.
+    #
+    #   @param [Array<Symbol>, String] uri_parts The components of the sequence URI.
+    #
+    #   @example Rewinding a sequence by its URI parts
+    #     rewind_sequence(:factory_name, :trait_name, :sequence_name)
+    #
+    #   @example Rewinding a sequence by its URI string
+    #     rewind_sequence("factory_name/trait_name/sequence_name")
+    #
+    # @!method set_sequence(*uri_parts, value)
+    #   Set the sequence to a specific value, providing the new value is within
+    #   the sequence set.
+    #
+    #   @param [Array<Symbol>, String] uri_parts The components of the sequence URI.
+    #   @param [Object] value The new value for the sequence. This must be a value that is
+    #     within the sequence definition. For example, you cannot set
+    #     a String sequence to an Integer value.
+    #
+    #   @example
+    #     set_sequence(:factory_name, :trait_name, :sequence_name, 450)
+    #   @example
+    #     set_sequence([:factory_name, :trait_name, :sequence_name], 450)
+    #   @example
+    #     set_sequence("factory_name/trait_name/sequence_name", 450)
     delegate :factories,
       :register_strategy,
       :rewind_sequences,
+      :rewind_sequence,
+      :set_sequence,
       :strategy_by_name,
       to: Internal
   end