howdoc 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 168c62956710423757404d82987844f3b33d64ebdc112f9c5c0354cd336c0944
-  data.tar.gz: 842bebc8325f407a398af4f87e050819325cdafea0d26ab568a694c91f3c765f
+  metadata.gz: 9201c07602657e340541387ddb7704ca43fcde6183ce52fd1273f036dd87513b
+  data.tar.gz: 2f9bc01470635e9d626141909f12196cb950e41e80c11077aa78943216291259
 SHA512:
-  metadata.gz: 139dfdadfe51e236abfb19bff5cb95bd28d6cb8ddd7e817b1ca9cb93362cd5cb3b9b83313544c3b9d35423f58a1385d2db807794dd2723f1e0fd4287732f34ac
-  data.tar.gz: 57d7cc5bafa03b0b103204e3a13a04015d5676445050a621cbca7b8be6e2290b01fd39bd4dd8db30377030277b66c01f57780b8462358a9a23a3b05be179159d
+  metadata.gz: c970647ba28984988f284e173b3a675123cee78b35a66a1c0ff8c5d7ed4d6ca856e41dbf3b7e8eade8a4b852121a636d86869d1f002007f5df3eba6b5c9ab10a
+  data.tar.gz: ea877687bd2a0ef1c550769f96d5cfea425ccda4f74ee1d4d71dde7575f5f473c13e97a13998d71f9958d01aa6fbeed69ca3daeb056ad0448e32f5f2ab42d3a9

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.4.0
+
+Screenshots can now show what the step is about, the way a guide made by hand
+does: an arrow on the button being pressed, a highlight around the words being
+looked for.
+
+- The marker is drawn in the browser between sizing the window and taking the
+  picture, and removed again straight after -- including when the picture could
+  not be taken, so nothing is left pointing at what has since moved.
+- An arrow's tip goes on the middle of a button, and below anything small
+  enough that the arrow would cover it.
+- A highlight measures the words themselves, through a range around the match,
+  rather than the paragraph that happens to hold them.
+- `config.illustrate_actions` illustrates every action rather than only the
+  moments a reader arrives somewhere. That is what makes the pointer worth
+  having: a picture per click, each one marked.
+- `config.marker`, `config.marker_colour`, `config.marker_dim` and
+  `config.marker_size` decide whether and how it is drawn.
+
 ## 0.3.1
 
 - The menu pass left a blank line behind every time it ran. A suite that builds

data/README.md

@@ -114,6 +114,31 @@ By default `visit` and `assert_text` are illustrated and the action verbs are
 not, on the grounds that a picture is worth showing when the reader arrives
 somewhere, not every time they press a button.
 
+## Showing where to look
+
+A screenshot of a busy page does not say which of forty things on it the step is
+about, so howdoc draws the mark a person would draw by hand:
+
+* an arrow with its tip on the button about to be pressed, on the field about to
+  be filled, on the menu about to be chosen from
+* a highlight around the words an assertion was looking for
+
+It is drawn in the browser between sizing the window and taking the picture, and
+taken off again straight after, so the page the test goes on driving is the page
+it was. There is no cursor in a headless screenshot to photograph -- the arrow is
+drawn, and its tip moves below anything too small for it to sit on without
+covering.
+
+By default only the moments a reader arrives somewhere are illustrated. A guide
+that shows every click is one line of configuration:
+
+```ruby
+config.illustrate_actions = true    # a picture per action, each one marked
+config.marker_colour = '#e11d48'    # the arrow and the highlight
+config.marker_dim = true            # dim the rest of the page around the mark
+config.marker = false               # or draw nothing at all
+```
+
 ## Your own helpers
 
 Real suites have helpers Capybara has no verb for -- a custom editor, a menu

data/lib/howdoc/capybara_actions.rb

