govuk-rspec-helpers 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2688889ddc616f1479c43451e7cf7eb79cf2f1ea15cf56eaf2de361dfff89d51
+  data.tar.gz: 6a5b5fe732f6025d57884b152ab0898030b27c8d3fd17ab1145d14fbc8223824
+SHA512:
+  metadata.gz: 5061ab29b4267c0b87cdcb5ad862d1c60e94eaf85163c8d036cb4bd98efe8d1f628c95ccd0b6cb37b584ab23d03ae3d32b3bb942e06fbaa107dce7a14e3c3e3e
+  data.tar.gz: b613d4f0f68a69b9876cc8d19ef55ea19bcb2ae8952b1373d78a8c0b14094920f6228906c7c7a383c05d5a44ab7b72596a9c51fdc8e74753b45d5d806eb311e9

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Frankie Roberto
+
+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/README.md

@@ -0,0 +1,7 @@
+# GOV.UK RSpec Helpers
+
+This gem providers a set of helpers to make it easier to test GOV.UK services using the [RSpec](https://rspec.info) framework.
+
+This is a pre-release. Feedback is welcome.
+
+See [documentation](https://x-govuk.github.io/govuk-rspec-helpers/).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/check_govuk_checkbox.rb

@@ -0,0 +1,167 @@
+module GovukRSpecHelpers
+  class GovukCheckbox
+
+    attr_reader :page, :label_text, :hint_text
+
+    def initialize(page:, label_text:, hint_text:)
+      @label_text = label_text
+      @hint_text = hint_text
+      @page = page
+    end
+
+    def check
+      set_checked(true)
+    end
+
+    def uncheck
+      set_checked(false)
+    end
+
+    private
+
+    def set_checked(checked)
+      labels = page.all('label', text: label_text, exact_text: true, normalize_ws: true)
+
+      if labels.size == 0
+        check_for_input_id_match
+
+        raise "Unable to find label with the text \"#{label_text}\""
+      elsif labels.size > 1
+        raise "Found #{labels.size} labels with the same text. Checkbox labels should be unique within a fieldset."
+      end
+
+      @label = labels.first
+
+      check_label_has_a_for_attribute
+
+      inputs_matching_label = page.all(id: @label[:for])
+
+      if inputs_matching_label.size == 1
+        @input = inputs_matching_label.first
+      elsif inputs_matching_label.size == 0
+        raise "Found the label but it is not associated with an checkbox, did not find a checkbox with the ID \"#{@label[:for]}\"."
+      else
+        raise "Found #{inputs_matching_label.size} elements with id=\"#{@label[:for]}\". IDs must be unique."
+      end
+
+      check_input_type_is_radio
+
+      check_label_classes
+      check_input_class
+
+      hints = @label.ancestor('.govuk-checkboxes__item')
+        .all('.govuk-hint', text: hint_text, exact_text: true, normalize_ws: true)
+
+      @hint = hints.first
+
+      check_for_hint if hint_text
+      check_that_hint_is_associated_with_input if @hint
+      check_that_checkbox_not_checked if checked
+      check_that_checkbox_is_checked if !checked
+
+      @label.click
+    end
+
+    def check_for_input_id_match
+      inputs = page.all('input', id: label_text)
+
+      if inputs.size > 0
+
+        matching_labels = page.all("label[for=#{label_text}]")
+
+        if matching_labels.size > 0
+          raise "Use the full label text \"#{matching_labels.first.text}\" instead of the input ID"
+        end
+      end
+    end
+
+    def check_label_has_a_for_attribute
+      if !@label[:for]
+        raise 'Found the label but it is not associated with an checkbox, was missing a for="" attribute'
+      end
+    end
+
+    def check_input_type_is_radio
+      if @input[:type] == 'radio'
+        raise "Found the label, but it is associated with an input with type=\"#{@input[:type]}\" not a checkbox"
+      end
+    end
+
+    def check_label_classes
+      label_classes = @label[:class].to_s.split(/\s+/)
+
+      if !label_classes.include?('govuk-label') && !label_classes.include?('govuk-checkboxes__label')
+        raise "Found label but it is missing the govuk-label and govuk-checkboxes__label classes"
+      elsif !label_classes.include?('govuk-label')
+        raise "Found label but it is missing the govuk-label class"
+      elsif !label_classes.include?('govuk-checkboxes__label')
+        raise "Found label but it is missing the govuk-checkboxes__label class"
+      end
+    end
+
+    def check_input_class
+      input_classes = @input[:class].to_s.split(/\s+/)
+
+      if !input_classes.include?('govuk-checkboxes__input')
+        raise "Found checkbox but it is missing the govuk-checkboxes__input class"
+      end
+    end
+
+
+    def check_for_hint
+      if @hint.nil? || @hint.text != hint_text
+        other_hints = @label.ancestor('.govuk-checkboxes__item').all('.govuk-hint')
+
+        if other_hints.size > 0 && hint_text
+          raise "Found checkbox but could not find matching hint. Found the hint \"#{other_hints.first.text}\" instead"
+        end
+      end
+    end
+
+    def check_that_hint_is_associated_with_input
+      hint_id = @hint[:id]
+
+      if hint_id.to_s.strip == ""
+        if hint_text
+          raise "Found checkbox and hint, but the hint is not associated with the input using aria. And an ID to the hint and Add aria-describedby= to the input with that ID."
+        else
+          raise "Found checkbox, but also found a hint that is not associated with the input using aria. And an ID to the hint and Add aria-describedby= to the input with that ID."
+        end
+      end
+
+      if !@input["aria-describedby"].to_s.split(/\s+/).include?(hint_id)
+        if hint_text
+          raise "Found checkbox and hint, but the hint is not associated with the input using aria. Add aria-describedby=\"#{hint_id}\" to the input."
+        else
+          raise "Found checkbox, but also found a hint that is not associated with the input using aria. Add aria-describedby=\"#{hint_id}\" to the input."
+        end
+      end
+    end
+
+    def check_that_checkbox_not_checked
+      if @input[:checked]
+        raise "Found checkbox, but it was already checked"
+      end
+    end
+
+    def check_that_checkbox_is_checked
+      if !@input[:checked]
+        raise "Found checkbox, but it was already unchecked"
+      end
+    end
+
+  end
+
+  def check_govuk_checkbox(label_text, hint: nil)
+    GovukCheckbox.new(page: page, label_text: label_text, hint_text: hint).check
+  end
+
+  def uncheck_govuk_checkbox(label_text, hint: nil)
+    GovukCheckbox.new(page: page, label_text: label_text, hint_text: hint).uncheck
+  end
+
+  RSpec.configure do |rspec|
+    rspec.include self
+  end
+
+end

data/lib/choose_govuk_radio.rb

@@ -0,0 +1,104 @@
+module GovukRSpecHelpers
+  class ChooseGovukRadio
+
+    attr_reader :page, :label_text, :hint_text
+
+    def initialize(page:, label_text:, hint_text:)
+      @label_text = label_text
+      @hint_text = hint_text
+      @page = page
+    end
+
+    def choose
+      labels = page.all('label', text: label_text, exact_text: true, normalize_ws: true)
+
+      if labels.size == 0
+        check_for_input_id_match
+
+        raise "Unable to find label with the text \"#{label_text}\""
+      end
+
+      @label = labels.first
+
+      inputs_matching_label = page.all(id: @label[:for])
+
+      if inputs_matching_label.size == 1
+        @input = inputs_matching_label.first
+      end
+
+      check_that_fieldset_legend_was_specified
+
+      if hint_text
+        check_for_hint
+        check_that_hint_is_associated_with_input
+      end
+
+
+      @label.click
+    end
+
+    private
+
+    def check_for_input_id_match
+      inputs = page.all('input', id: label_text)
+
+      if inputs.size > 0
+
+        matching_labels = page.all("label[for=#{label_text}]")
+
+        if matching_labels.size > 0
+          raise "Use the full label text \"#{matching_labels.first.text}\" instead of the input ID"
+        end
+      end
+    end
+
+    def check_that_fieldset_legend_was_specified
+      if page.current_scope.is_a?(Capybara::Node::Document)
+
+        fieldset = @label.ancestor('fieldset')
+        legend = fieldset.find('legend')
+
+        if legend
+          raise "Specify the legend using: within_govuk_fieldset \"#{legend.text}\" do"
+        end
+      end
+    end
+
+    def check_for_hint
+      radio_item = @label.ancestor('.govuk-radios__item')
+
+      hints = radio_item.all('.govuk-hint', text: hint_text, exact_text: true, normalize_ws: true)
+
+      if hints.size == 0
+        other_hints = radio_item.all('.govuk-hint')
+
+        if other_hints.size > 0
+          raise "Found radio but could not find matching hint. Found the hint \"#{other_hints.first.text}\" instead"
+        end
+      end
+
+      @hint = hints.first
+    end
+
+    def check_that_hint_is_associated_with_input
+      hint_id = @hint[:id]
+
+      if hint_id.to_s.strip == ""
+        raise "Found radio and hint, but the hint is not associated with the input using aria. And an ID to the hint and Add aria-describedby= to the input with that ID."
+      end
+
+      if !@input["aria-describedby"].to_s.split(/\s+/).include?(hint_id)
+        raise "Found radio and hint, but the hint is not associated with the input using aria. Add aria-describedby=#{hint_id} to the input."
+      end
+    end
+  end
+
+  def choose_govuk_radio(label_text, hint: nil)
+    ChooseGovukRadio.new(page: page, label_text: label_text, hint_text: hint).choose
+  end
+
+  RSpec.configure do |rspec|
+    rspec.include self
+  end
+
+end

data/lib/click_govuk_button.rb

@@ -0,0 +1,109 @@
+module GovukRSpecHelpers
+  class ClickButton
+
+    attr_reader :page, :button_text, :disabled
+
+    def initialize(page:, button_text:, disabled: false)
+      @page = page
+      @button_text = button_text
+      @disabled = disabled
+    end
+
+    def click
+      @buttons = page.all('button', text: button_text, exact_text: true)
+
+      if @buttons.empty?
+        @buttons = page.all('a.govuk-button', text: button_text, exact_text: true)
+      end
+
+      if @buttons.empty?
+        @buttons = page.all("input[type=submit][value=\"#{Capybara::Selector::CSS.escape(button_text)}\"]")
+      end
+
+      if @buttons.size == 0
+        check_for_inexact_match
+        raise "Unable to find button \"#{button_text}\""
+      end
+
+      check_that_button_text_is_unique_on_the_page
+
+      @button = @buttons.first
+
+      check_data_module_attribute_is_present
+      check_role_is_present_if_button_is_a_link
+      check_button_is_not_draggable_if_button_is_a_link
+      check_if_button_is_disabled
+      check_for_govuk_class
+
+      @button.click unless disabled
+    end
+
+  private
+
+    def check_for_inexact_match
+      buttons_without_exact_match = page.all('button', text: button_text)
+
+      if buttons_without_exact_match.size > 0
+        raise "Unable to find button \"#{button_text}\" but did find button with the text \"#{buttons_without_exact_match.first.text}\" - include the full button text including any visually-hidden text"
+      end
+    end
+
+    def check_that_button_text_is_unique_on_the_page
+      if @buttons.size > 1
+        raise "There are #{@buttons.size} buttons with the text \"#{button_text}\" - buttons should be unique within a page"
+      end
+    end
+
+    def check_data_module_attribute_is_present
+      if @button["data-module"] != "govuk-button"
+        raise "Button is missing the data-module=\"govuk-button\" attribute"
+      end
+    end
+
+    def check_role_is_present_if_button_is_a_link
+      if @button.tag_name == 'a' && @button["role"] != "button"
+        raise "Button found, but `role=\"button\"` is missing, this is needed on links styled as buttons"
+      end
+    end
+
+    def check_button_is_not_draggable_if_button_is_a_link
+      if @button.tag_name == 'a' && @button["draggable"] != "false"
+        raise "Button found, but `draggable=\"false\"` is missing, this is needed on links styled as buttons"
+      end
+    end
+
+    def check_if_button_is_disabled
+      button_classes = @button[:class].to_s.split(/\s/).collect(&:strip)
+
+      if @button["disabled"] == "disabled" && !disabled
+        raise "Button is disabled. Avoid using disabled buttons as they have poor contrast and can confuse users. If this is unavoidable, use click_govuk_button(\"#{button_text}\", disabled: true)"
+      end
+
+      if disabled && !button_classes.include?('govuk-button--disabled')
+        raise "Disabled button is missing the govuk-button--disabled class"
+      end
+
+      if disabled && @button["aria-disabled"].to_s != "true"
+        raise 'Disabled button is missing aria-disabled="true"'
+      end
+    end
+
+    def check_for_govuk_class
+      button_classes = @button[:class].to_s.split(/\s/).collect(&:strip)
+      if button_classes.empty?
+        raise "Button is missing a class, should contain \"govuk-button\""
+      elsif !button_classes.include?('govuk-button')
+        raise "Button is missing the govuk-button class, contains #{button_classes.join(', ')}"
+      end
+    end
+
+  end
+
+  def click_govuk_button(button_text, disabled: false)
+    ClickButton.new(page: page, button_text: button_text, disabled: disabled).click
+  end
+
+  RSpec.configure do |rspec|
+    rspec.include self
+  end
+end

data/lib/click_govuk_link.rb

@@ -0,0 +1,110 @@
+module GovukRSpecHelpers
+  class ClickLink
+
+    attr_reader :link_text, :page
+
+    VALID_LINK_CLASSES = ["govuk-link", "govuk-breadcrumbs__link", "govuk-back-link", "govuk-header__link", "govuk-footer__link", "govuk-notification-banner__link", "govuk-skip-link", "govuk-tabs__tab"]
+
+    AMIBIGOUS_LINK_TEXTS = ["Change", "Add", "Remove"]
+
+    def initialize(page:, link_text:)
+      @page = page
+      @link_text = link_text
+    end
+
+    def click
+      @links = page.all('a', text: link_text, exact_text: true, normalize_ws: true)
+
+      if @links.size == 0
+        check_whether_there_is_an_inexact_match
+        check_whether_there_is_an_href_match
+        check_whether_there_is_an_id_match
+
+        raise "Unable to find link \"#{link_text}\""
+      end
+
+      check_link_text_is_unique
+      check_link_text_is_not_ambiguous
+
+      @link = @links.first
+      @link_classes = @link[:class].to_s.split(/\s/).collect(&:strip)
+
+      check_link_is_not_styled_as_button
+      check_link_warns_if_opening_in_a_new_tab
+      check_link_does_not_contain_a_button
+      check_link_has_a_valid_class
+
+      @link.click
+    end
+
+    private
+
+    def check_whether_there_is_an_inexact_match
+      links_without_exact_match = page.all('a', text: link_text)
+      if page.all('a', text: link_text).size > 0
+        raise "Unable to find link \"#{link_text}\" but did find link with the text \"#{links_without_exact_match.first.text}\" - include the full link text including any visually-hidden text"
+      end
+    end
+
+    def check_whether_there_is_an_href_match
+      links_with_href_match = page.all(:link, href: link_text)
+      if links_with_href_match.size > 0
+        raise "Use the full link text within click_govuk_link() instead of the link href"
+      end
+    end
+
+    def check_whether_there_is_an_id_match
+      links_with_id_match = page.all(:link, link_text)
+      if links_with_id_match.size > 0
+        raise "Use the full link text within click_govuk_link() instead of the link id"
+      end
+    end
+
+    def check_link_text_is_not_ambiguous
+      if AMIBIGOUS_LINK_TEXTS.include?(link_text.strip)
+        raise "The link was found, but the text \"#{link_text}\" is ambiguous if heard out of context - add some visually-hidden text"
+      end
+    end
+
+    def check_link_text_is_unique
+      if @links.size > 1
+        raise "There are #{@links.size} links with the link text \"#{link_text}\" - links should be unique within a page"
+      end
+    end
+
+    def check_link_is_not_styled_as_button
+      if @link_classes.include?('govuk-button')
+        raise "The link was found, but is styled as a button. Use `click_govuk_button` instead."
+      end
+    end
+
+    def check_link_warns_if_opening_in_a_new_tab
+      if @link[:target] == "_blank" && !link_text.include?("opens in new tab")
+        raise "The link was found, but is set to open in a new tab. Either remove this, or add \"(opens in new tab)\" to the link text"
+      end
+    end
+
+    def check_link_does_not_contain_a_button
+      if @link.all('button').any?
+        raise "The link was found, but it contains a button – use either a link or button but not both"
+      end
+    end
+
+    def check_link_has_a_valid_class
+      if @link_classes.empty?
+        raise "\"#{link_text}\" link is missing a class, should contain \"govuk-link\""
+      elsif !@link_classes.any? {|link_class| VALID_LINK_CLASSES.include?(link_class) }
+        raise "\"#{link_text}\" link is missing a govuk-link class, contains #{@link_classes.join(', ')}"
+      end
+    end
+  end
+
+  def click_govuk_link(link_text)
+    ClickLink.new(page: page, link_text: link_text).click
+  end
+
+  RSpec.configure do |rspec|
+    rspec.include self
+  end
+
+end

data/lib/fill_in_govuk_text_field.rb

@@ -0,0 +1,150 @@
+module GovukRSpecHelpers
+  class FillInGovUKTextField
+
+    attr_reader :page, :label, :hint, :with
+
+    def initialize(page:, label:, hint:, with:)
+      @page = page
+      @label = label
+      @hint = hint
+      @with = with
+    end
+
+    def fill_in
+      labels = page.all('label', text: label, exact_text: true, normalize_ws: true)
+
+      if labels.size == 0
+        check_for_inexact_label_match
+        check_for_field_name_match
+
+        raise "Unable to find label with the text #{label}"
+      end
+
+      @label = labels.first
+
+      check_label_has_a_for_attribute
+
+      label_for = @label[:for]
+      @inputs = page.all(id: label_for)
+
+      check_label_is_associated_with_a_field
+      check_there_is_only_1_element_with_the_associated_id
+
+      @input = @inputs.first
+
+      check_associated_element_is_a_form_field
+      check_input_type_is_text
+
+      aria_described_by_ids = @input["aria-describedby"].to_s.strip.split(/\s+/)
+
+      @described_by_elements = []
+
+      if aria_described_by_ids.size > 0
+        aria_described_by_ids.each do |aria_described_by_id|
+
+          check_there_is_only_one_element_with_id(aria_described_by_id)
+          @described_by_elements << page.find(id: aria_described_by_id)
+
+        end
+      end
+
+      if hint
+        check_field_is_described_by_a_hint
+        check_hint_matches_text_given
+      end
+
+      @input.set(with)
+    end
+
+    private
+
+    def check_for_inexact_label_match
+      labels_not_using_exact_match = page.all('label', text: label)
+      if labels_not_using_exact_match.size > 0
+        raise "Unable to find label with the text \"#{label}\" but did find label with the text \"#{labels_not_using_exact_match.first.text}\" - use the full label text"
+      end
+    end
+
+    def check_for_field_name_match
+      inputs_matching_name = page.all("input[name=\"#{label}\"]")
+
+      if inputs_matching_name.size > 0
+
+        input_matching_name = inputs_matching_name.first
+
+        labels = page.all("label[for=\"#{input_matching_name['id']}\"]")
+
+        if labels.size > 0
+          raise "Use the full label text \"#{labels.first.text}\" instead of the field name"
+        end
+      end
+    end
+
+    def check_label_has_a_for_attribute
+      if @label[:for].to_s.strip == ""
+        raise "Found the label but it is missing a \"for\" attribute to associate it with an input"
+      end
+    end
+
+    def check_label_is_associated_with_a_field
+      if @inputs.size == 0
+        raise "Found the label but there is no field with the ID \"#{@label[:for]}\" which matches the label‘s \"for\" attribute"
+      end
+    end
+
+    def check_there_is_only_1_element_with_the_associated_id
+      if @inputs.size > 1
+        raise "Found the label but there there are #{@inputs.size} elements with the ID \"#{@label[:for]}\" which matches the label‘s \"for\" attribute"
+      end
+    end
+
+    def check_associated_element_is_a_form_field
+      if !['input', 'textarea', 'select'].include?(@input.tag_name)
+        raise "Found the label but but it is associated with a <#{@input.tag_name}> element instead of a form field"
+      end
+    end
+
+    def check_input_type_is_text
+      raise "Found the field, but it has type=\"#{@input[:type]}\", expected type=\"text\"" unless @input[:type] == "text"
+    end
+
+    def check_field_is_described_by_a_hint
+      if @described_by_elements.size == 0
+        check_if_the_hint_exists_but_is_not_associated_with_field
+
+        raise "Found the field but could not find the hint \"#{hint}\""
+      end
+    end
+
+    def check_if_the_hint_exists_but_is_not_associated_with_field
+      if page.all('.govuk-hint', text: hint).size > 0
+        raise "Found the field and the hint, but not field is not associated with the hint using aria-describedby"
+      end
+    end
+
+    def check_hint_matches_text_given
+      hint_matching_id = @described_by_elements.find {|element| element[:class].include?("govuk-hint") }
+      if hint_matching_id.text != hint
+        raise "Found the label but the associated hint is \"#{hint_matching_id.text}\" not \"#{hint}\""
+      end
+    end
+
+    def check_there_is_only_one_element_with_id(aria_described_by_id)
+      elements_matching_id = page.all(id: aria_described_by_id)
+      if elements_matching_id.size == 0
+        raise "Found the field but it has an \"aria-describedby=#{aria_described_by_id}\" attribute and no hint with that ID exists"
+      elsif elements_matching_id.size > 1
+        raise "Found the field but it has an \"aria-describedby=#{aria_described_by_id}\" attribute and 2 elements with that ID exist"
+      end
+    end
+
+  end
+
+  def fill_in_govuk_text_field(label, hint: nil, with:)
+    FillInGovUKTextField.new(page:, label:, hint:, with:).fill_in
+  end
+
+  RSpec.configure do |rspec|
+    rspec.include self
+  end
+end

data/lib/govuk_rspec_helpers.rb

@@ -0,0 +1,13 @@
+
+require 'rspec'
+require 'capybara'
+
+require_relative 'summarise_errors_matcher'
+require_relative 'summarise_matcher'
+
+require_relative 'check_govuk_checkbox'
+require_relative 'click_govuk_link'
+require_relative 'click_govuk_button'
+require_relative 'fill_in_govuk_text_field'
+require_relative 'choose_govuk_radio'
+require_relative 'within_govuk_fieldset'

data/lib/summarise_errors_matcher.rb

@@ -0,0 +1,119 @@
+module GovukRSpecHelpers
+  module SummariseErrorsMatcher
+
+    extend RSpec::Matchers::DSL
+
+    define :summarise_errors do |expected|
+      match do |_actual|
+        title_contains_prefix &&
+        error_summary_title &&
+        expected.all? do |expected_error|
+          error_messages && error_messages[expected.index(expected_error)] == expected_error
+        end && expected.size == error_messages.size &&
+        all_error_messages_contain_links &&
+        all_error_messages_links_are_valid
+      end
+
+      failure_message do |actual|
+        missing_error = expected.find {|expected_error| !error_messages.include?(expected_error) }
+        if !title
+          "Missing <title> tag"
+        elsif !title_contains_prefix
+          "Title tag is missing the error prefix: ‘#{title}’"
+        elsif !error_summary_title
+          "Missing an error summary title"
+        elsif missing_error
+          "Missing error message: ‘#{missing_error}’"
+        elsif !all_error_messages_contain_links
+          "Error message ‘#{error_message_missing_link}’ isn’t linked to anything"
+        elsif !all_error_messages_links_are_valid
+          "Error message ‘#{error_message_with_invalid_link.text(normalize_ws: true)}’ links to ##{error_message_with_invalid_link[:href].split('#').last} but no input field has this ID or name"
+        elsif expected.size == error_messages.size
+          "Error messages appear in a different order"
+        elsif expected.size < error_messages.size
+          "An extra error message is present"
+        else
+          "Unexpected error"
+        end
+      end
+
+      def html
+        @html ||= Capybara::Node::Simple.new(actual.is_a?(String) ? actual : actual.html)
+      end
+
+      def title
+        @title ||= html.title
+      end
+
+      def title_contains_prefix
+        title.to_s.start_with?("Error: ")
+      end
+
+      def all_error_messages_contain_links
+        error_message_items.all? do |error_message_item|
+          error_message_item.all(:link).first
+        end
+      end
+
+      def all_error_messages_links_are_valid
+        error_message_items.all? do |error_message_item|
+          link = error_message_item.all(:link).first
+
+          if link
+            link_fragment = link[:href].split('#').last
+
+            link_target= html.all(id: link_fragment).first || html.all(:field, name: link_fragment).first
+
+            link_target
+          else
+            false
+          end
+        end
+      end
+
+      def error_message_with_invalid_link
+        invalid_link = error_message_links.find do |error_message_link|
+          link_fragment = error_message_link[:href].split('#').last
+
+          link_target= html.all(id: link_fragment).first || html.all(:field, name: link_fragment).first
+
+          !link_target
+        end
+      end
+
+      def error_message_missing_link
+        error_message_items.find do |error_message_item|
+          !error_message_item.all(:link).first
+        end.text(normalize_ws: true)
+      end
+
+      def error_messages
+        @error_messages ||= (error_summary_list && error_summary_list.all('li').collect {|li| li.text(normalize_ws: true) } || [])
+      end
+
+      def error_message_links
+        @error_message_links ||= error_message_items.collect {|item| item.all(:link).first }
+      end
+
+      def error_message_items
+        @error_message_items ||= (error_summary_list && error_summary_list.all('li') || [])
+      end
+
+      def error_summary_list
+        @error_summary_list ||= (error_summary && error_summary.all('.govuk-error-summary__list').first)
+      end
+
+      def error_summary_title
+        @error_summary_title ||= error_summary.all('h2.govuk-error-summary__title').first
+      end
+
+      def error_summary
+        @error_summary ||= html.all('.govuk-error-summary').first
+      end
+    end
+
+    RSpec.configure do |rspec|
+      rspec.include self
+    end
+  end
+end

data/lib/summarise_matcher.rb

@@ -0,0 +1,71 @@
+module GovukRSpecHelpers
+  module SummariseMatcher
+
+    extend RSpec::Matchers::DSL
+
+    define :summarise do |expected|
+      match do |_actual|
+        if expected[:action]
+          key_html && value_html && value_match? && action_link && action_link[:href] == expected[:action][:href]
+        else
+          key_html && value_html && value_match?
+        end
+      end
+
+      failure_message do |actual|
+        if !key_html
+          "Could not find the key ‘#{expected[:key]}’ within\n\n #{actual}"
+        elsif !value_html
+          "Could not find a <dd class=\"govuk-summary-list__value\"> element within HTML: \n#{row_html.native.to_html}"
+        elsif value_text != expected[:value]
+          "Expected ‘#{expected[:key]}’ value to be ‘#{expected[:value]}’ but was ‘#{value_text}’"
+        elsif !action_link
+          "Could not find the link ‘#{expected[:action][:text]}’ within HTML: \n#{actions_html.native.to_html}"
+        else
+          "Expected link href to be #{expected[:action][:href]}, was #{action_link[:href]}"
+        end
+      end
+
+      def html
+        @html ||= Capybara::Node::Simple.new(actual.is_a?(String) ? actual : actual.html)
+      end
+
+      def key_html
+        @key_html ||= html.all('dt.govuk-summary-list__key', exact_text: expected[:key], normalize_ws: true).first
+      end
+
+      def row_html
+        @row_html ||= key_html.ancestor('.govuk-summary-list__row')
+      end
+
+      def actions_html
+        @actions_html ||= row_html.all('dd.govuk-summary-list__actions').first
+      end
+
+      def value_html
+        @value_html ||= row_html.all('dd.govuk-summary-list__value').first
+      end
+
+      def value_text
+        @value_text ||= value_html.text(normalize_ws: true)
+      end
+
+      def action_link
+        @action_link ||= actions_html.all(:link, exact_text: expected[:action][:text], normalize_ws: true).first
+      end
+
+      def value_match?
+        if expected[:value].is_a?(Regexp)
+          value_text.match?(expected[:value])
+        else
+          value_text == expected[:value]
+        end
+      end
+    end
+
+    RSpec.configure do |rspec|
+      rspec.include self
+    end
+
+  end
+end

data/lib/within_govuk_fieldset.rb

@@ -0,0 +1,74 @@
+module GovukRSpecHelpers
+  class WithinGovukFieldset
+
+    attr_reader :page, :legend_text, :hint, :block
+
+    def initialize(page:, legend_text:, hint:, block:)
+      @legend_text = legend_text
+      @hint = hint
+      @page = page
+      @block = block
+    end
+
+    def within
+
+      legends = page.all('legend', text: legend_text, exact_text: true, normalize_ws: true)
+
+      if legends.size == 0
+        check_for_fieldset_id_match
+        raise "No fieldset found with matching legend"
+      end
+
+      legend = legends.first
+      @fieldset = legend.ancestor('fieldset')
+
+      check_hint
+
+      @page.within(@fieldset) do
+        block.call
+      end
+    end
+
+    private
+
+    def check_hint
+      if hint
+        hint_elements = @fieldset.all('.govuk-hint', text: hint, exact_text: true, normalize_ws: true)
+
+        if hint_elements.size == 0
+          raise "Count not find hint with that text"
+        end
+
+        hint_id = hint_elements.first[:id]
+
+        if !@fieldset["aria-describedby"].to_s.split(/\s+/).include?(hint_id)
+          raise "Found hint but it is not associated with the fieldset using aria-describedby"
+        end
+
+      end
+    end
+
+    def check_for_fieldset_id_match
+      matching_fieldsets = page.all("fieldset[id=#{Capybara::Selector::CSS.escape(legend_text)}]")
+
+      if matching_fieldsets.size > 0
+
+        legends = matching_fieldsets.first.all('legend')
+
+        if legends.size > 0
+          raise "Use the full legend text \"#{legends.first.text}\" instead of the fieldset ID"
+        end
+      end
+    end
+
+  end
+
+  def within_govuk_fieldset(legend_text, hint: nil, &block)
+    WithinGovukFieldset.new(page: page, legend_text: legend_text, hint: hint, block: block).within
+  end
+
+  RSpec.configure do |rspec|
+    rspec.include self
+  end
+
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: govuk-rspec-helpers
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Frankie Roberto
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-10-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.24'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.24'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ''
+email:
+- frankie@frankieroberto.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/check_govuk_checkbox.rb
+- lib/choose_govuk_radio.rb
+- lib/click_govuk_button.rb
+- lib/click_govuk_link.rb
+- lib/fill_in_govuk_text_field.rb
+- lib/govuk_rspec_helpers.rb
+- lib/summarise_errors_matcher.rb
+- lib/summarise_matcher.rb
+- lib/within_govuk_fieldset.rb
+homepage: https://x-govuk.github.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://x-govuk.github.io
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.4
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: RSpec test helpers for GOV.UK services
+test_files: []