rspec-html 0.3.2 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 654cc8f392f2bde8068c50baedce33357749605760fe00d46558d6aef072a21f
-  data.tar.gz: 7d207122c82ceb3681ab65cd00c05871c73fbe2628855943fa6c6758ab957451
+  metadata.gz: c535d0ae9c4cf1a7f73cdae79bf0b09a6ad24e78fb7fe787ea098c9640456940
+  data.tar.gz: 335afe827f7526ed40446930aa6555f06a54c76b0da532c0097b435e0d622ec0
 SHA512:
-  metadata.gz: a1295ec0d0106dcfc7dc4157be1a56527137b2c671d814e1a62226a062a8e83844bf2571cbd42a90e2317033b4f39a8b4c433b2733ae3e186aed9ce6af1d6e7e
-  data.tar.gz: 8e5b3027c778ccbbf5ddc46b3b915ee87de9b3e0cbdbd022c196b6a81e4cb2912faccf8eebaab6b76e4ce517d3c957e91a79bb5f2c28c7f2a20193e5e0e1dd8c
+  metadata.gz: 161327678741ab16f3f010e8c4e3c30d9b098c63387d26e504f45cb54fd7115b2b21e6dd051a683312a489e6d007c3355e25ef3aed4a0f5451ec7fcdbff1d1e0
+  data.tar.gz: b662a85ff8fb34ca580ec8a883bd5241201823cd64decb531929f478f03f24490aaaba123bdad005e2e51d2c52265581063229d19c5cc0c1b9bf35294dd8ce57

data/.gitignore

@@ -14,3 +14,4 @@
 *.swo
 .byebug_history
 rspec-html-*.gem
+/rspec-documentation/bundle/

data/.ruby-version

@@ -1 +1 @@
-2.6.9
+2.7.8

data/Gemfile

@@ -6,12 +6,14 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'activesupport', '~> 6.1'
-gem 'bundler', '~> 2.0'
-gem 'devpack', '~> 0.4.0'
-gem 'i18n', '~> 1.7'
+gem 'devpack', '~> 0.4.1'
+gem 'i18n', '~> 1.14'
+gem 'mail', '~> 2.8'
 gem 'rake', '~> 13.0'
+gem 'rspec-documentation', '~> 0.0.7'
+gem 'rspec-file_fixtures', '~> 0.1.6'
 gem 'rspec-its', '~> 1.3'
-gem 'rubocop', '~> 1.29'
+gem 'rubocop', '~> 1.52'
 gem 'rubocop-rake', '~> 0.6.0'
-gem 'rubocop-rspec', '~> 2.10'
+gem 'rubocop-rspec', '~> 2.22'
 gem 'strong_versions', '~> 0.4.5'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rspec-html (0.3.2)
+    rspec-html (0.3.4)
       nokogiri (~> 1.10)
       rspec (~> 3.0)
 
@@ -16,34 +16,68 @@ GEM
       zeitwerk (~> 2.3)
     ast (2.4.2)
     concurrent-ruby (1.2.2)
+    date (3.3.3)
     devpack (0.4.1)
     diff-lcs (1.5.0)
-    i18n (1.13.0)
+    htmlbeautifier (1.4.2)
+    i18n (1.14.1)
       concurrent-ruby (~> 1.0)
     json (2.6.3)
-    mini_portile2 (2.8.2)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    mini_mime (1.1.2)
     minitest (5.18.0)
-    nokogiri (1.13.10)
-      mini_portile2 (~> 2.8.0)
+    net-imap (0.3.4)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.1)
+      timeout
+    net-smtp (0.3.3)
+      net-protocol
+    nokogiri (1.15.2-x86_64-linux)
       racc (~> 1.4)
     paint (2.3.0)
+    paintbrush (0.1.3)
     parallel (1.23.0)
-    parser (3.2.2.1)
+    parser (3.2.2.3)
       ast (~> 2.4.1)
-    racc (1.6.2)
+      racc
+    racc (1.7.0)
     rainbow (3.1.1)
     rake (13.0.6)
-    regexp_parser (2.8.0)
+    redcarpet (3.6.0)
+    regexp_parser (2.8.1)
     rexml (3.2.5)
