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).