rspec-html 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f8ba6978f02ad1d8763eb137332a30db8807af2f1f484b843cf65e41afffa5e
-  data.tar.gz: 3619e2e57b5f05c45a7f2bc6612a8e8f1a7c6ce5b8628a3be2bee9d16a2e5835
+  metadata.gz: d34bf3daf886cca4a7e1b50de449025cd6255629a1fb6a5f6d319c6353fedb0a
+  data.tar.gz: 7f3ae650fa77a60700211ccda0cb3478e034d8b14f22a40375b89ed007ecb843
 SHA512:
-  metadata.gz: df6d3216cf9bf3ea3d4db4149420aaaf9fc8ea7342bc03142b1e82cde2d71ec4f4a653b1dd94b2c3cfdeb88309b5416c5c575e5bed706d7d0b615407ff7da358
-  data.tar.gz: 18c22ee25803f0fb6f01f772e44c55b7dc2a17f02911721ccd7f56304d5b2ad7ed611eab2c38030e6a40f4cf99954087b31db61ba24cd73e0035f878f6d7e7ba
+  metadata.gz: a0ae4675dfe2790a31f953e089ce97157f6b736967abc96281eb50adc04641e1725765085be03770686dbff3c8ccd8d2fa4d567fd366edaabb74c7f2348f5e27
+  data.tar.gz: '0384ab293fe9397088d0c6356585d1c0657a443ba7a2be8ed1d6a8cdd05ada3b173adc7138091db29b4eedf0c3a267360231735fe1d9fa53144ee64f7367bf39'

data/.gitignore

@@ -12,3 +12,5 @@
 
 *.swp
 *.swo
+.byebug_history
+rspec-html-*.gem

data/.rubocop.yml

@@ -0,0 +1,51 @@
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'rspec-html.gemspec'
+
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
+Lint/DeprecatedOpenSSLConstant:
+  Enabled: true
+Lint/DuplicateElsifCondition:
+  Enabled: true
+Lint/MixedRegexpCaptureTypes:
+  Enabled: true
+Lint/RaiseException:
+  Enabled: true
+Lint/StructNewOverride:
+  Enabled: true
+Style/AccessorGrouping:
+  Enabled: true
+Style/ArrayCoercion:
+  Enabled: true
+Style/BisectedAttrAccessor:
+  Enabled: true
+Style/CaseLikeIf:
+  Enabled: true
+Style/ExponentialNotation:
+  Enabled: true
+Style/HashAsLastArrayItem:
+  Enabled: true
+Style/HashEachMethods:
+  Enabled: true
+Style/HashLikeCase:
+  Enabled: true
+Style/HashTransformKeys:
+  Enabled: true
+Style/HashTransformValues:
+  Enabled: true
+Style/RedundantAssignment:
+  Enabled: true
+Style/RedundantFetchBlock:
+  Enabled: true
+Style/RedundantFileExtensionInRequire:
+  Enabled: true
+Style/RedundantRegexpCharacterClass:
+  Enabled: true
+Style/RedundantRegexpEscape:
+  Enabled: true
+Style/SlicingWithRange:
+  Enabled: true

data/Gemfile.lock

@@ -1,66 +1,80 @@
 PATH
   remote: .
   specs:
-    rspec-html (0.1.0)
+    rspec-html (0.2.1)
+      nokogiri (~> 1.10)
       rspec (~> 3.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.0)
-    concurrent-ruby (1.1.5)
-    diff-lcs (1.3)
-    i18n (1.7.0)
+    ast (2.4.1)
+    byebug (11.1.3)
+    concurrent-ruby (1.1.6)
+    devpack (0.1.2)
+    diff-lcs (1.4.4)
+    i18n (1.8.5)
       concurrent-ruby (~> 1.0)
-    jaro_winkler (1.5.4)
-    paint (2.1.1)
-    parallel (1.19.1)
-    parser (2.6.5.0)
-      ast (~> 2.4.0)
+    mini_portile2 (2.4.0)
+    nokogiri (1.10.10)
+      mini_portile2 (~> 2.4.0)
+    paint (2.2.0)
+    parallel (1.19.2)
+    parser (2.7.1.4)
+      ast (~> 2.4.1)
     rainbow (3.0.0)