+    rouge (4.1.2)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
       rspec-mocks (~> 3.12.0)
     rspec-core (3.12.2)
       rspec-support (~> 3.12.0)
+    rspec-documentation (0.0.7)
+      htmlbeautifier (~> 1.4)
+      kramdown (~> 2.4)
+      kramdown-parser-gfm (~> 1.1)
+      nokogiri (~> 1.15)
+      paintbrush (~> 0.1.3)
+      redcarpet (~> 3.6)
+      rouge (~> 4.1)
+      rspec (~> 3.12)
     rspec-expectations (3.12.3)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
+    rspec-file_fixtures (0.1.6)
+      rspec (~> 3.0)
     rspec-its (1.3.0)
       rspec-core (>= 3.0.0)
       rspec-expectations (>= 3.0.0)
@@ -51,7 +85,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.0)
-    rubocop (1.50.2)
+    rubocop (1.52.0)
       json (~> 2.3)
       parallel (~> 1.10)
       parser (>= 3.2.0.0)
@@ -61,39 +95,45 @@ GEM
       rubocop-ast (>= 1.28.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.28.0)
+    rubocop-ast (1.29.0)
       parser (>= 3.2.1.0)
     rubocop-capybara (2.18.0)
       rubocop (~> 1.41)
+    rubocop-factory_bot (2.23.1)
+      rubocop (~> 1.33)
     rubocop-rake (0.6.0)
       rubocop (~> 1.0)
-    rubocop-rspec (2.20.0)
+    rubocop-rspec (2.22.0)
       rubocop (~> 1.33)
       rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
     ruby-progressbar (1.13.0)
     strong_versions (0.4.5)
       i18n (>= 0.5)
       paint (~> 2.0)
+    timeout (0.3.2)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.4.2)
     zeitwerk (2.6.8)
 
 PLATFORMS
-  ruby
+  x86_64-linux
 
 DEPENDENCIES
   activesupport (~> 6.1)
-  bundler (~> 2.0)
-  devpack (~> 0.4.0)
-  i18n (~> 1.7)
+  devpack (~> 0.4.1)
+  i18n (~> 1.14)
+  mail (~> 2.8)
   rake (~> 13.0)
+  rspec-documentation (~> 0.0.7)
+  rspec-file_fixtures (~> 0.1.6)
   rspec-html!
   rspec-its (~> 1.3)
-  rubocop (~> 1.29)
+  rubocop (~> 1.52)
   rubocop-rake (~> 0.6.0)
-  rubocop-rspec (~> 2.10)
+  rubocop-rspec (~> 2.22)
   strong_versions (~> 0.4.5)
 
 BUNDLED WITH
-   2.3.11
+   2.4.13

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019 Bob Farrell
+Copyright (c) 2019-2023 Robert Farrell
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/Makefile

@@ -1,5 +1,14 @@
+project=rspec-html
+
 .PHONY:
 test:
 	bundle exec rspec
 	bundle exec rubocop
 	bundle exec strong_versions
+	bundle exec rspec-documentation
+
+.PHONY: publish
+publish:
+	@RSPEC_DOCUMENTATION_URL_ROOT='/$(project)' bundle exec rspec-documentation
+	@rsync --delete -r rspec-documentation/bundle/ docs01.bob.frl:/mnt/docs/$(project)/
+	@echo 'Published.'

data/README.md

@@ -1,13 +1,15 @@
 # RSpec::HTML
 
