Module: Howdoc::CapybaraActions

Defined in:
lib/howdoc/capybara_actions.rb

Overview

Wraps the Capybara verbs a person would recognise as an instruction, so an ordinary test narrates itself. Include it after any other module that wraps the same verbs -- Ruby searches the most recently included module first, and each wrapper here ends in super.

Every wrapper accepts four extra options, which are removed before the call reaches Capybara:

nodoc:         leave this action out of the guide entirely
screenshot:    illustrate this action even though it normally is not
no_screenshot: do not illustrate this action even though it normally is
full_page:     capture the whole scrollable page, not one screenful

Anything the application does that Capybara has no verb for is recorded by calling Howdoc.record directly from the application's own helper.

Instance Method Summary collapse

Instance Method Details

#assert_text(locator, **options) ⇒ Object

The one assertion that is also an instruction: it is how a guide tells the reader they have arrived somewhere and what they should see there.



109
110
111
112
113
114
115
116
117
118
 
# File 'lib/howdoc/capybara_actions.rb', line 109

def assert_text(locator, **options)
  doc = Howdoc.extract_options!(options)
  result = super(locator, **options)

  narrate(
    :assert_text, doc,
    capture: true, arrival: true, text: locator, target: locator.to_s, marker_mode: :highlight
  )
  result
end

#attach_file(locator = nil, paths, make_visible: nil, **options) ⇒ Object

rubocop:disable Style/OptionalArguments



98
99
100
101
102
103
104
 
# File 'lib/howdoc/capybara_actions.rb', line 98

def attach_file(locator = nil, paths, make_visible: nil, **options)
  doc = Howdoc.extract_options!(options)

  narrate(:attach_file, doc, target: [:file_field, locator], field: howdoc_field_label(locator))

  super(locator, paths, make_visible:, **options)
end

#check(locator = nil, **options) ⇒ Object 



49
50
51
52
53
54
55
 
# File 'lib/howdoc/capybara_actions.rb', line 49

def check(locator = nil, **options)
  doc = Howdoc.extract_options!(options)

  narrate(:check, doc, target: [:checkbox, locator], field: howdoc_field_label(locator))

  super(locator, **options)
end

#choose(locator = nil, **options) ⇒ Object 



65
66
67
68
69
70
71
 
# File 'lib/howdoc/capybara_actions.rb', line 65

def choose(locator = nil, **options)
  doc = Howdoc.extract_options!(options)

  narrate(:choose, doc, target: [:radio_button, locator], field: howdoc_field_label(locator))

  super(locator, **options)
end

#click_button(locator = nil, **options) ⇒ Object 



73
74
75
76
77
78
79
 
# File 'lib/howdoc/capybara_actions.rb', line 73

def click_button(locator = nil, **options)
  doc = Howdoc.extract_options!(options)

  narrate(:click_button, doc, target: [:button, locator], locator:)

  super(locator, **options)
end

#click_link(locator = nil, **options) ⇒ Object 



81
82
83
84
85
86
87
 
# File 'lib/howdoc/capybara_actions.rb', line 81

def click_link(locator = nil, **options)
  doc = Howdoc.extract_options!(options)

  narrate(:click_link, doc, target: [:link, locator], locator:)

  super(locator, **options)
end

#click_on(locator = nil, **options) ⇒ Object 



89
90
91
92
93
94
95
 
# File 'lib/howdoc/capybara_actions.rb', line 89

def click_on(locator = nil, **options)
  doc = Howdoc.extract_options!(options)

  narrate(:click_on, doc, target: [:link_or_button, locator], locator:)

  super(locator, **options)
end

#fill_in(locator = nil, with:, currently_with: nil, fill_options: {}, **options) ⇒ Object 



30
31
32
33
34
35
36
37
38
39
 
# File 'lib/howdoc/capybara_actions.rb', line 30

def fill_in(locator = nil, with:, currently_with: nil, fill_options: {}, **options)
  doc = Howdoc.extract_options!(options)

  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

#select(value = nil, from: nil, **options) ⇒ Object 



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

def select(value = nil, from: nil, **options)
  doc = Howdoc.extract_options!(options)

  narrate(:select, doc, target: [:select, from], value:, field: howdoc_field_label(from))

  super(value, from:, **options)
end

#uncheck(locator = nil, **options) ⇒ Object 



57
58
59
60
61
62
63
 
# File 'lib/howdoc/capybara_actions.rb', line 57

def uncheck(locator = nil, **options)
  doc = Howdoc.extract_options!(options)

  narrate(:uncheck, doc, target: [:checkbox, locator], field: howdoc_field_label(locator))

  super(locator, **options)
end

#visit(visit_uri, **options) ⇒ Object 



22
23
24
25
26
27
28
 
# File 'lib/howdoc/capybara_actions.rb', line 22

def visit(visit_uri, **options)
  doc = Howdoc.extract_options!(options)
  result = super(visit_uri)

  narrate(:visit, doc, capture: true, url: displayed_url(visit_uri))
  result
end