Class: Capybara::Storyboard::Session

Inherits:
Object
  • Object
show all
Defined in:
lib/capybara/storyboard/session.rb

Overview

Per-example state (sequence counter, output directory, enabled flag, example metadata) plus filename / path / sanitize derivation.

Extracting this state out of TestHelper keeps its unit tests independent of Capybara and RSpec hooks: a Session can be built with a plain example double and an injected output_root.

Instance Method Summary collapse

Constructor Details

#initialize(example:, enabled:, output_root: nil) ⇒ Session

Returns a new instance of Session.



18
19
20
21
22
23
24
25
 
# File 'lib/capybara/storyboard/session.rb', line 18

def initialize(example:, enabled:, output_root: nil)
  @example = example
  @enabled = enabled
  @output_root = output_root
  @index = 0
  @dir = nil
  @suppression_depth = 0
end

Instance Method Details

#auto(page, action, detail = nil) ⇒ Object

Automatic screenshot for a DSL action. No-op unless enabled.



32
33
34
35
36
37
38
 
# File 'lib/capybara/storyboard/session.rb', line 32

def auto(page, action, detail = nil)
  return unless @enabled
  return if suppressed?

  label = [action, sanitize(detail)].compact_blank.join('_')
  capture_with_label(page, label)
end

#auto_path(page, action, path) ⇒ Object

Automatic screenshot for a path-shaped DSL action (currently only #visit). Same as #auto except wholly-numeric path segments in the detail are collapsed to N first, so /observations/20/edit and /observations/33/edit yield one stable filename. Record ids vary between runs and between branches; a varying filename stops a visual-regression tool from pairing the two sides by path, which reports the same screen as added + deleted instead of comparing it.

Deliberately a separate entry point rather than a branch inside #auto: Session stays ignorant of which action names are path-shaped, and the caller declares it by choosing the method (as with #auto vs #manual). Locators passed to click_link/fill_in/... are human-written fixed strings, so they keep their digits and keep using #auto.

The enabled/suppressed guards are repeated here rather than left to #auto because Ruby evaluates arguments before the call: without them, every visit in a disabled suite would normalize a path only for #auto to discard it, breaking the "disabled -> zero overhead" contract.



58
59
60
61
62
63
 
# File 'lib/capybara/storyboard/session.rb', line 58

def auto_path(page, action, path)
  return unless @enabled
  return if suppressed?

  auto(page, action, normalize_path_ids(path))
end

#enabled? ⇒ Boolean

Returns:

  • (Boolean) 


27
28
29
 
# File 'lib/capybara/storyboard/session.rb', line 27

def enabled?
  @enabled
end

#manual(page, label) ⇒ Object

Manual screenshot hook. Like #auto, captured only when enabled. For an unconditional screenshot, use Capybara's own save_screenshot. The page is passed explicitly rather than held as state.



68
69
70
71
72
73
 
# File 'lib/capybara/storyboard/session.rb', line 68

def manual(page, label)
  return unless @enabled
  return if suppressed?

  capture_with_label(page, sanitize(label))
end

#suppress_captures ⇒ Object

Suppresses automatic/manual captures for the duration of the block. Used to skip nested captures while a confirm/alert dialog is open, where a screenshot or JS eval would raise UnexpectedAlertOpenError. A depth counter (not a boolean) supports nesting; the ensure guarantees reset on exceptions.



79
80
81
82
83
84
 
# File 'lib/capybara/storyboard/session.rb', line 79

def suppress_captures
  @suppression_depth += 1
  yield
ensure
  @suppression_depth -= 1
end

#suppressed? ⇒ Boolean

Returns:

  • (Boolean) 


86
87
88
 
# File 'lib/capybara/storyboard/session.rb', line 86

def suppressed?
  @suppression_depth.positive?
end