-    rake (10.5.0)
+    rake (13.0.1)
+    regexp_parser (1.7.1)
+    rexml (3.2.4)
     rspec (3.9.0)
       rspec-core (~> 3.9.0)
       rspec-expectations (~> 3.9.0)
       rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.0)
-      rspec-support (~> 3.9.0)
-    rspec-expectations (3.9.0)
+    rspec-core (3.9.2)
+      rspec-support (~> 3.9.3)
+    rspec-expectations (3.9.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.9.0)
     rspec-its (1.3.0)
       rspec-core (>= 3.0.0)
       rspec-expectations (>= 3.0.0)
-    rspec-mocks (3.9.0)
+    rspec-mocks (3.9.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.9.0)
-    rspec-support (3.9.0)
-    rubocop (0.76.0)
-      jaro_winkler (~> 1.5.1)
+    rspec-support (3.9.3)
+    rubocop (0.88.0)
       parallel (~> 1.10)
-      parser (>= 2.6)
+      parser (>= 2.7.1.1)
       rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.7)
+      rexml
+      rubocop-ast (>= 0.1.0, < 1.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 1.7)
-    rubocop-rspec (1.36.0)
-      rubocop (>= 0.68.1)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (0.2.0)
+      parser (>= 2.7.0.1)
+    rubocop-rspec (1.42.0)
+      rubocop (>= 0.87.0)
     ruby-progressbar (1.10.1)
-    strong_versions (0.3.2)
-      i18n (>= 0.5.0)
+    strong_versions (0.4.5)
+      i18n (>= 0.5)
       paint (~> 2.0)
