README.md in amber_component-0.0.5 vs README.md in amber_component-1.0.0
- old
+ new
@@ -281,26 +281,30 @@
```erb
<!-- app/controller/tasks/show.html.erb -->
<%= ModalComponent.call id: 'update-task-modal' title: 'Update the task' do %>
+ <!-- You can provide HTML and render other components -->
<h2>This is your task!</h2>
<%= form_with model: @task do |f| %>
<%= f.text_field :name %>
<%= f.text_area :description %>
<%= f.submit %>
<% end %>
+ <%= OtherComponent.call some: 'prop' %>
<% end %>
```
Note that this will raise an error when no block/nested content is provided.
In order to render nested content
only when it is present (will work without nested content)
you can use `yield.html_safe if block_given?`
In general `block_given?` will return `true` when a block/nested content is present, otherwise `false`.
+You can use it to render content conditionally based on
+whether nested content is present.
### Components with namespaces
Components may be defined inside multiple modules/namespaces.
@@ -355,9 +359,102 @@
```sh
$ bin/rails generate component FooBar
```
This will generate a new component in `app/components/foo_bar_component.rb` along with a view, stylesheet and test file.
+
+### Testing Components
+
+### Rails
+
+After setting up this gem with the rails generator
+`rails generate amber_component:install` a new abstract
+test class will be available called `ApplicationComponentTestCase`.
+
+It provides a handful of helper methods to make it
+easier to inspect the rendered HTML.
+
+A simple test file may look like this:
+
+```ruby
+# test/components/foo_component_test.rb
+
+require 'test_helper'
+
+class FooComponentTest < ApplicationComponentTestCase
+ test 'render correct HTML' do
+ # Specify what the assertions are supposed to
+ # check against.
+ #
+ # There can be multiple renders in one test
+ # but they override the previous one.
+ # So there is only one rendered component
+ # at any given time.
+ render do
+ FooComponent.call some: 'prop'
+ end
+
+ # Assertions on the rendered HTML
+
+ # Use a CSS selector
+ assert_selector ".foo_component span.my_class", text: 'Some Text'
+ # Check text
+ assert_text 'Amber Component is awesome!'
+ end
+end
+```
+
+A full list of available assertions can be found [here](https://rubydoc.info/github/jnicklas/capybara/Capybara/Node/Matchers).
+
+### Non Rails
+
+There is a test case class for minitest. You can
+access it by requiring `'amber_component/minitest_test_case'`.
+
+It has the same assertion methods as the Rails test case class.
+It requires [capybara](https://github.com/teamcapybara/capybara) to be installed and present in the Gemfile.
+
+A full list of available assertions can be found [here](https://rubydoc.info/github/jnicklas/capybara/Capybara/Node/Matchers).
+
+```ruby
+require 'amber_component/minitest_test_case'
+
+class FooComponentTest < AmberComponent::MinitestTestCase
+ def test_render_correct_html
+ # Specify what the assertions are supposed to
+ # check against.
+ #
+ # There can be multiple renders in one test
+ # but they override the previous one.
+ # So there is only one rendered component
+ # at any given time.
+ render do
+ FooComponent.call some: 'prop'
+ end
+
+ # Assertions on the rendered HTML
+
+ # Use a CSS selector
+ assert_selector ".foo_component span.my_class", text: 'Some Text'
+ # Check text
+ assert_text 'Amber Component is awesome!'
+ end
+end
+```
+
+There is also a helper module which provides all of these assertions
+under `'amber_component/test_helper'`.
+
+```ruby
+require 'amber_component/test_helper'
+
+class MyAbstractTestCase < ::Minitest::Test
+ include ::AmberComponent::TestHelper
+end
+```
+
+Note that this module has only been tested with minitest and rails test suites,
+so it may require overriding or implementing a few methods to work with other test suites.
## Contribute
Do you want to contribute to AmberComponent? Open the issues page and check for the help wanted label! But before you start coding, please read our [Contributing Guide](https://github.com/amber-ruby/amber_component/blob/main/CONTRIBUTING.md).