Module: Capybara::Screenshot::Diff::TestMethods

Included in:
CapybaraScreenshotDiff::DSL
Defined in:
lib/capybara/screenshot/diff/test_methods.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#test_screenshots ⇒ Array(Array(Array(String), String, ImageCompare | Minitest::Mock))

Returns An array where each element is an array containing the caller context, the name of the screenshot, and the comparison object. This attribute stores information about each screenshot scheduled for comparison to ensure they do not show any unintended differences.

Returns:

  • (Array(Array(Array(String), String, ImageCompare | Minitest::Mock))) —

    An array where each element is an array containing the caller context, the name of the screenshot, and the comparison object. This attribute stores information about each screenshot scheduled for comparison to ensure they do not show any unintended differences.



32
33
34
35
36
37
38
 
# File 'lib/capybara/screenshot/diff/test_methods.rb', line 32

def initialize(*)
  super
  @screenshot_counter = nil
  @screenshot_group = nil
  @screenshot_section = nil
  @test_screenshot_errors = nil
end

Instance Method Details

#build_full_name(name) ⇒ String

Builds the full name for a screenshot, incorporating counters and group names for uniqueness.

Parameters:

  • name (String) —

    The base name for the screenshot.

Returns:

  • (String) —

    The full, unique name for the screenshot.



44
45
46
47
48
49
50
51
 
# File 'lib/capybara/screenshot/diff/test_methods.rb', line 44

def build_full_name(name)
  if @screenshot_counter
    name = format("%02i_#{name}", @screenshot_counter)
    @screenshot_counter += 1
  end

  File.join(*group_parts.push(name.to_s))
end

#group_parts ⇒ Object 



85
86
87
88
89
90
 
# File 'lib/capybara/screenshot/diff/test_methods.rb', line 85

def group_parts
  parts = []
  parts << @screenshot_section unless @screenshot_section.nil? || @screenshot_section.empty?
  parts << @screenshot_group unless @screenshot_group.nil? || @screenshot_group.empty?
  parts
end

#initialize ⇒ Object 



32
33
34
35
36
37
38
 
# File 'lib/capybara/screenshot/diff/test_methods.rb', line 32

def initialize(*)
  super
  @screenshot_counter = nil
  @screenshot_group = nil
  @screenshot_section = nil
  @test_screenshot_errors = nil
end

#schedule_match_job(job) ⇒ Boolean

Schedules a screenshot comparison job for later execution.

This method adds a job to the queue of screenshots to be matched. It’s used when ‘Capybara::Screenshot::Diff.delayed` is set to true, allowing for batch processing of screenshot comparisons at a later point, typically at the end of a test.

Parameters:

  • job (Array(Array(String), String, ImageCompare)) —

    The job to be scheduled, consisting of the caller context, screenshot name, and comparison object.

Returns:

  • (Boolean) —

    Always returns true, indicating the job was successfully scheduled.



80
81
82
83
 
# File 'lib/capybara/screenshot/diff/test_methods.rb', line 80

def schedule_match_job(job)
  CapybaraScreenshotDiff.add_assertion(job)
  true
end

#screenshot(name, skip_stack_frames: 0, **options) ⇒ Boolean

Takes a screenshot and optionally compares it against a baseline image.

Examples:

Capture a full-page screenshot named ‘login_page’

screenshot('login_page', skip_stack_frames: 1, full: true)

Parameters:

  • name (String) —

    The name of the screenshot, used to generate the filename.

  • skip_stack_frames (Integer) (defaults to: 0) —

    The number of stack frames to skip when reporting errors, for cleaner error messages.

  • options (Hash) —

    Additional options for taking the screenshot, such as custom dimensions or selectors.

Returns:

  • (Boolean) —

    Returns true if the screenshot was successfully captured and matches the baseline, false otherwise.

Raises:



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/capybara/screenshot/diff/test_methods.rb', line 101

def screenshot(name, skip_stack_frames: 0, **options)
  return false unless Screenshot.active?

  # setup
  screenshot_full_name = build_full_name(name)

  # exercise
  match_changes_job = build_screenshot_matches_job(screenshot_full_name, options)

  # verify
  backtrace = caller(skip_stack_frames + 1).reject { |l| l =~ /gems\/(activesupport|minitest|railties)/ }

  unless match_changes_job
    if Screenshot::Diff.fail_if_new
      _raise_error(<<-ERROR.strip_heredoc, backtrace)
        No existing screenshot found for #{screenshot_full_name}!
        To stop seeing this error disable by `Capybara::Screenshot::Diff.fail_if_new=false`
      ERROR
    end

    return false
  end

  match_changes_job.prepend(backtrace)

  if Screenshot::Diff.delayed
    schedule_match_job(match_changes_job)
  else
    invoke_match_job(match_changes_job)
  end
end

#screenshot_dir ⇒ String

Determines the directory path for saving screenshots.

Returns:

  • (String) —

    The full path to the directory where screenshots are saved.



56
57
58
 
# File 'lib/capybara/screenshot/diff/test_methods.rb', line 56

def screenshot_dir
  File.join(*([Screenshot.screenshot_area] + group_parts))
end

#screenshot_group(name) ⇒ Object 



64
65
66
67
68
69
70
71
 
# File 'lib/capybara/screenshot/diff/test_methods.rb', line 64

def screenshot_group(name)
  @screenshot_group = name.to_s
  @screenshot_counter = (@screenshot_group.nil? || @screenshot_group.empty?) ? nil : 0
  name_present = !(name.nil? || name.empty?)
  return unless Screenshot.active? && name_present

  FileUtils.rm_rf screenshot_dir
end

#screenshot_section(name) ⇒ Object 



60
61
62
 
# File 'lib/capybara/screenshot/diff/test_methods.rb', line 60

def screenshot_section(name)
  @screenshot_section = name.to_s
end