@@ -30,7 +30,10 @@ module Howdoc
     def fill_in(locator = nil, with:, currently_with: nil, fill_options: {}, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(fill_in_action(locator), doc, field: howdoc_field_label(locator), value: with)
+      narrate(
+        fill_in_action(locator), doc,
+        target: [:fillable_field, locator], field: howdoc_field_label(locator), value: with
+      )
 
       super(locator, with:, currently_with:, fill_options:, **options)
     end
@@ -38,7 +41,7 @@ module Howdoc
     def select(value = nil, from: nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:select, doc, value:, field: howdoc_field_label(from))
+      narrate(:select, doc, target: [:select, from], value:, field: howdoc_field_label(from))
 
       super(value, from:, **options)
     end
@@ -46,7 +49,7 @@ module Howdoc
     def check(locator = nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:check, doc, field: howdoc_field_label(locator))
+      narrate(:check, doc, target: [:checkbox, locator], field: howdoc_field_label(locator))
 
       super(locator, **options)
     end
@@ -54,7 +57,7 @@ module Howdoc
     def uncheck(locator = nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:uncheck, doc, field: howdoc_field_label(locator))
+      narrate(:uncheck, doc, target: [:checkbox, locator], field: howdoc_field_label(locator))
 
       super(locator, **options)
     end
@@ -62,7 +65,7 @@ module Howdoc
     def choose(locator = nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:choose, doc, field: howdoc_field_label(locator))
+      narrate(:choose, doc, target: [:radio_button, locator], field: howdoc_field_label(locator))
 
       super(locator, **options)
     end
@@ -70,7 +73,7 @@ module Howdoc
     def click_button(locator = nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:click_button, doc, locator:)
+      narrate(:click_button, doc, target: [:button, locator], locator:)
 
       super(locator, **options)
     end
@@ -78,7 +81,7 @@ module Howdoc
     def click_link(locator = nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:click_link, doc, locator:)
+      narrate(:click_link, doc, target: [:link, locator], locator:)
 
       super(locator, **options)
     end
@@ -86,7 +89,7 @@ module Howdoc
     def click_on(locator = nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:click_on, doc, locator:)
+      narrate(:click_on, doc, target: [:link_or_button, locator], locator:)
 
       super(locator, **options)
     end
@@ -95,7 +98,7 @@ module Howdoc
     def attach_file(locator = nil, paths, make_visible: nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:attach_file, doc, field: howdoc_field_label(locator))
+      narrate(:attach_file, doc, target: [:file_field, locator], field: howdoc_field_label(locator))
 
       super(locator, paths, make_visible:, **options)
     end
@@ -107,7 +110,10 @@ module Howdoc
       doc = Howdoc.extract_options!(options)
       result = super(locator, **options)
 
-      narrate(:assert_text, doc, capture: true, arrival: true, text: locator)
+      narrate(
+        :assert_text, doc,
+        capture: true, arrival: true, text: locator, target: locator.to_s, marker_mode: :highlight
+      )
       result
     end
 
@@ -138,19 +144,48 @@ module Howdoc
       host.nil? ? visit_uri.to_s : "https://#{host}#{visit_uri}"
     end
 
-    def narrate(action, doc_options, capture: false, arrival: false, **payload)
+    def narrate(action, doc_options, capture: false, arrival: false, target: nil,
+                marker_mode: :pointer, **payload)
       step = Howdoc.record(action, arrival:, nodoc: doc_options[:nodoc], **payload)
       return nil if step.nil?
 
-      illustrate = doc_options.fetch(:screenshot, capture)
+      illustrate = doc_options.fetch(:screenshot, capture || illustrated_action?(target))
       return step unless illustrate
 
       Howdoc.capture(
         page,
         full_page: doc_options[:full_page] || false,
-        no_screenshot: doc_options[:no_screenshot] || false
+        no_screenshot: doc_options[:no_screenshot] || false,
+        marker: howdoc_marker(target), marker_mode:
       )
       step
     end
+
+    # An action is illustrated only when the application asked for every click
+    # to be shown; a picture after each button is a lot of pictures, and worth
+    # it only when they are marked.
+    def illustrated_action?(target)
+      !target.nil? && Howdoc.config.illustrate_actions?
+    end
+
+    # What the marker should point at. A string is the words an assertion was
+    # looking for, which the browser finds for itself; anything else names a
+    # Capybara selector and is resolved here, in whatever scope the test is in,
+    # exactly as the action about to happen would resolve it.
+    #
+    # Never waits: the action itself is entitled to wait, but a picture is not
+    # worth holding a suite up for, and a marker nobody could place is simply
+    # not drawn.
+    def howdoc_marker(target)
+      return nil if target.nil? || !Howdoc.config.marker?
+      return target if target.is_a?(String)
+
+      kind, locator = target
+      return nil if locator.nil?
+
+      page.find(kind, locator, match: :first, wait: 0)
+    rescue StandardError
+      nil
+    end
   end
 end

data/lib/howdoc/configuration.rb

@@ -35,6 +35,29 @@ module Howdoc
     # page, so that guides do not mix wildly different image proportions.
     attr_accessor :screenshot_height
 
+    # Whether a screenshot points at what the step is about: an arrow on the
+    # button being pressed, a highlight around the words being looked for. Off
+    # leaves the pictures exactly as the browser rendered them.
+    attr_accessor :marker
+
+    # The colour of that arrow and highlight. Red by convention, because a guide
+    # is read at a glance and red is the one colour an interface rarely uses for
+    # anything else.
+    attr_accessor :marker_colour
+
+    # Dims the rest of the page around what is marked. Emphatic, and worth it
+    # for a crowded screen; off by default because it changes every picture.
+    attr_accessor :marker_dim
+
+    # How tall the drawn pointer is, in CSS pixels.
+    attr_accessor :marker_size
+
+    # Whether an action -- a click, a choice, something typed -- is illustrated
+    # as well as narrated. Off by default: a picture belongs where the reader
+    # arrives somewhere new, not after every button. Turning it on is what makes
+    # the pointer worth having, so a guide shows every click.
+    attr_accessor :illustrate_actions
+
     # Files in the output directory that the clean task must leave alone,
     # typically hand-maintained landing pages.
     attr_accessor :preserved_files
@@ -53,19 +76,28 @@ module Howdoc
     attr_reader :locale_paths
 
     def initialize
+      reset_defaults
+      @template_paths = []
+      @locale_paths = []
+      @field_label = nil
+      @sort_key = nil
+      @group_label = nil
+    end
+
+    def reset_defaults
       @root = 'doc/howdoc'
       @enabled = false
       @host = nil
       @formats = %i[html]
       @locales = nil
       @screenshot_height = 940
+      @marker = true
+      @marker_colour = '#e11d48'
+      @marker_dim = false
+      @marker_size = 52
+      @illustrate_actions = false
       @preserved_files = %w[index.html .keep]
       @install_assets = true
-      @template_paths = []
-      @locale_paths = []
-      @field_label = nil
-      @sort_key = nil
-      @group_label = nil
     end
 
     def register_template_path(path)
@@ -105,5 +137,13 @@ module Howdoc
     def enabled?
       !!@enabled
     end
+
+    def marker?
+      !!@marker
+    end
+
+    def illustrate_actions?
+      !!@illustrate_actions
+    end
   end
 end

data/lib/howdoc/marker.js

@@ -0,0 +1,113 @@
+// Drawn over the page for as long as it takes to photograph it: an arrow on
+// what is about to be clicked, a highlight around the words that were looked
+// for. Called with no target, it takes off whatever it drew last time.
+var MARKER = 'howdoc-marker';
+var POINTER =
+  // The arrow, in a 24x32 box with its tip at 0,0 -- the shape every operating
+  // system has drawn since 1981, so a reader knows it without being told.
+  'M0 0 L0 22.6 L5.6 17.4 L9.4 25.9 L13.6 23.9 L9.8 15.7 L17.6 15.4 Z';
+
+var target = arguments[0];
+var options = arguments[1] || {};
+
+var previous = document.getElementById(MARKER);
+if (previous) { previous.parentNode.removeChild(previous); }
+if (!target) { return null; }
+
+var element = target;
+var rect = null;
+
+if (typeof target === 'string') {
+  // The words themselves, not the paragraph holding them: a range around
+  // the match measures what a reader would underline with a finger, where
+  // the element around it is as wide as the page.
+  var wanted = target.replace(/\\s+/g, ' ').trim();
+  var walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, null);
+  var node = null;
+  element = null;
+
+  while ((node = walker.nextNode())) {
+    var at = node.data.indexOf(wanted);
+    if (at === -1 || !node.parentElement || !node.parentElement.getClientRects().length) {
+      continue;
+    }
+
+    var range = document.createRange();
+    range.setStart(node, at);
+    range.setEnd(node, at + wanted.length);
+    rect = range.getBoundingClientRect();
+    element = node.parentElement;
+    break;
+  }
+}
+
+if (!element || !element.getClientRects().length) { return null; }
+if (!rect) { rect = element.getBoundingClientRect(); }
+
+// A field dressed by a widget -- select2 and its like -- leaves the real
+// <select> hidden and all but sizeless in a corner of what the reader actually
+// sees. Point at the thing on the screen: the nearest ancestor that is really
+// laid out.
+if (rect.width < 8 || rect.height < 8) {
+  var holder = element.parentElement;
+
+  while (holder && holder !== document.body) {
+    var box = holder.getBoundingClientRect();
+
+    if (box.width >= 8 && box.height >= 8) { element = holder; rect = box; break; }
+
+    holder = holder.parentElement;
+  }
+}
+var left = rect.left + window.scrollX;
+var top = rect.top + window.scrollY;
+var colour = options.colour || '#e11d48';
+var padding = 6;
+
+var layer = document.createElement('div');
+layer.id = MARKER;
+layer.style.cssText = 'position:absolute;left:0;top:0;width:0;height:0;' +
+  'z-index:2147483647;pointer-events:none;';
+
+var ring = document.createElement('div');
+ring.style.cssText = 'position:absolute;box-sizing:border-box;' +
+  'left:' + (left - padding) + 'px;top:' + (top - padding) + 'px;' +
+  'width:' + (rect.width + padding * 2) + 'px;' +
+  'height:' + (rect.height + padding * 2) + 'px;' +
+  'border:3px solid ' + colour + ';border-radius:8px;' +
+  (options.mode === 'highlight' ? 'background:' + colour + '1f;' : '') +
+  (options.dim ? 'box-shadow:0 0 0 9999px rgba(15,23,42,0.45);' : '');
+layer.appendChild(ring);
+
+if (options.mode !== 'highlight') {
+  var size = options.size || 52;
+
+  // The tip goes on the middle of a button, where a hand would put it, and a
+  // little below the middle on a field or a select: there the value is read
+  // along the top of the box, and an arrow through the middle of it sits in
+  // the way of the very thing the reader is meant to see.
+  //
+  // On something small -- a link in a table, a word in a row -- the arrow would
+  // cover what it points at whatever we do, so it hangs below instead.
+  var small = rect.width < 120 || rect.height < 32;
+  var tipLeft = left + rect.width / 2;
+  var tipTop = small ? top + rect.height - 2 : top + rect.height * 0.62;
+  var arrow = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  arrow.setAttribute('viewBox', '0 0 24 32');
+  arrow.setAttribute('width', size);
+  arrow.setAttribute('height', size * 32 / 24);
+  arrow.style.cssText = 'position:absolute;left:' + tipLeft + 'px;top:' + tipTop + 'px;' +
+    'filter:drop-shadow(0 2px 3px rgba(15,23,42,0.45));';
+
+  var path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+  path.setAttribute('d', POINTER);
+  path.setAttribute('fill', '#ffffff');
+  path.setAttribute('stroke', colour);
+  path.setAttribute('stroke-width', '2.2');
+  path.setAttribute('stroke-linejoin', 'round');
+  arrow.appendChild(path);
+  layer.appendChild(arrow);
+}
+
+document.body.appendChild(layer);
+return true;

