Module: Howdoc::Marker

Defined in:
lib/howdoc/marker.rb

Overview

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.

Constant Summary collapse

SCRIPT = 
File.read(File.expand_path('marker.js', __dir__)).freeze

Class Method Summary collapse

Class Method Details

.around(page, target, mode:) ⇒ Object

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.



28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/howdoc/marker.rb', line 28

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

.draw(page, target, mode:) ⇒ Object 



40
41
42
43
44
45
46
47
48
 
# File 'lib/howdoc/marker.rb', line 40

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

.options(mode) ⇒ Object 



50
51
52
53
54
55
56
57
 
# File 'lib/howdoc/marker.rb', line 50

def options(mode)
  {
    'mode' => mode.to_s,
    'colour' => Howdoc.config.marker_colour,
    'dim' => Howdoc.config.marker_dim,
    'size' => Howdoc.config.marker_size
  }
end