Conditionally print `$stdout` when invoking `run_generator` (#49448)

* Conditionally print `$stdout` when invoking `run_generator`

In an effort to improve the developer experience when debugging
generator tests, we add the ability to conditionally print `$stdout`
instead of capturing it.

This allows for calls to `binding.irb` and `puts` work as expected.

```sh
PRINT_STDOUT=true ./bin/test test/generators/actions_test.rb
```

* Update railties/CHANGELOG.md

Co-authored-by: Rafael Mendonça França <rafael@franca.dev>

* Rename environment variable

* Update generators guides.

* Update guides

---------

Co-authored-by: Rafael Mendonça França <rafael@franca.dev>

guides/source/contributing_to_ruby_on_rails.md

@@ -495,6 +495,12 @@ You can invoke `test_jdbcmysql`, `test_jdbcsqlite3` or `test_jdbcpostgresql` als
 
 To use an external debugger (pry, byebug, etc), install the debugger and use it as normal.  If debugger issues occur, run tests in serial by setting `PARALLEL_WORKERS=1` or run a single test with `-n test_long_test_name`.
 
+If running tests against generators you will need to set `RAILS_LOG_TO_STDOUT=true` in order for debugging tools to work.
+
+```sh
+RAILS_LOG_TO_STDOUT=true ./bin/test test/generators/actions_test.rb
+```
+
 ### Warnings
 
 The test suite runs with warnings enabled. Ideally, Ruby on Rails should issue no warnings, but there may be a few, as well as some from third-party libraries. Please ignore (or fix!) them, if any, and submit patches that do not issue new warnings.

guides/source/generators.md

@@ -528,6 +528,24 @@ In addition to those, Rails also provides many helper methods via
 * [`rake`][]
 * [`route`][]
 
+Testing Generators
+------------------
+
+Rails provides testing helper methods via
+[`Rails::Generators::Testing::Behaviour`][], such as:
+
+* [`run_generator`][]
+
+If running tests against generators you will need to set
+`RAILS_LOG_TO_STDOUT=true` in order for debugging tools to work.
+
+```sh
+RAILS_LOG_TO_STDOUT=true ./bin/test test/generators/actions_test.rb
+```
+
+In addition to those, Rails also provides additional assertions via
+[`Rails::Generators::Testing::Assertions`][].
+
 [`Rails::Generators::Actions`]: https://api.rubyonrails.org/classes/Rails/Generators/Actions.html
 [`environment`]: https://api.rubyonrails.org/classes/Rails/Generators/Actions.html#method-i-environment
 [`gem`]: https://api.rubyonrails.org/classes/Rails/Generators/Actions.html#method-i-gem
@@ -541,3 +559,6 @@ In addition to those, Rails also provides many helper methods via
 [`rails_command`]: https://api.rubyonrails.org/classes/Rails/Generators/Actions.html#method-i-rails_command
 [`rake`]: https://api.rubyonrails.org/classes/Rails/Generators/Actions.html#method-i-rake
 [`route`]: https://api.rubyonrails.org/classes/Rails/Generators/Actions.html#method-i-route
+[`Rails::Generators::Testing::Behaviour`]: https://api.rubyonrails.org/classes/Rails/Generators/Testing.html
+[`run_generator`]: https://api.rubyonrails.org/classes/Rails/Generators/Testing/Behaviour.html#method-i-run_generator
+[`Rails::Generators::Testing::Assertions`]: https://api.rubyonrails.org/classes/Rails/Generators/Testing/Assertions.html

railties/CHANGELOG.md

@@ -1,2 +1,15 @@
+*   Conditionally print `$stdout` when invoking `run_generator`
+
+    In an effort to improve the developer experience when debugging
+    generator tests, we add the ability to conditionally print `$stdout`
+    instead of capturing it.
+
+    This allows for calls to `binding.irb` and `puts` work as expected.
+
+    ```sh
+    RAILS_LOG_TO_STDOUT=true ./bin/test test/generators/actions_test.rb
+    ```
+
+    *Steve Polito*
 
 Please check [7-1-stable](https://github.com/rails/rails/blob/7-1-stable/railties/CHANGELOG.md) for previous changes.

railties/lib/rails/generators/testing/behavior.rb

@@ -65,11 +65,15 @@ module Rails
         # You can provide a configuration hash as second argument. This method returns the output
         # printed by the generator.
         def run_generator(args = default_arguments, config = {})
-          capture(:stdout) do
-            args += ["--skip-bundle"] unless args.include?("--no-skip-bundle") || args.include?("--dev")
-            args += ["--skip-bootsnap"] unless args.include?("--no-skip-bootsnap") || args.include?("--skip-bootsnap")
+          args += ["--skip-bundle"] unless args.include?("--no-skip-bundle") || args.include?("--dev")
+          args += ["--skip-bootsnap"] unless args.include?("--no-skip-bootsnap") || args.include?("--skip-bootsnap")
 
+          if ENV["RAILS_LOG_TO_STDOUT"] == "true"
             generator_class.start(args, config.reverse_merge(destination_root: destination_root))
+          else
+            capture(:stdout) do
+              generator_class.start(args, config.reverse_merge(destination_root: destination_root))
+            end
           end
         end