data/lib/howdoc/marker.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Howdoc
+  # Shows the reader where to look.
+  #
+  # A screenshot of a busy page does not say which of forty things on it the
+  # step is about. A guide made by hand solves that with a red circle drawn over
+  # the button; this draws the same thing, in the browser, in the moment between
+  # the window being sized and the picture being taken -- and takes it off again
+  # afterwards, so the page the test goes on driving is the page it was.
+  #
+  # There is no cursor in a headless screenshot to photograph, so the pointer is
+  # drawn: an arrow with its tip on whatever is about to be clicked. An assertion
+  # gets no arrow, because nobody is pointing at anything -- the words the reader
+  # should see are highlighted instead.
+  #
+  # The drawing itself is JavaScript, and lives in JavaScript: marker.js beside
+  # this file. Asked to draw nothing, it takes off what it drew last time, which
+  # is how the marker is removed.
+  module Marker
+    SCRIPT = File.read(File.expand_path('marker.js', __dir__)).freeze
+
+    module_function
+
+    # Draws the marker, runs the block, and takes it off again -- including when
+    # the block raised, because a marker left behind would appear in the next
+    # picture, pointing at something that is no longer there.
+    def around(page, target, mode:)
+      return yield if target.nil? || !Howdoc.config.marker?
+
+      drawn = draw(page, target, mode:)
+
+      begin
+        yield
+      ensure
+        draw(page, nil, mode:) if drawn
+      end
+    end
+
+    def draw(page, target, mode:)
+      page.execute_script(SCRIPT, target, options(mode))
+      true
+    rescue StandardError
+      # A marker is a courtesy. A page that will not take one -- a frame gone, an
+      # element detached between finding it and drawing on it -- still has a
+      # picture worth taking.
+      false
+    end
+
+    def options(mode)
+      {
+        'mode' => mode.to_s,
+        'colour' => Howdoc.config.marker_colour,
+        'dim' => Howdoc.config.marker_dim,
+        'size' => Howdoc.config.marker_size
+      }
+    end
+  end
+end

