render_preview can pass parameters to preview (#1499)

* remove experimental tag

* move render_preview docs down

* update docs to reference more reliable `m` command

* `render_preview` can pass parameters to preview

* linters

Author: joelhawksley

docs/CHANGELOG.md

@@ -10,6 +10,10 @@ nav_order: 5
 
 ## main
 
+* `render_preview` can pass parameters to preview.
+
+    *Joel Hawksley*
+
 * Fix docs typos.
 
     *Joel Hawksley*

docs/CONTRIBUTING.md

@@ -56,7 +56,7 @@ The codespace environment includes a minimal Rails app with ViewComponent instal
 Use [`m`](https://rubygems.org/gems/m):
 
 ```command
-m test/view_component/YOUR_COMPONENT_test.rb:line_number
+bundle exec m test/view_component/YOUR_COMPONENT_test.rb:line_number
 ```
 
 ### Running tests for a specific version of Rails

docs/guide/previews.md

@@ -32,14 +32,26 @@ Then access the resulting previews at:
 
 _For a more interactive experience, consider using [Lookbook](https://github.com/allmarkedup/lookbook) or [ViewComponent::Storybook](https://github.com/jonspalmer/view_component_storybook)._
 
+## Passing parameters
+
+Set dynamic values from URL parameters by setting them as arguments:
+
+```ruby
+# test/components/previews/example_component_preview.rb
+class ExampleComponentPreview < ViewComponent::Preview
+  def with_dynamic_title(title: "Example component default")
+    render(ExampleComponent.new(title: title))
+  end
+end
+```
+
+Then pass in a value: `/rails/view_components/example_component/with_dynamic_title?title=Custom+title`.
+
 ## Previews as test cases
 
 Since 2.56.0
 {: .label }
 
-Experimental
-{: .label .label-yellow }
-
 Use `render_preview(name)` to render previews in ViewComponent unit tests:
 
 ```ruby
@@ -52,21 +64,18 @@ class ExampleComponentTest < ViewComponent::TestCase
 end
 ```
 
-## Passing parameters
-
-Set dynamic values from URL parameters by setting them as arguments:
+Parameters can also be passed:
 
 ```ruby
-# test/components/previews/example_component_preview.rb
-class ExampleComponentPreview < ViewComponent::Preview
-  def with_dynamic_title(title: "Example component default")
-    render(ExampleComponent.new(title: title))
+class ExampleComponentTest < ViewComponent::TestCase
+  def test_render_preview
+    render_preview(:with_default_title, params: { message: "Hello, world!" })
+
+    assert_text("Hello, world!")
   end
 end
 ```
 
-Then pass in a value: `/rails/view_components/example_component/with_dynamic_title?title=Custom+title`.
-
 ## Helpers
 
 The `ViewComponent::Preview` base class includes

docs/guide/slots.md

@@ -147,7 +147,7 @@ end
 
 ## Referencing slots
 
-As the content passed to slots is registered after a component is initialized, it cannot referenced in an initializer. One way to reference slot content is using the `before_render` [lifecycle method](/guide/lifecycle):
+As the content passed to slots is registered after a component is initialized, it can't be referenced in an initializer. One way to reference slot content is using the `before_render` [lifecycle method](/guide/lifecycle):
 
 ```ruby
 # blog_component.rb

lib/view_component/test_helpers.rb

@@ -80,9 +80,10 @@ def render_inline(component, **args, &block)
     #
     # In RSpec, `Preview` is appended to `described_class`.
     #
-    # @param preview [String] The name of the preview to be rendered.
+    # @param name [String] The name of the preview to be rendered.
+    # @param params [Hash] Parameters to be passed to the preview.
     # @return [Nokogiri::HTML]
-    def render_preview(name)
+    def render_preview(name, params: {})
       begin
         preview_klass = if respond_to?(:described_class)
           raise "`render_preview` expected a described_class, but it is nil." if described_class.nil?
@@ -97,6 +98,13 @@ def render_preview(name)
       end
 
       previews_controller = build_controller(Rails.application.config.view_component.preview_controller.constantize)
+
+      # From what I can tell, it's not possible to overwrite all request parameters
+      # at once, so we set them individually here.
+      params.each do |k, v|
+        previews_controller.request.params[k] = v
+      end
+
       previews_controller.request.params[:path] = "#{preview_klass.preview_name}/#{name}"
       previews_controller.response = ActionDispatch::Response.new
       result = previews_controller.previews

test/sandbox/app/components/my_component.html.erb

@@ -1 +1,2 @@
 <div>hello,world!</div>
+<%= content %>

test/sandbox/test/components/my_component_test.rb

@@ -12,4 +12,10 @@ def test_render_preview
 
     assert_selector("div", text: "hello,world!")
   end
+
+  def test_render_preview_with_args
+    render_preview(:with_content, params: {content: "foo"})
+
+    assert_text("foo")
+  end
 end

test/sandbox/test/components/previews/my_component_preview.rb

@@ -7,6 +7,10 @@ def default
     render(MyComponent.new)
   end
 
+  def with_content(content:)
+    render(MyComponent.new.with_content(content))
+  end
+
   def inside_banner
     render_with_template
   end