Class: Applitools::Images::Eyes

Inherits:
EyesBase
  • Object
show all
Defined in:
lib/applitools/images/eyes.rb

Overview

A class to perform visual validation on images. Allows to handle user data like Mouse trigger and Text trigger

Examples:

eyes = Applitools::Images::Eyes.new
eyes.open(app_name: 'App name', test_name: 'Test name')
eyes.check_image(eyes.check_image(image_path: '~/test/some_screenshot.png', tag: 'My Test')
eyes.close(true)

Instance Method Summary collapse

Constructor Details

#initialize(server_url = Applitools::Connectivity::ServerConnector::DEFAULT_SERVER_URL) ⇒ Eyes

Creates a new eyes object

Examples:

eyes = Applitools::Images::Eyes.new

Parameters:

  • server_url (defaults to: Applitools::Connectivity::ServerConnector::DEFAULT_SERVER_URL)

    The Eyes Server URL


27
28
29
30
# File 'lib/applitools/images/eyes.rb', line 27

def initialize(server_url = Applitools::Connectivity::ServerConnector::DEFAULT_SERVER_URL)
  super
  self.base_agent_id = "eyes.images.ruby/#{Applitools::VERSION}".freeze
end

Instance Method Details

#add_mouse_trigger(action, control, cursor) ⇒ Object

Adds a mouse trigger

Parameters:

  • action (Symbol)

    A mouse action. Can be one of :click, :right_click, :double_click, :move, :down, :up

  • control (Applitools::Region)

    The control on which the trigger is activated (context relative coordinates).

  • cursor (Applitools::Location)

    The cursor's position relative to the control.


191
192
193
# File 'lib/applitools/images/eyes.rb', line 191

def add_mouse_trigger(action, control, cursor)
  add_mouse_trigger_base action, control, cursor
end

#add_text_trigger(control, text) ⇒ Object

Adds a keyboard trigger

Parameters:

  • control (Applitools::Region)

    the control's context-relative region.

  • text

    The trigger's text.


198
199
200
# File 'lib/applitools/images/eyes.rb', line 198

def add_text_trigger(control, text)
  add_text_trigger_base control, text
end

#check(name, target) ⇒ Object


63
64
65
# File 'lib/applitools/images/eyes.rb', line 63

def check(name, target)
  check_it(name, target, Applitools::MatchWindowData.new).as_expected?
end

#check_image(options) ⇒ Object

Matches the input image with the next expected image. Takes a hash as an argument. Returns boolean as result of matching.

Examples:

Image is a file

eyes.check_image(image_path: '~/test/some_screenshot.png', tag: 'My Test')

Image is a Applitools::Screenshot instance

eyes.check_image(image: my_image, tag: 'My Test')

Image is a String

eyes.check_image(image_bytes: string_represents_image, tag: 'My Test')

Ignore mismatch

eyes.check_image(image: my_image, tag: 'My Test', ignore_mismatch: true)

Parameters:

  • options (Hash)

Options Hash (options):

  • :image (Applitools::Screenshot)
  • :image_bytes (String)

    image in PNG format. Can be obtained as ChunkyPNG::Image.to_blob()

  • :image_path (String)
  • :tag (String)

    An optional tag to be associated with the validation checkpoint.

  • :ignore_mismatch (Boolean)

    If set to true the server should ignore a negative result for the visual validation. (false by default)


153
154
155
156
157
158
# File 'lib/applitools/images/eyes.rb', line 153

def check_image(options)
  options = { tag: '', ignore_mismatch: false }.merge options
  image = get_image_from_options(options)
  target = Applitools::Images::Target.any(image).ignore_mismatch(options[:ignore_mismatch])
  check(options[:tag], target)
end

#check_it(name, target, match_window_data) ⇒ Object


81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
# File 'lib/applitools/images/eyes.rb', line 81

def check_it(name, target, match_window_data)
  Applitools::ArgumentGuard.not_nil(name, 'name')
  region_provider = get_region_provider(target)

  match_window_data.tag = name
  update_default_settings(match_window_data)
  match_window_data.read_target(target, nil)

  image = target.image
  self.viewport_size = Applitools::RectangleSize.new image.width, image.height if viewport_size.nil?
  self.screenshot = EyesImagesScreenshot.new image

  if match_window_data.is_a? Applitools::MatchSingleCheckData
    return check_single_base(
      region_provider,
      target.options[:timeout] || Applitools::EyesBase::USE_DEFAULT_TIMEOUT,
      match_window_data
    )
  end

  check_window_base(
    region_provider,
    target.options[:timeout] || Applitools::EyesBase::USE_DEFAULT_TIMEOUT,
    match_window_data
  )
end

#check_region(options) ⇒ Object

Performs visual validation for the current image.

Examples:

Image is a file

eyes.check_region(image_path: '~/test/some_screenshot.png', region: my_region, tag: 'My Test')

Image is a Applitools::Screenshot instance

eyes.check_region(image: my_image, tag: 'My Test', region: my_region)

Image is a String

eyes.check_region(image_bytes: string_represents_image, tag: 'My Test', region: my_region)

Parameters:

  • options (Hash)

Options Hash (options):

  • :region (Applitools::Region)

    A region to validate within the image

  • :image (Applitools::Screenshot)

    Image to validate

  • :image_bytes (String)

    Image in PNG format. Can be obtained as ChunkyPNG::Image.to_blob()

  • :image_path (String)

    Path to image file

  • :tag (String)

    An optional tag to be associated with the validation checkpoint.

  • :ignore_mismatch (Boolean)

    If set to true the server would ignore a negative result for the visual validation


175
176
177
178
179
180
181
182
183
# File 'lib/applitools/images/eyes.rb', line 175

def check_region(options)
  options = { tag: nil, ignore_mismatch: false }.merge options
  Applitools::ArgumentGuard.not_nil options[:region], 'options[:region] can\'t be nil!'
  image = get_image_from_options options
  target = Applitools::Images::Target.any(image).ignore_mismatch(options[:ignore_mismatch])
  target.region(options[:region])
  logger.info "check_region(image, #{options[:region]}, #{options[:tag]}, #{options[:ignore_mismatch]})"
  check(options[:tag], target)
end

#check_single(name, target, options = {}) ⇒ Object


67
68
69
70
71
# File 'lib/applitools/images/eyes.rb', line 67

def check_single(name, target, options = {})
  open_and_close(name, target, options) do |n, t|
    check_it(n, t, Applitools::MatchSingleCheckData.new)
  end
end

#get_region_provider(target) ⇒ Object


108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
# File 'lib/applitools/images/eyes.rb', line 108

def get_region_provider(target)
  if (region_to_check = target.region_to_check).nil?
    Object.new.tap do |prov|
      prov.instance_eval do
        define_singleton_method :region do
          Applitools::Region::EMPTY
        end

        define_singleton_method :coordinate_type do
          nil
        end
      end
    end
  else
    Object.new.tap do |prov|
      prov.instance_eval do
        define_singleton_method :region do
          region_to_check
        end

        define_singleton_method :coordinate_type do
          Applitools::EyesScreenshot::COORDINATE_TYPES[:context_relative]
        end
      end
    end
  end
end

#open(options = {}) ⇒ Object

Starts a test.

Examples:

eyes.open app_name: 'my app', test_name: 'my test'

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :app_name (String)

    the name of the application under trest. Required.

  • :test_name (String)

    the test name. Required

  • :viewport_size (String | Hash)

    viewport size for the baseline, may be passed as a string ('800x600') or as a hash ({width: 800, height: 600}). If ommited, the viewport size will be grabbed from the actual image size


41
42
43
44
45
# File 'lib/applitools/images/eyes.rb', line 41

def open(options = {})
  Applitools::ArgumentGuard.hash options, 'open(options)', [:app_name, :test_name]
  options[:viewport_size] = Applitools::RectangleSize.from_any_argument options[:viewport_size]
  open_base options
end

#open_and_close(*args) ⇒ Object


73
74
75
76
77
78
79
# File 'lib/applitools/images/eyes.rb', line 73

def open_and_close(*args)
  options_for_open = Applitools::Utils.extract_options!(args)
  open(options_for_open)
  result = yield(*args)
  close(true, true)
  result
end

#test(options = {}, &_block) ⇒ Object

Opens eyes using passed options, yields the block and then closes eyes session. Use Applitools::Images::Eyes method inside the block to perform the test. If the block throws an exception, eyes session will be closed correctly.

Examples:

eyes.test(app_name: 'Eyes.Java', test_name: 'home2') do
  eyes.check_image(image_path: './images/viber-home.png')
  eyes.check_image(image_path: './images/viber-bada.png')
end

55
56
57
58
59
60
61
# File 'lib/applitools/images/eyes.rb', line 55

def test(options = {}, &_block)
  open(options)
  yield
  close
ensure
  abort_if_not_closed
end