data/lib/howdoc/recorder.rb

@@ -54,7 +54,7 @@ module Howdoc
     # Illustrates the step recorded most recently. Separate from +record+
     # because a screenshot has to be taken while the browser is still on the
     # page, whereas the sentence can be composed at any time.
-    def capture(page, full_page: false, no_screenshot: false)
+    def capture(page, full_page: false, no_screenshot: false, marker: nil, marker_mode: :pointer)
       return nil if no_screenshot || !recording?
 
       step = current.last_step || current.new_step
@@ -64,7 +64,7 @@ module Howdoc
         page,
         path: File.join(current.image_dir, filename),
         height: Howdoc.config.screenshot_height,
-        full_page:
+        full_page:, marker:, marker_mode:
       )
 
       step.screenshot = filename

data/lib/howdoc/screenshot.rb

@@ -7,7 +7,10 @@ module Howdoc
   module Screenshot
     module_function
 
-    def capture(page, path:, height:, full_page: false)
+    # The marker is drawn after the window has been sized and not before: a
+    # resize lays the page out again, and an arrow placed by the old layout
+    # would point at where the button used to be.
+    def capture(page, path:, height:, full_page: false, marker: nil, marker_mode: :pointer)
       FileUtils.mkdir_p(File.dirname(path))
 
       width, current_height = page.current_window.size
@@ -15,7 +18,10 @@ module Howdoc
 
       page.current_window.resize_to(width, target) unless target == current_height
 
-      page.save_screenshot(path, full: true)
+      Marker.around(page, marker, mode: marker_mode) do
+        page.save_screenshot(path, full: true)
+      end
+
       path
     end
 

data/lib/howdoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Howdoc
-  VERSION = '0.3.1'
+  VERSION = '0.4.0'
 end

data/lib/howdoc.rb

@@ -9,6 +9,7 @@ require_relative 'howdoc/narrator'
 require_relative 'howdoc/step'
 require_relative 'howdoc/edition'
 require_relative 'howdoc/document'
+require_relative 'howdoc/marker'
 require_relative 'howdoc/screenshot'
 require_relative 'howdoc/recorder'
 require_relative 'howdoc/templates'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howdoc
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Priit Tark
@@ -59,6 +59,8 @@ files:
 - lib/howdoc/configuration.rb
 - lib/howdoc/document.rb
 - lib/howdoc/edition.rb
+- lib/howdoc/marker.js
+- lib/howdoc/marker.rb
 - lib/howdoc/minitest.rb
 - lib/howdoc/narrator.rb
 - lib/howdoc/navigation.rb