-    unicode-display_width (1.6.0)
+    unicode-display_width (1.7.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler (~> 2.0)
-  rake (~> 10.0)
+  byebug (~> 11.0)
+  devpack (~> 0.1.2)
+  i18n (~> 1.7)
+  rake (~> 13.0)
   rspec-html!
   rspec-its (~> 1.3)
-  rubocop (~> 0.76.0)
+  rubocop (~> 0.88.0)
   rubocop-rspec (~> 1.36)
-  strong_versions (~> 0.3.2)
+  strong_versions (~> 0.4.5)
 
 BUNDLED WITH
    2.0.2

data/README.md

@@ -1,17 +1,14 @@
-# Rspec::Html
+# RSpec::HTML
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/rspec/html`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+_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).
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
 ```ruby
-gem 'rspec-html'
+gem 'rspec-html', '~> 0.2.1'
 ```
 
+Bundle
 And then execute:
 
     $ bundle
@@ -22,18 +19,90 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Require the gem in your `spec_helper.rb`:
+
+```
+# spec/spec_helper.rb
+require 'rspec/html'
+```
+
+### Object Interface
+
+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
+before { parse_html('<html><body>hello</body></html>') }
+it 'says hello' do
+  expect(document.body).to include 'hello'
+end
+```
+
+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 include '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 include 'some text'
+```
+
+#### Class Matching
+CSS classes are treated as a special case: to select an element matching a specific class (or array of classes) pass the `class` parameter:
+```ruby
+expect(document.body.div(id: 'my-div').span(class: 'my-class')).to include 'some text'
+expect(document.body.div(id: 'my-div').span(class: ['my-class', 'my-other-class'])).to include 'some text'
+```
+
+#### Attribute Retrieval
+To select an attribute from an element use the hash-style interface:
+```ruby
+expect(document.body.div.span[:class]).to include 'my-class'
+expect(document.body.div.span['data-content']).to include 'my content'
+```
+
+#### 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 include '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
+```
 
-## Development
+#### 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
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+#### 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 include 'some text'
+expect(document.body.css('span.my-class')).to include 'some text'
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+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"]'
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rspec-html.
+Feel free to make a pull request.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+[MIT License](LICENSE)

data/lib/rspec/html.rb

@@ -1,10 +1,24 @@
 # frozen_string_literal: true
 
+require 'rspec'
+require 'rspec_html'
+
 require 'rspec/html/version'
 
-module Rspec
-  module Html
-    class Error < StandardError; end
-    # Your code goes here...
+module RSpec
+  # Module extension for RSpec::SharedContext
+  module HTML
+    def document
+      @document || RSpecHTML::Element.new(Nokogiri::HTML.parse(response.body), :document)
+    end
+
+    def parse_html(content)
+      @document = RSpecHTML::Element.new(Nokogiri::HTML.parse(content), :document)
+    end
   end
 end
+
+RSpec.configure do |config|
+  config.include RSpec::HTML
+  config.backtrace_exclusion_patterns << %r{/lib/rspec/html}
+end

data/lib/rspec/html/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-module Rspec
-  module Html
-    VERSION = '0.1.0'
+module RSpec
+  module HTML
+    VERSION = '0.2.1'
   end
 end

data/lib/rspec_html.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'pathname'
+
+require 'rspec_html/nameable'
+require 'rspec_html/searchable'
+require 'rspec_html/element'
+require 'rspec_html/tags'
+
+# Support module for rspec/html
+module RSpecHTML
+  def self.root
+    Pathname.new(__dir__).parent
+  end
+end

data/lib/rspec_html/element.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RSpecHTML
+  # HTML DOM element abstraction
+  class Element
+    include Searchable
+    include Nameable
+
+    def initialize(element, name, siblings: [])
+      @name = name
+      @element = element
+      @siblings = siblings
+    end
+  end
+end

data/lib/rspec_html/nameable.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module RSpecHTML
+  # Mixin module providing methods allowing an entity to specify its name
+  module Nameable
+    attr_reader :name
+  end
+end

data/lib/rspec_html/searchable.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module RSpecHTML
+  # Mixin module providing methods for searching text content of HTML entities
+  module Searchable
+    def include?(val)
+      @element.text.include?(val)
+    end
+
+    def css(*args)
+      self.class.new(@element&.css(*args), :css)
+    end
+
+    def xpath(*args)
+      self.class.new(@element&.xpath(*args), :xpath)
+    end
+
+    def present?
+      !@element.nil?
+    end
+    alias exist? present?
+
+    # rubocop:disable Naming/PredicateName
+    def has_css?(*args)
+      !@element&.css(*args)&.empty?
+    end
+
+    def has_xpath?(*args)
+      !@element&.xpath(*args)&.empty?
+    end
+    # rubocop:enable Naming/PredicateName
+
+    def to_s
+      @element&.text&.strip
+    end
+
+    def inspect
+      %("#{@element}")
+    end
+
+    def [](val)
+      return index(val) if val.is_a?(Integer)
+      return range(val) if val.is_a?(Range)
+
+      @element&.attr(val.to_s)
+    end
+
+    def size
+      return @element.size if @element.respond_to?(:size)
+
+      @siblings.size
+    end
+    alias length size
+
+    private
+
+    def method_missing(tag, *args)
+      return super unless Tags.include?(tag)
+      return self.class.new(find(tag), tag, siblings: find(tag, all: true)) if args.empty?
+
+      self.class.new(where(tag, args.first), tag, siblings: where(tag, args.first, all: true))
+    end
+
+    def index(val)
+      zero_index_error if val.zero?
+      self.class.new(@siblings[val - 1], name)
+    end
+
+    def range(val)
+      zero_index_error if val.first.zero?
+      self.class.new(@siblings[(val.first - 1)..(val.last - 1)], :range)
+    end
+
+    def zero_index_error
+      raise ArgumentError, 'Index for matched sets starts at 1, not 0.'
+    end
+
+    def where(tag, query, all: false)
+      matched = if query[:class]
+                  where_class(tag, query[:class]) & where_xpath(tag, query.merge(class: nil))
+                else
+                  where_xpath(tag, query)
+                end
+      return matched&.first unless all
+
+      matched
+    end
+
+    def where_xpath(tag, query)
+      conditions = "[#{where_conditions(query)}]" unless query.compact.empty?
+      @element&.xpath("//#{tag}#{conditions}")
+    end
+
+    def where_conditions(query)
+      query.compact.map do |key, value|
+        next if value.nil?
+
+        %(@#{key}="#{value}")
+      end.join ' and '
+    end
+
+    def where_class(tag, class_or_classes)
+      selector = class_or_classes.is_a?(Array) ? class_or_classes.join('.') : class_or_classes
+      @element&.css("#{tag}.#{selector}")
+    end
+
+    def find(tag, all: false)
+      return @element&.css(tag.to_s)&.first unless all
+
+      @element&.css(tag.to_s)
+    end
+
+    def respond_to_missing?(method_name, *_)
+      Tags.include?(method_name)
+    end
+  end
+end

data/lib/rspec_html/tags.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RSpecHTML
+  # HTML tag identification, used to determine viability for DOM traversal via chained methods.
+  class Tags
+    def self.include?(val)
+      tags.include?(val.to_s.upcase)
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    def self.tags
+      %w[
+        A ABBR ACRONYM ADDRESS APPLET AREA ARTICLE ASIDE AUDIO B BASE BASEFONT BDI BDO BGSOUND
+        BIG BLINK BLOCKQUOTE BODY BR BUTTON CANVAS CAPTION CENTER CITE CODE COL COLGROUP COMMAND
+        CONTENT DATA DATALIST DD DEL DETAILS DFN DIALOG DIR DIV DL DT ELEMENT EM EMBED FIELDSET
+        FIGCAPTION FIGURE FONT FOOTER FORM FRAME FRAMESET H1 H2 H3 H4 H5 H6 HEAD HEADER HGROUP HR
+        HTML I IFRAME IMAGE IMG INPUT INS ISINDEX KBD KEYGEN LABEL LEGEND LI LINK LISTING MAIN
+        MAIN MAP MARK MARQUEE MENU MENUITEM META METER MULTICOL NAV NEXTID NOBR NOEMBED NOFRAMES
+        NOSCRIPT OBJECT OL OPTGROUP OPTION OUTPUT P PARAM PICTURE PLAINTEXT PRE PROGRESS Q RB RP
+        RT RTC RUBY S SAMP SCRIPT SECTION SELECT SHADOW SLOT SMALL SOURCE SPACER SPAN STRIKE
+        STRONG STYLE SUB SUMMARY SUP TABLE TBODY TD TEMPLATE TEXTAREA TFOOT TH THEAD TIME TITLE
+        TR TRACK TT U UL VAR VIDEO WBR XMP
+      ]
+    end
+    # rubocop:enable Metrics/MethodLength
+  end
+end

data/rspec-html.gemspec

@@ -6,7 +6,7 @@ require 'rspec/html/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'rspec-html'
-  spec.version       = Rspec::Html::VERSION
+  spec.version       = RSpec::HTML::VERSION
   spec.authors       = ['Bob Farrell']
   spec.email         = ['git@bob.frl']
 
@@ -28,12 +28,16 @@ Gem::Specification.new do |spec|
   spec.executables   = []
   spec.require_paths = ['lib']
 
+  spec.add_dependency 'nokogiri', '~> 1.10'
   spec.add_dependency 'rspec', '~> 3.0'
 
   spec.add_development_dependency 'bundler', '~> 2.0'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'byebug', '~> 11.0'
+  spec.add_development_dependency 'devpack', '~> 0.1.2'
+  spec.add_development_dependency 'i18n', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec-its', '~> 1.3'
-  spec.add_development_dependency 'rubocop', '~> 0.76.0'
+  spec.add_development_dependency 'rubocop', '~> 0.88.0'
   spec.add_development_dependency 'rubocop-rspec', '~> 1.36'
-  spec.add_development_dependency 'strong_versions', '~> 0.3.2'
+  spec.add_development_dependency 'strong_versions', '~> 0.4.5'
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: rspec-html
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Bob Farrell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-23 00:00:00.000000000 Z
+date: 2020-07-30 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -38,20 +52,62 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.0'
+- !ruby/object:Gem::Dependency
+  name: devpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec-its
   requirement: !ruby/object:Gem::Requirement
@@ -72,14 +128,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.76.0
+        version: 0.88.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.76.0
+        version: 0.88.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
@@ -100,14 +156,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.2
+        version: 0.4.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.2
+        version: 0.4.5
 description: HTML document abstraction and matchers for RSpec
 email:
 - git@bob.frl
@@ -117,6 +173,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - ".ruby-version"
 - ".travis.yml"
 - Gemfile
@@ -129,6 +186,11 @@ files:
 - bin/setup
 - lib/rspec/html.rb
 - lib/rspec/html/version.rb
+- lib/rspec_html.rb
+- lib/rspec_html/element.rb
+- lib/rspec_html/nameable.rb
+- lib/rspec_html/searchable.rb
+- lib/rspec_html/tags.rb
 - rspec-html.gemspec
 homepage: https://github.com/bobf/rspec-html
 licenses: