FEATURE: Before(:all) and after(:all) callbacks added (#1740)

* Before(:all) and after(:all) callbacks added

* Update docs/src/ref/hooks.md

Co-authored-by: Valerie Burzynski <[email protected]>

* Update docs/src/callbacks/summary.md

Co-authored-by: Valerie Burzynski <[email protected]>

* Update docs/src/callbacks/summary.md

Co-authored-by: Valerie Burzynski <[email protected]>

* Update docs/src/callbacks/summary.md

Co-authored-by: Valerie Burzynski <[email protected]>

* small code tidy-up

- moved `require` statemnet to top of file (containers/test_log.rb)
- removed blank line (doc/src/callbacks/summary.md)

---------

Co-authored-by: Valerie Burzynski <[email protected]>

Author: CodeMeister

docs/src/SUMMARY.md

@@ -84,6 +84,7 @@
   - [Multiple callbacks](callbacks/multiple-callbacks.md)
   - [Global callbacks](callbacks/global-callbacks.md)
   - [Symbol#to_proc](callbacks/symbol-to_proc.md)
+  - [Callback order](callbacks/callback_order.md)
 - [Modifying factories](modifying-factories/summary.md)
 - [Linting Factories](linting-factories/summary.md)
 - [Custom Construction](custom-construction/summary.md)

docs/src/callbacks/callback_order.md

@@ -0,0 +1,101 @@
+# Callback Order
+
+When a callback event like `after_build` or `before_all` is triggered, all callbacks for that event are excuted in the following order:
+
+1. Global callbacks.
+2. Inherited callbacks.
+3. Factory callbacks.
+4. Trait callbacks (in the order requested).
+
+## A simple factory example:
+
+```ruby
+FactoryBot.define do
+  before(:all) { puts "Global before(:all)" }
+  after(:all) { puts "Global after(:all)" }
+
+  factory :user do
+    before(:all) { puts "User before(:all)" }
+    after(:all) { puts "User after(:all)" }
+    after(:build) { puts "User after(:build)"
+    
+    trait :trait_a do
+      after(:build) { puts "Trait-A after(:build)" 
+    end
+    
+    trait :trait_b do 
+      after(:build) { puts "Trait-B after(:build)" }
+    end
+  end
+end
+
+build(:user, :trait_b, :trait_a) 
+
+# Result:
+#
+# 1. "Global before(:all)"
+# 2. "User before(:all)"
+# 3. "User after(:build)"
+# 4. "Trait-B after(:build)"
+# 5. "Trait-A after(:build)"
+# 6. "Global after(:all)"
+# 7. "User after(:all)"
+
+```
+
+
+## An inherited factory example:
+
+```ruby
+FactoryBot.define do
+  before(:all) { puts "Global before(:all)" }
+  after(:build) { puts "Global after(:build)" }
+  after(:all) { puts "Global after(:all)" }
+
+  factory :parent do
+    before(:all) { puts "Parent before(:all)" }
+    after(:all) { puts "Parent after(:all)" }
+    after(:build) { puts "Parent after(:build)" }
+    
+    trait :trait_a do 
+      after(:build) { puts "Trait-A after(:build)" }
+    end
+
+    factory :child do
+      before(:all) { puts "Child before(:all)" }
+      after(:build) { puts "Child after(:build)" }
+      after(:all) { puts "Child after(:all)" }
+
+      trait :trait_b do
+        after(:build) { puts "Trait-B after(:build)" }
+        after(:all) { puts "Trait-B after(:all)" }
+      end
+
+      trait :trait_c do
+        after(:build) { puts "Trait-C after(:build)" }
+        before(:all) { puts "Trait-C before(:all)" }
+      end
+    end
+  end
+end
+
+build(:child, :trait_c, :trait_a, :trait_b) 
+
+# Result:
+#
+# 1. "Global before(:all)"
+# 2. "Parent before(:all)"
+# 3. "Child before(:all)"
+# 4. "Trait-C before(:all)"
+# 5. "Global after(:build)"
+# 6. "Parent after(:build)"
+# 7. "Child after(:build)"
+# 8. "Trait-C after(:build)"
+# 9. "Trait-A after(:build)"
+# 10. "Trait-B after(:build)"
+# 11. "Global after(:all)"
+# 12. "Parent after(:all)"
+# 13. "Child after(:all)"
+# 14. "Trait-B after(:all)"
+
+```

docs/src/callbacks/summary.md

@@ -1,19 +1,42 @@
 # Callbacks
 
-factory\_bot makes four callbacks available:
+factory\_bot makes six callbacks available:
 
-* after(:build)   - called after a factory is built   (via `FactoryBot.build`, `FactoryBot.create`)
-* before(:create) - called before a factory is saved  (via `FactoryBot.create`)
-* after(:create)  - called after a factory is saved   (via `FactoryBot.create`)
-* after(:stub)    - called after a factory is stubbed (via `FactoryBot.build_stubbed`)
+| Callback        | Timing                                                                                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| before(:all)    | called before a factory constructs an object (via `FactoryBot.build`, `FactoryBot.create`, or `FactoryBot.build_stubbed`) |
+| after(:build)   | called after a factory builds an object (via `FactoryBot.build` or `FactoryBot.create`)                                   |
+| before(:create) | called before a factory saves an object (via `FactoryBot.create`)                                                         |
+| after(:create)  | called after a factory saves an object (via `FactoryBot.create`)                                                          |
+| after(:stub)    | called after a factory stubs an object (via `FactoryBot.build_stubbed`)                                                   |
+| after(:all)     | called after a factory constructs an object (via `FactoryBot.build`, `FactoryBot.create`, or `FactoryBot.build_stubbed`)  |
 
-Examples:
+
+## Examples
+
+### Calling an object's own method after building
 
 ```ruby
-# Define a factory that calls the generate_hashed_password method after the user factory is built
+## 
+# Define a factory that calls the generate_hashed_password method
+# after the user factory is built.
+#
+# Note that you'll have an instance of the object in the block
+#
 factory :user do
   after(:build) { |user, context| generate_hashed_password(user) }
 end
 ```
 
-Note that you'll have an instance of the object in the block.
+### Skipping an object's own :after_create callback
+
+```ruby
+##
+# Disable a model's own :after_create callback that sends an email 
+# on creation, then re-enable it afterwards
+#
+factory :user do
+  before(:all){ User.skip_callback(:create, :after, :send_welcome_email) }
+  after(:all){ User.set_callback(:create, :after, :send_welcome_email) }
+end
+```

docs/src/ref/hooks.md

@@ -13,7 +13,7 @@ factory. Within a `FactoryBot.define` block, they are global to all factories.
 
 The `callback` method allows you to hook into any factory\_bot callback by
 name. The pre-defined names, as seen in the [build strategies] reference, are
-`after_build`, `before_create`, `after_create`, and `after_stub`.
+`before_all`, `after_build`, `before_create`, `after_create`, `after_stub`, and `after_all`.
 
 This method takes a splat of names, and a block. It invokes the block any time
 one of the names is activated. The block can be anything that responds to

lib/factory_bot/factory.rb

@@ -33,6 +33,7 @@ def build_class
 
     def run(build_strategy, overrides, &block)
       block ||= ->(result) { result }
+
       compile
 
       strategy = StrategyCalculator.new(build_strategy).strategy.new
@@ -44,7 +45,11 @@ def run(build_strategy, overrides, &block)
       evaluation =
         Evaluation.new(evaluator, attribute_assigner, compiled_to_create, observer)
 
-      strategy.result(evaluation).tap(&block)
+      evaluation.notify(:before_all, nil)
+      instance = strategy.result(evaluation).tap(&block)
+      evaluation.notify(:after_all, instance)
+
+      instance
     end
 
     def human_names