-_RSpec::HTML_ provides a simple object interface to HTML responses from [_RSpec Rails_ request specs](https://relishapp.com/rspec/rspec-rails/docs/request-specs/request-spec).
+_RSpec::HTML_ provides a simple object interface to _HTML_ content.
+
+You can use _RSpec::HTML_ to test any _HTML_ produced by your library or application and it works out of the box with [_RSpec Rails_ request specs](https://relishapp.com/rspec/rspec-rails/docs/request-specs/request-spec).
 
 ## Installation
 
 Add the gem to your `Gemfile`:
 
 ```ruby
-gem 'rspec-html', '~> 0.3.0'
+gem 'rspec-html', '~> 0.3.4'
 ```
 
 And rebuild your bundle:
@@ -16,205 +18,9 @@ And rebuild your bundle:
 $ bundle install
 ```
 
-## Usage
-
-Require the gem in your `spec_helper.rb`:
-
-```
-# spec/spec_helper.rb
-require 'rspec/html'
-```
-
-Several [matchers](#matchers) are provided to identify text and _HTML_ elements within the _DOM_. These matchers can only be used with the provided [object interface](#object-interface).
-
-### Browser Inspection
-
-To open the current document in your operating system's default browser, call `document.open`. Use this to inspect _HTML_ content while debugging.
-
-```ruby
-it 'has complex HTML' do
-  get '/my/path'
-  document.open
-end
-```
-
-Alternatively `document.html_path` writes the current document to a temporary file and returns its path.
-
-### Object Interface
-<a name="object-interface"></a>
-
-The top-level object `document` is available in all tests which reflects the current response body (e.g. in request specs).
-
-If you need to parse _HTML_ manually you can use the provided `parse_html` helper and then access `document` as normal:
-
-```ruby
-let(:document) { parse_html('<html><body>hello</body></html>') }
-
-it 'says hello' do
-  expect(document.body).to match_text 'hello'
-end
-```
-
-This method can also be used for _ActionMailer_ emails:
-```ruby
-let(:document) { parse_html(ActionMailer::Base.deliveries.last.body.decoded) }
-```
-
-**Changed in 0.3.0**: `parse_html` no longer assigns `document` automatically, you must use a `let` block to assign it yourself.
-
-To navigate the _DOM_ by a sequence of tag names use chained method calls on the `document` object:
-
-#### Tag Traversal
-```ruby
-expect(document.body.div.span).to match_text 'some text'
-```
-
-#### Attribute Matching
-To select an element matching certain attributes pass a hash to any of the chained methods:
-```ruby
-expect(document.body.div(id: 'my-div').span(align: 'left')).to match_text 'some text'
-```
-
-Special attributes like `checked` can be found using the `#attributes` method:
-```ruby
-expect(document.input(type: 'checkbox', name: 'my-name')).attributes).to include 'checked'
-```
-
-#### Class Matching
-_CSS_ classes are treated as a special case: to select an element matching a set of classes pass the `class` parameter:
-```ruby
-expect(document.body.div(id: 'my-div').span(class: 'my-class')).to match_text 'some text'
-expect(document.body.div(id: 'my-div').span(class: 'my-class my-other-class')).to match_text 'some text'
-```
-
-Classes can be provided in any order, i.e. `'my-class my-other-class'` is equivalent to `'my-other-class my-class'`.
-
-#### Simple CSS Matching
-To use a simple CSS selector when no other attributes are needed, pass a string to the tag method:
-```ruby
-expect(document.body.div('#my-id.my-class1.my-class2')).to match_text 'some text'
-```
-
-This is effectively shorthand for:
-```ruby
-expect(document.body.div(id: 'my-id', class: 'my-class1 my-class2')).to match_text 'some text'
-```
-
-#### Counting Matchers
-Use `once`, `twice`, `times`, `at_least`, and `at_most` to match element counts:
-```ruby
-expect(document.div('.my-class')).to match_text('some text').once
-expect(document.div('.my-class')).to match_text('some other text').twice
-expect(document.div('.my-class')).to match_text('some').times(3)
-expect(document.div('.my-class')).to match_text('some').at_least(:twice)
-expect(document.div('.my-class')).to match_text('some').at_least.times(3)
-expect(document.div('.my-class')).to match_text('some text').at_most.once
-expect(document.div('.my-class')).to match_text('some other text').at_most.twice
-expect(document.div('.my-class')).to match_text('text').at_most.times(3)
-```
-
-#### Text Matching
-To select an element that includes a given text string (i.e. excluding mark-up) use the `text` option:
-```ruby
-expect(document.body.div(text: 'some text').input[:value]).to eql 'some-value'
-```
-
-#### Attribute Retrieval
-To select an attribute from an element use the hash-style interface:
-```ruby
-expect(document.body.div.span[:class]).to match_text 'my-class'
-expect(document.body.div.span['data-content']).to match_text 'my content'
-```
-
-#### Retrieve all matching elements
-To select all matching elements as an array, use `#all`:
-```ruby
-expect(document.span.all.map(&:text)).to eql ['foo', 'bar', 'baz']
-```
-
-#### Indexing a Matching Set
-To select an index from a set of matched elements use the array-style interface (the first matching element is `1`, not `0`):
-```ruby
-expect(document.body.div[1].span[1][:class]).to match_text 'my-class'
-```
-
-Alternatively, use `#first`, `#last` or, when using _ActiveSupport_, `#second`, `#third`, etc. are also available:
-
-```ruby
-expect(document.body.div.first.span.last[:class]).to match_text 'my-class'
-```
-
-
-#### Element Existence
-To test if a matching element was found use the `exist` matcher:
-```ruby
-expect(document.body.div[1]).to exist
-expect(document.body.div[4]).to_not exist
-```
-
-#### Length of matched attributes
-To test the length of matched elements use the `#size` or `#length` method:
-```ruby
-expect(document.body.div.size).to eql 3
-expect(document.body.div.length).to eql 3
-```
-
-#### XPath / CSS Selectors
-If you need something more specific you can always use the _Nokogiri_ `#xpath` and `#css` methods on any element:
-```ruby
-expect(document.body.xpath('//span[@class="my-class"]')).to match_text 'some text'
-expect(document.body.css('span.my-class')).to match_text 'some text'
-```
-
-To simply check that an _XPath_ or _CSS_ selector exists use `have_xpath` and `have_css`:
-```ruby
-expect(document.body).to have_css 'html body div.myclass'
-expect(document.body).to have_xpath '//html/body/div[@class="myclass"]'
-```
-
-#### Checkboxes
-
-Use `be_checked` to test if a checkbox is checked:
-```ruby
-expect(document.input(type: 'checkbox')).to be_checked
-```
-
-### Custom Matchers
-<a name="matchers"></a>
-
-**Changed in 0.3.0**: The `contain_text` matcher has been removed. Use `match_text` instead.
-
-#### match_text
-
-Use the `match_text` matcher to locate text within a _DOM_ element. All mark-up elements are stripped when using this matcher.
-
-This matcher receives either a string or a regular expression.
-
-```ruby
-expect(document.body.form).to match_text 'Please enter your password'
-expect(document.body.form).to match_text /Please enter your [a-z]+/
-```
-
-#### contain_tag
-
-Use the `contain_tag` matcher to locate _DOM_ elements within any given element. This matcher accepts two arguments:
-
-* The tag name of the element you want to match (e.g. `:div`);
-* _(Optional)_ A hash of options. All options supported by the [object interface](#object-interface) can be used here.
-
-Without options:
-```ruby
-expect(document.div(class: 'my-class')).to contain_tag :span
-```
-
-With options:
-```ruby
-expect(document.form(class: 'my-form')).to contain_tag :input, name: 'email', class: 'email-input'
-```
-
-## Contributing
+## Documentation
 
-Feel free to make a pull request.
+See the [documentation](https://docs.bob.frl/rspec_html) for full usage guide.
 
 ## License
 

data/lib/rspec/html/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module HTML
-    VERSION = '0.3.2'
+    VERSION = '0.3.4'
   end
 end

data/lib/rspec_html/element.rb

@@ -49,6 +49,7 @@ module RSpecHTML
 
     Tags.each do |tag|
       define_method tag.downcase do |*args|
+        args[0] = " #{args[0]}" if args.first.is_a?(String) && args.first&.match?(/^[a-zA-Z]/)
         options = args.first
         return @search.new_from_find(tag.downcase, options) if options.nil?
 

data/lib/rspec_html/search.rb

@@ -56,11 +56,11 @@ module RSpecHTML
 
     # rubocop:disable Naming/PredicateName
     def has_css?(*args)
-      !@element&.css(*args)&.empty?
+      !blank?(@element&.css(*args))
     end
 
     def has_xpath?(*args)
-      !@element&.xpath(*args)&.empty?
+      !blank?(@element&.xpath(*args))
     end
     # rubocop:enable Naming/PredicateName
 
@@ -148,9 +148,9 @@ module RSpecHTML
     end
 
     def where_xpath(tag, query)
-      conditions = "[#{where_conditions(query)}]" unless query.compact.empty?
+      conditions = "[#{where_conditions(query)}]" unless blank?(query.compact)
       result = @element&.xpath(".//#{tag}#{conditions}")
-      return result unless @siblings.is_a?(Nokogiri::XML::NodeSet) && (result.nil? || result.empty?)
+      return result unless @siblings.is_a?(Nokogiri::XML::NodeSet) && blank?(result)
 
       @siblings.xpath(".//#{tag}#{conditions}")
     end
@@ -175,6 +175,12 @@ module RSpecHTML
 
       @element&.css(tag.to_s)
     end
+
+    def blank?(object)
+      return true unless object
+
+      object.empty?
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end

data/rspec-documentation/pages/000-Introduction.md

@@ -0,0 +1,38 @@
+# Introduction
+
+_RSpec::HTML_ provides a simple object interface to _HTML_ content.
+
+You can use _RSpec::HTML_ to test any _HTML_ produced by your library or application and it works out of the box with [_RSpec Rails_ request specs](https://relishapp.com/rspec/rspec-rails/docs/request-specs/request-spec).
+
+## Setup
+
+Load `rspec-html` in your `spec_helper.rb`:
+
+```ruby
+# spec/spec_helper.rb
+
+require 'rspec/html'
+```
+
+## Quick Example
+
+```rspec:html
+subject(:document) { parse_html(html) }
+
+let(:html) do
+  <<~HTML
+  <html>
+    <body>
+      <div>Some other content</div>
+      <div class="my-div">
+        My div content
+      </div>
+    </body>
+  </html>
+  HTML
+end
+
+it 'matches "My div content"' do
+  expect(document.html.body.div('.my-div')).to match_text 'My div content'
+end
+```

data/rspec-documentation/pages/010-Usage/010-The document Object.md

@@ -0,0 +1,13 @@
+# The `document` Object
+
+For [_RSpec Rails_ `request` specs](request-specs.html) the `document` object is already defined by _RSpec::HTML_ as the parsed response body.
+
+If you are testing _HTML_ in any other context, e.g. for parsing _ActionMailer_ emails, simply define `document` with a `let` or `subject` block that calls the provided `parse_html` helper:
+
+```rspec:html
+subject(:document) { parse_html(ActionMailer::Base.deliveries.last.body.decoded) }
+
+it 'contains a welcome message' do
+  expect(document.div('.welcome-message')).to match_text 'Welcome to our website!'
+end
+```

data/rspec-documentation/pages/010-Usage/020-Selectors.md

@@ -0,0 +1,45 @@
+# Selectors
+
+Each method in the chain can receive arguments to specify selectors on attributes of each element.
+
+To select an `<input>` element with a `name` attribute whose value is `email`, pass `name: 'email'` to the `input` method:
+
+## Attribute Selectors
+
+```rspec:html
+it 'renders a name field' do
+  get '/users/new'
+  expect(document.form.input(name: 'user[email]')).to exist
+end
+```
+
+## CSS Selectors
+
+Since `class` is an attribute just like `name` you can specify the exact `class` string to match elements as `document.table(class: 'table users')`:
+
+However, this test is very fragile - any change to the `class` attribute will cause the test to break, even if the order of the classes changes.
+
+Instead, you can match using _CSS_ selectors by passing a string directly to each element method:
+
+```rspec:html
+it 'renders a users table' do
+  get '/users'
+  expect(document.table('.users')).to exist
+end
+```
+
+Any valid _CSS_ selector is permitted:
+
+```rspec:html
+it 'renders a users table' do
+  get '/users'
+  expect(document.table('#users-table')).to exist
+end
+```
+
+```rspec:html
+it 'renders a users table' do
+  get '/users'
+  expect(document.table('tr td[class="name"]')).to exist
+end
+```

data/rspec-documentation/pages/010-Usage/030-Matchers/010-match_text.md

@@ -0,0 +1,27 @@
+# `match_text`
+
+The `match_text` matcher filters out any tags and compacts whitespace to make matching strings within your _HTML_ more straightforward.
+
+## Strings
+
+```rspec:html
+subject(:document) do
+  parse_html '<div>Some     <span>text</span> with   <span>whitespace</span></div>'
+end
+
+it 'matches simple strings' do
+  expect(document.div).to match_text 'Some text with whitespace'
+end
+```
+
+## Regular Expressions
+
+```rspec:html
+subject(:document) do
+  parse_html '<div>Some     <span>text</span> with   <span>whitespace</span></div>'
+end
+
+it 'matches simple strings' do
+  expect(document.div).to match_text /text.*whitespace/
+end
+```

data/rspec-documentation/pages/010-Usage/030-Matchers/020-contain_tag.md

@@ -0,0 +1,15 @@
+# `contain_tag`
+
+The `contain_tag` matcher verifies that an element exists within your document.
+
+The matcher receives a tag name as a `Symbol` and optionally receives a set of keyword arguments that refine the element definition.
+
+```rspec:html
+subject(:document) do
+  parse_html('<html><body><table><tr><td align="center">td tag</td><tr></table></body></html>')
+end
+
+it 'matches an element' do
+  expect(document.table).to contain_tag :td, align: 'center'
+end
+```

data/rspec-documentation/pages/010-Usage/030-Matchers/030-exist.md

@@ -0,0 +1,13 @@
+# `exist`
+
+The `exist` matcher verifies that a provided element specification exists in the document.
+
+```rspec:html
+subject(:document) do
+  parse_html('<html><body><div><span class="my-span">my text</span></div></body></html>')
+end
+
+it 'verifies that an element exists' do
+  expect(document.body.div.span('.my-span')).to exist
+end
+```

data/rspec-documentation/pages/010-Usage/030-Matchers/040-be_checked.md

@@ -0,0 +1,13 @@
+# `be_checked`
+
+Use the `be_checked` matcher to verify that a checkbox input is checked.
+
+```rspec:html
+subject(:document) do
+  parse_html('<form><input type="checkbox" checked></form>')
+end
+
+it 'renders a checked checkbox input' do
+  expect(document.form.input(type: 'checkbox')).to be_checked
+end
+```

data/rspec-documentation/pages/010-Usage/030-Matchers.md

@@ -0,0 +1,8 @@
+# Matchers
+
+_RSpec::HTML_ provides a selection of matchers to help you verify your _HTML_ content.
+
+* [`match_text`](matchers/match_text.html)
+* [`contain_tag`](matchers/contain_tag.html)
+* [`exist`](matchers/exist.html)
+* [`be_checked`](matchers/be_checked.html)

data/rspec-documentation/pages/010-Usage/035-Counters.md

@@ -0,0 +1,55 @@
+# Counters
+
+The [`match_text`](matchers/match_text.html) and [`contain_tag`](matchers/contain_tag.html) matchers support a counting interface to verify the number of occurrences of a given element specification within a document.
+
+The following methods can be added to a `match_text` or `contain_tag` call:
+
+* `#once`
+* `#twice`
+* `#times(n)`
+* `#at_least(:once)`, `#at_least(:twice)`, `#at_least.times(n)`
+* `#at_most(:once)`, `#at_most(:twice)`, `#at_most.times(n)`
+
+## Exact Counts
+
+```rspec:html
+subject(:document) { parse_html('<div>my div</div>') }
+
+it 'has one div' do
+  expect(document.div).to match_text('my div').once
+end
+```
+
+```rspec:html
+subject(:document) { parse_html('<div>my div</div><div>my div</div>') }
+
+it 'has one div' do
+  expect(document.div).to match_text('my div').twice
+end
+```
+
+```rspec:html
+subject(:document) { parse_html('<div>my div</div><div>my div</div><div>my div</div>') }
+
+it 'has one div' do
+  expect(document.div).to match_text('my div').times(3)
+end
+```
+
+## Minimum/Maximum Counts
+
+```rspec:html
+subject(:document) { parse_html('<div>my div</div><div>my div</div><div>my div</div>') }
+
+it 'has at least two divs' do
+  expect(document.div).to match_text('my div').at_least(:twice)
+end
+```
+
+```rspec:html
+subject(:document) { parse_html('<div>my div</div><div>my div</div><div>my div</div>') }
+
+it 'has at most three divs' do
+  expect(document.div).to match_text('my div').at_most.times(3)
+end
+```

data/rspec-documentation/pages/010-Usage/040-Attributes.md

@@ -0,0 +1,24 @@
+# Attributes
+
+If you need to verify the exact value of an attribute, use `Hash` key lookup syntax by calling `#[]`.
+
+```rspec:html
+subject(:document) do
+  parse_html('<div><input type="text" value="my-value"></div>')
+end
+
+it 'has an input whose value is "my-value"' do
+  expect(document.div.input[:value]).to eql 'my-value'
+end
+```
+
+One particular use case that makes this especially useful is retrieving an anti-CSRF token from a form before submitting a `POST` or `PATCH` request:
+
+```rspec:html
+it 'submits a user form' do
+  get '/users/new'
+  token = document.form.input(name: 'authenticity_token')[:value]
+  post '/users', params: { user: { email: 'user@example.com' }, authenticity_token: token }
+  expect(document.div('.flash.notice')).to match_text 'User successfully created'
+end
+```

data/rspec-documentation/pages/010-Usage/050-Enumerating Elements.md

@@ -0,0 +1,49 @@
+# Enumerating Elements
+
+Several interfaces exist to assist you if you need to test specifics about the number of elements that match a given element specification.
+
+## `#all`
+
+Use `#all` to retrieve all matched elements:
+
+```rspec:html
+subject(:document) { parse_html('<div>div #1</div><div>div #2</div><div>div #3</div>') }
+
+it 'retrieves all matching elements' do
+  expect(document.div.all).to all(match_text /div #[0-9]/)
+end
+```
+
+## `#[]`
+
+Use `#[]` to index a specific element from a matching set. Note that indexing starts at `1`, not `0`, so the first element in a set is `[1]`.
+
+```rspec:html
+subject(:document) { parse_html('<div>div #1</div><div>div #2</div><div>div #3</div>') }
+
+it 'retrieves all matching elements' do
+  expect(document.div[2]).to match_text 'div #2'
+end
+```
+
+You can also use `#first` or `#last` if you prefer:
+
+```rspec:html
+subject(:document) { parse_html('<div>div #1</div><div>div #2</div><div>div #3</div>') }
+
+it 'retrieves all matching elements' do
+  expect(document.div.last).to match_text 'div #3'
+end
+```
+
+## `#size`
+
+Use `#size` to verify the length of a set of matched elements:
+
+```rspec:html
+subject(:document) { parse_html('<div>div #1</div><div>div #2</div><div>div #3</div>') }
+
+it 'retrieves all matching elements' do
+  expect(document.div.size).to eql 3
+end
+```

data/rspec-documentation/pages/010-Usage/050-XPath.md

@@ -0,0 +1,13 @@
+# XPath
+
+If the provided _DOM_ navigation syntax does not provide a way for you to definitively select the required element, [_XPath_](https://developer.mozilla.org/en-US/docs/Web/XPath) is available via the `#xpath` method which delegates directly to the underlying [`Nokogiri::HTML::Document`](https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/HTML/Document) object.
+
+```rspec:html
+subject(:document) do
+  parse_html('<table><tr><td>My content</td></table>')
+end
+
+it 'matches using xpath' do
+  expect(document.xpath('//table/tr/td').text).to eql 'My content'
+end
+```

data/rspec-documentation/pages/010-Usage.md

@@ -0,0 +1,25 @@
+# Usage
+
+_RSpec::HTML_ uses method chaining to traverse the Document Object Model (_DOM_).
+
+## Implicit Navigation
+
+Access a `<td>` tag anywhere in the document:
+
+```rspec:html
+it 'renders a user name' do
+  get '/users'
+  expect(document.td('.name')).to match_text 'Example User #1'
+end
+```
+
+## Explicit Navigation
+
+Or specify the full node tree explicitly to ensure your document's structure:
+
+```rspec:html
+it 'renders a user name' do
+  get '/users'
+  expect(document.body.table.tbody.tr.td('.name')).to match_text 'Example User #1'
+end
+```

data/rspec-documentation/pages/020-Request Specs.md

@@ -0,0 +1,21 @@
+# Request Specs
+
+If you're using _RSpec_ `request` specs with _Rails_, a `document` object is available in all specs, wrapping the `response.body` of each request.
+
+```rspec:html
+it 'generates a users table' do
+  get '/users'
+  expect(document.table('.users').td('.email')).to match_text 'user@example.com'
+end
+```
+
+This is equivalent to:
+
+```rspec:html
+let(:document) { parse_html(response.body) }
+
+it 'generates a users table' do
+  get '/users'
+  expect(document.table('.users').td('.email')).to match_text 'user@example.com'
+end
+```

data/rspec-documentation/pages/030-Response Inspection.md

@@ -0,0 +1,23 @@
+# Response Inspection
+
+## Browser Inspection
+
+To make debugging a little easier, the output of the parsed document can be loaded into your operating system's default web browser by calling `document.open`.
+
+```ruby
+it 'has complex HTML' do
+  get '/my/path'
+  document.open
+end
+```
+
+## String Inspection
+
+Alternatively, the document can be printed to `stdout` by calling `puts document`.
+
+```ruby
+it 'has complex HTML' do
+  get '/my/path'
+  puts document
+end
+```

data/rspec-documentation/pages/400-Alternatives.md

@@ -0,0 +1,3 @@
+# Alternatives
+
+* [rspec-html-matchers](https://github.com/kucaahbe/rspec-html-matchers)

data/rspec-documentation/pages/500-License.md

@@ -0,0 +1,11 @@
+# License
+
+## MIT
+
+Copyright 2019-2023 Robert Farrell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/rspec-documentation/spec_helper.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'rspec/html'
+require 'rspec/file_fixtures'
+
+require 'mail'
+
+module ActionMailer
+  # Stub for ActionMailer::Base to return an example delivered email.
+  class Base
+    def self.deliveries
+      [Mail.new { body '<div class="welcome-message">Welcome to our website!</div>' }]
+    end
+  end
+end
+
+RSpec::Documentation.configure do |config|
+  config.context do
+    def get(path)
+      @response_body = fixture("html#{path}.html").read
+    end
+
+    def post(path, params:) # rubocop:disable Lint/UnusedMethodArgument
+      @response_body = fixture("html#{path}/create.html").read
+    end
+
+    def response
+      double(body: @response_body)
+    end
+
+    subject { @response_body }
+  end
+end

data/rspec-html.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   spec.executables   = []
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = '>= 2.6'
+  spec.required_ruby_version = '>= 2.7'
   spec.add_dependency 'nokogiri', '~> 1.10'
   spec.add_dependency 'rspec', '~> 3.0'
   spec.metadata['rubygems_mfa_required'] = 'true'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-html
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.4
 platform: ruby
 authors:
 - Bob Farrell
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-18 00:00:00.000000000 Z
+date: 2023-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -71,6 +71,24 @@ files:
 - lib/rspec_html/reconstituted_element.rb
 - lib/rspec_html/search.rb
 - lib/rspec_html/tags.rb
+- rspec-documentation/pages/000-Introduction.md
+- rspec-documentation/pages/010-Usage.md
+- rspec-documentation/pages/010-Usage/010-The document Object.md
+- rspec-documentation/pages/010-Usage/020-Selectors.md
+- rspec-documentation/pages/010-Usage/030-Matchers.md
+- rspec-documentation/pages/010-Usage/030-Matchers/010-match_text.md
+- rspec-documentation/pages/010-Usage/030-Matchers/020-contain_tag.md
+- rspec-documentation/pages/010-Usage/030-Matchers/030-exist.md
+- rspec-documentation/pages/010-Usage/030-Matchers/040-be_checked.md
+- rspec-documentation/pages/010-Usage/035-Counters.md
+- rspec-documentation/pages/010-Usage/040-Attributes.md
+- rspec-documentation/pages/010-Usage/050-Enumerating Elements.md
+- rspec-documentation/pages/010-Usage/050-XPath.md
+- rspec-documentation/pages/020-Request Specs.md
+- rspec-documentation/pages/030-Response Inspection.md
+- rspec-documentation/pages/400-Alternatives.md
+- rspec-documentation/pages/500-License.md
+- rspec-documentation/spec_helper.rb
 - rspec-html.gemspec
 - templates/description/contain_tag.erb
 - templates/description/match_text.erb
@@ -92,14 +110,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: RSpec HTML