eyes_selenium 6.9.0 → 6.9.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +97 -0
- data/LICENSE +26 -0
- data/README.md +658 -0
- data/eyes_selenium.gemspec +4 -2
- data/lib/applitools/eyes_selenium/version.rb +1 -1
- data/lib/applitools/selenium/browser_types.rb +0 -2
- data/lib/applitools/selenium/configuration.rb +54 -0
- data/lib/applitools/selenium/driver.rb +9 -0
- data/lib/applitools/selenium/element.rb +9 -0
- data/lib/applitools/selenium/entire_element_screenshot.rb +8 -14
- data/lib/applitools/selenium/eyes_screenshot.rb +7 -53
- data/lib/applitools/selenium/full_page_capture_algorithm.rb +2 -2
- data/lib/applitools/selenium/fullpage_screenshot.rb +8 -31
- data/lib/applitools/selenium/selenium_eyes.rb +15 -40
- data/lib/applitools/selenium/target.rb +25 -6
- data/lib/applitools/selenium/viewport_screenshot.rb +8 -40
- data/lib/eyes_selenium.rb +19 -0
- metadata +7 -5
data/README.md
ADDED
@@ -0,0 +1,658 @@
|
|
1
|
+
# Applitools Eyes Selenium SDK for Ruby
|
2
|
+
|
3
|
+
[](https://badge.fury.io/rb/eyes_selenium)
|
4
|
+
|
5
|
+
The Applitools Eyes Selenium SDK for Ruby provides comprehensive visual testing capabilities for web applications using Selenium WebDriver. Add AI-powered visual validations to your existing Selenium tests with minimal code changes.
|
6
|
+
|
7
|
+
## Table of Contents
|
8
|
+
|
9
|
+
1. [Overview](#overview)
|
10
|
+
2. [Installation](#installation)
|
11
|
+
3. [Key Components](#key-components)
|
12
|
+
- [Eyes Class](#eyes-class)
|
13
|
+
- [Target Class](#target-class)
|
14
|
+
- [Configuration Class](#configuration-class)
|
15
|
+
- [Runners](#runners)
|
16
|
+
4. [Basic Usage](#basic-usage)
|
17
|
+
- [Initializing Eyes](#initializing-eyes)
|
18
|
+
- [Configuring the SDK](#configuring-the-sdk)
|
19
|
+
- [Opening a Test](#opening-a-test)
|
20
|
+
- [Capturing Screenshots](#capturing-screenshots)
|
21
|
+
- [Closing a Test](#closing-a-test)
|
22
|
+
5. [Advanced Features](#advanced-features)
|
23
|
+
- [Check Specific Regions](#check-specific-regions)
|
24
|
+
- [Handling Frames](#handling-frames)
|
25
|
+
- [Fluent Interface](#fluent-interface)
|
26
|
+
- [Match Levels](#match-levels)
|
27
|
+
- [Ignoring Regions](#ignoring-regions)
|
28
|
+
- [Floating Regions](#floating-regions)
|
29
|
+
- [Layout, Content, and Strict Regions](#layout-content-and-strict-regions)
|
30
|
+
- [DOM Capture](#dom-capture)
|
31
|
+
6. [Visual Grid / Ultrafast Grid](#visual-grid--ultrafast-grid)
|
32
|
+
- [Configuring Visual Grid](#configuring-visual-grid)
|
33
|
+
- [Cross-Browser Testing](#cross-browser-testing)
|
34
|
+
- [Cross-Device Testing](#cross-device-testing)
|
35
|
+
7. [Best Practices](#best-practices)
|
36
|
+
8. [Troubleshooting](#troubleshooting)
|
37
|
+
9. [FAQ](#faq)
|
38
|
+
10. [Documentation](#documentation)
|
39
|
+
11. [API Reference](#api-reference)
|
40
|
+
|
41
|
+
## Overview
|
42
|
+
|
43
|
+
The Applitools Eyes Selenium SDK for Ruby seamlessly integrates visual testing into your Selenium WebDriver test automation. It captures screenshots of web pages and uses AI-powered visual comparison to detect visual changes and regressions.
|
44
|
+
|
45
|
+
### Key Features
|
46
|
+
|
47
|
+
- **Full Page Screenshots**: Automatic scrolling and stitching for complete page capture
|
48
|
+
- **Element & Region Testing**: Target specific components for precise validation
|
49
|
+
- **Frame Support**: Test content inside iframes with automatic context switching
|
50
|
+
- **Cross-Browser Testing**: Run tests across multiple browsers with Visual Grid
|
51
|
+
- **Responsive Testing**: Validate your app across different viewport sizes and devices
|
52
|
+
- **Smart Matching**: Flexible algorithms to handle dynamic content
|
53
|
+
- **DOM Capture**: Enhanced debugging with full DOM snapshots
|
54
|
+
- **Parallel Execution**: Scale your tests with the Ultrafast Grid
|
55
|
+
|
56
|
+
### Test Execution Modes
|
57
|
+
|
58
|
+
1. **Classic Runner**: Sequential execution on your local browser
|
59
|
+
2. **Visual Grid Runner**: Parallel execution across browsers in the cloud
|
60
|
+
|
61
|
+
## Installation
|
62
|
+
|
63
|
+
Add the gem to your Gemfile:
|
64
|
+
|
65
|
+
```ruby
|
66
|
+
gem 'eyes_selenium'
|
67
|
+
```
|
68
|
+
|
69
|
+
Or install it directly:
|
70
|
+
|
71
|
+
```bash
|
72
|
+
gem install eyes_selenium
|
73
|
+
```
|
74
|
+
|
75
|
+
### Dependencies
|
76
|
+
|
77
|
+
The Eyes Selenium SDK has the following dependencies:
|
78
|
+
- `eyes_core` - Core Applitools functionality
|
79
|
+
- `selenium-webdriver` (>= 3) - WebDriver implementation
|
80
|
+
- `css_parser` - CSS parsing for DOM analysis (!Deprecated)
|
81
|
+
- `crass` - CSS parsing (!Deprecated)
|
82
|
+
- `state_machines` - Internal state management (!Deprecated)
|
83
|
+
|
84
|
+
## Key Components
|
85
|
+
|
86
|
+
### Eyes Class
|
87
|
+
|
88
|
+
`Applitools::Selenium::Eyes` is the main class for interacting with the Applitools Eyes service. It provides the methods for initializing, configuring, and performing visual checks.
|
89
|
+
|
90
|
+
The Eyes class creates either a `SeleniumEyes` instance (for Classic Runner) or a `VisualGridEyes` instance (for Visual Grid), depending on the runner provided during initialization.
|
91
|
+
|
92
|
+
### Target Class
|
93
|
+
|
94
|
+
`Applitools::Selenium::Target` defines what to capture during a check operation. It provides a fluent interface for specifying:
|
95
|
+
- Full window or specific region to capture
|
96
|
+
- Frames to switch to
|
97
|
+
- Regions to ignore
|
98
|
+
- Floating regions
|
99
|
+
- Layout, content, and strict regions
|
100
|
+
|
101
|
+
### Configuration Class
|
102
|
+
|
103
|
+
`Applitools::Selenium::Configuration` manages all the settings for Eyes tests, including:
|
104
|
+
- Basic test information (app name, test name, etc.)
|
105
|
+
- Screenshot capture options
|
106
|
+
- Visual Grid browsers and devices
|
107
|
+
- Match settings
|
108
|
+
- Visual Grid options
|
109
|
+
|
110
|
+
### Runners
|
111
|
+
|
112
|
+
The SDK offers two types of test runners:
|
113
|
+
|
114
|
+
1. **Classic Runner (`Applitools::ClassicRunner`):**
|
115
|
+
- Sequential execution
|
116
|
+
- One browser at a time
|
117
|
+
- Good for simple tests and debugging
|
118
|
+
|
119
|
+
2. **Visual Grid Runner (`Applitools::Selenium::VisualGridRunner`):**
|
120
|
+
- Parallel execution
|
121
|
+
- Cross-browser and cross-device testing
|
122
|
+
- Faster execution for multiple environments
|
123
|
+
|
124
|
+
## Basic Usage
|
125
|
+
|
126
|
+
### Initializing Eyes
|
127
|
+
|
128
|
+
```ruby
|
129
|
+
require 'eyes_selenium'
|
130
|
+
|
131
|
+
# For Classic Runner (sequential execution)
|
132
|
+
runner = Applitools::ClassicRunner.new
|
133
|
+
eyes = Applitools::Selenium::Eyes.new(runner: runner)
|
134
|
+
|
135
|
+
# For Visual Grid (parallel execution)
|
136
|
+
runner = Applitools::Selenium::VisualGridRunner.new(10) # Concurrent sessions
|
137
|
+
eyes = Applitools::Selenium::Eyes.new(visual_grid_runner: runner)
|
138
|
+
|
139
|
+
# Set your API key
|
140
|
+
eyes.api_key = 'YOUR_API_KEY'
|
141
|
+
|
142
|
+
# Optional: Configure logging
|
143
|
+
eyes.log_handler = Logger.new(STDOUT)
|
144
|
+
```
|
145
|
+
|
146
|
+
### Using WebDriver Elements Directly
|
147
|
+
|
148
|
+
The SDK allows direct usage of WebDriver elements:
|
149
|
+
|
150
|
+
```ruby
|
151
|
+
# Initialize the WebDriver
|
152
|
+
driver = Selenium::WebDriver.for :chrome
|
153
|
+
|
154
|
+
# Initialize the Classic Runner
|
155
|
+
runner = Applitools::ClassicRunner.new
|
156
|
+
|
157
|
+
# Initialize Eyes with the runner
|
158
|
+
eyes = Applitools::Selenium::Eyes.new(runner: runner)
|
159
|
+
|
160
|
+
# Configure Eyes
|
161
|
+
eyes.api_key = ENV['APPLITOOLS_API_KEY']
|
162
|
+
eyes.configure do |conf|
|
163
|
+
conf.app_name = 'My Application'
|
164
|
+
conf.test_name = 'Simple Example'
|
165
|
+
conf.viewport_size = { width: 1024, height: 768 }
|
166
|
+
end
|
167
|
+
|
168
|
+
# Open Eyes using the WebDriver directly
|
169
|
+
eyes.open(driver: driver)
|
170
|
+
|
171
|
+
# Navigate to the test page
|
172
|
+
driver.get 'https://applitools.com/helloworld'
|
173
|
+
|
174
|
+
# Check the full window
|
175
|
+
target = Applitools::Selenium::Target.window
|
176
|
+
eyes.check('Hello World', target)
|
177
|
+
|
178
|
+
# Check a specific element by using the element directly
|
179
|
+
element = driver.find_element(:id, 'button')
|
180
|
+
target_with_element = Applitools::Selenium::Target.region(element)
|
181
|
+
eyes.check('Just the button', target_with_element)
|
182
|
+
```
|
183
|
+
|
184
|
+
> **Note:** While wrapper classes for WebDriver elements are still supported for backwards compatibility, it's recommended to use WebDriver elements directly as shown above.
|
185
|
+
|
186
|
+
### Configuring the SDK
|
187
|
+
|
188
|
+
```ruby
|
189
|
+
# Using configure block
|
190
|
+
eyes.configure do |conf|
|
191
|
+
conf.app_name = 'My App'
|
192
|
+
conf.test_name = 'My Test'
|
193
|
+
conf.viewport_size = { width: 1200, height: 800 }
|
194
|
+
|
195
|
+
# Screenshot settings
|
196
|
+
conf.force_full_page_screenshot = true
|
197
|
+
conf.stitch_mode = Applitools::STITCH_MODE[:css]
|
198
|
+
conf.hide_scrollbars = true
|
199
|
+
conf.wait_before_screenshots = 0.25 # seconds
|
200
|
+
|
201
|
+
# Match settings
|
202
|
+
conf.match_level = Applitools::MatchLevel::STRICT
|
203
|
+
conf.send_dom = true
|
204
|
+
end
|
205
|
+
|
206
|
+
# Or using individual setters
|
207
|
+
eyes.match_level = Applitools::MatchLevel::LAYOUT
|
208
|
+
eyes.send_dom = true
|
209
|
+
eyes.force_full_page_screenshot = true
|
210
|
+
```
|
211
|
+
|
212
|
+
### Opening a Test
|
213
|
+
|
214
|
+
```ruby
|
215
|
+
# Initialize the WebDriver
|
216
|
+
web_driver = Selenium::WebDriver.for :chrome
|
217
|
+
|
218
|
+
# Start the test
|
219
|
+
driver = eyes.open(
|
220
|
+
driver: web_driver,
|
221
|
+
app_name: 'My App',
|
222
|
+
test_name: 'My Test',
|
223
|
+
viewport_size: { width: 1200, height: 800 }
|
224
|
+
)
|
225
|
+
|
226
|
+
# Navigate to the page
|
227
|
+
driver.get('https://example.com')
|
228
|
+
```
|
229
|
+
|
230
|
+
### Capturing Screenshots
|
231
|
+
|
232
|
+
```ruby
|
233
|
+
# Check the entire window
|
234
|
+
eyes.check('Home Page', Applitools::Selenium::Target.window)
|
235
|
+
|
236
|
+
# Check the entire window, capturing full page
|
237
|
+
eyes.check('Full Page', Applitools::Selenium::Target.window.fully)
|
238
|
+
|
239
|
+
# Alternative syntax for full window check
|
240
|
+
eyes.check_window('Home Page')
|
241
|
+
```
|
242
|
+
|
243
|
+
### Closing a Test
|
244
|
+
|
245
|
+
```ruby
|
246
|
+
# End the test
|
247
|
+
results = eyes.close(false) # Pass true to raise exception on differences
|
248
|
+
|
249
|
+
# Always clean up in an ensure block
|
250
|
+
ensure
|
251
|
+
# If the test was not closed properly, abort it
|
252
|
+
eyes.abort_if_not_closed
|
253
|
+
|
254
|
+
# Close the WebDriver
|
255
|
+
web_driver.quit
|
256
|
+
|
257
|
+
# For Visual Grid, get all results and stop the runner
|
258
|
+
if runner.is_a? Applitools::Selenium::VisualGridRunner
|
259
|
+
all_results = runner.get_all_test_results
|
260
|
+
runner.stop
|
261
|
+
end
|
262
|
+
```
|
263
|
+
|
264
|
+
## Advanced Features
|
265
|
+
|
266
|
+
### Check Specific Regions
|
267
|
+
|
268
|
+
```ruby
|
269
|
+
# Check a specific element by CSS selector
|
270
|
+
eyes.check('Header', Applitools::Selenium::Target.region(:css, 'header'))
|
271
|
+
|
272
|
+
# Check a specific element by ID
|
273
|
+
eyes.check('My Element', Applitools::Selenium::Target.region(:id, 'my-element'))
|
274
|
+
|
275
|
+
# Check a region by coordinates
|
276
|
+
region = Applitools::Region.new(10, 20, 200, 100) # left, top, width, height
|
277
|
+
eyes.check('Custom Region', Applitools::Selenium::Target.region(region))
|
278
|
+
```
|
279
|
+
|
280
|
+
### Handling Frames
|
281
|
+
|
282
|
+
```ruby
|
283
|
+
# Check content inside an iframe
|
284
|
+
eyes.check('Frame Content', Applitools::Selenium::Target.frame('frame-name'))
|
285
|
+
|
286
|
+
# Check a specific element inside a frame
|
287
|
+
eyes.check('Element in Frame',
|
288
|
+
Applitools::Selenium::Target.frame('frame-name').region(:css, '.my-class')
|
289
|
+
)
|
290
|
+
|
291
|
+
# Check nested frames
|
292
|
+
eyes.check('Nested Frame Content',
|
293
|
+
Applitools::Selenium::Target.frame('parent-frame').frame('child-frame')
|
294
|
+
)
|
295
|
+
```
|
296
|
+
|
297
|
+
### Fluent Interface
|
298
|
+
|
299
|
+
The Target class provides a fluent interface for building complex check commands:
|
300
|
+
|
301
|
+
```ruby
|
302
|
+
eyes.check('Complete Check',
|
303
|
+
Applitools::Selenium::Target.window
|
304
|
+
.fully # Capture full page
|
305
|
+
.ignore(:css, '.timestamp') # Ignore dynamic content
|
306
|
+
.floating(:css, '.ad', 5, 5, 5, 5) # Floating region
|
307
|
+
.layout(:css, '.dynamic-data') # Layout region
|
308
|
+
.strict(:css, '.logo') # Strict region
|
309
|
+
.send_dom(true) # Send DOM
|
310
|
+
)
|
311
|
+
```
|
312
|
+
|
313
|
+
### Match Levels
|
314
|
+
|
315
|
+
Set different match levels to control how strict or lenient the comparison should be:
|
316
|
+
|
317
|
+
```ruby
|
318
|
+
# Global match level
|
319
|
+
eyes.match_level = Applitools::MatchLevel::LAYOUT
|
320
|
+
|
321
|
+
# Match level for a specific check
|
322
|
+
eyes.check('Layout Check',
|
323
|
+
Applitools::Selenium::Target.window.match_level(Applitools::MatchLevel::LAYOUT)
|
324
|
+
)
|
325
|
+
|
326
|
+
# Available match levels:
|
327
|
+
# - Applitools::MatchLevel::EXACT # Pixel-perfect matching
|
328
|
+
# - Applitools::MatchLevel::STRICT # Default, allows small differences
|
329
|
+
# - Applitools::MatchLevel::CONTENT # Ignores colors, checks content
|
330
|
+
# - Applitools::MatchLevel::LAYOUT # Checks only layout structure
|
331
|
+
# - Applitools::MatchLevel::NONE # No comparison, just captures screenshot
|
332
|
+
```
|
333
|
+
|
334
|
+
### Ignoring Regions
|
335
|
+
|
336
|
+
Specify regions to ignore during comparison:
|
337
|
+
|
338
|
+
```ruby
|
339
|
+
# Ignore by selector
|
340
|
+
eyes.check('Ignore Timestamp',
|
341
|
+
Applitools::Selenium::Target.window.ignore(:css, '.timestamp')
|
342
|
+
)
|
343
|
+
|
344
|
+
# Ignore multiple regions
|
345
|
+
eyes.check('Ignore Multiple',
|
346
|
+
Applitools::Selenium::Target.window
|
347
|
+
.ignore(:css, '.timestamp')
|
348
|
+
.ignore(:id, 'ad-banner')
|
349
|
+
)
|
350
|
+
|
351
|
+
# Ignore by region
|
352
|
+
region = Applitools::Region.new(10, 20, 200, 100)
|
353
|
+
eyes.check('Ignore Region', Applitools::Selenium::Target.window.ignore(region))
|
354
|
+
```
|
355
|
+
|
356
|
+
### Floating Regions
|
357
|
+
|
358
|
+
Floating regions allow elements to "float" or shift position within defined bounds:
|
359
|
+
|
360
|
+
```ruby
|
361
|
+
# Floating region by selector with offsets (left, top, right, bottom)
|
362
|
+
eyes.check('Floating Region',
|
363
|
+
Applitools::Selenium::Target.window.floating(:css, '.banner', 10, 10, 10, 10)
|
364
|
+
)
|
365
|
+
|
366
|
+
# Using FloatingBounds object
|
367
|
+
bounds = Applitools::FloatingBounds.new(10, 10, 10, 10)
|
368
|
+
eyes.check('Floating Region',
|
369
|
+
Applitools::Selenium::Target.window.floating(:css, '.banner', bounds)
|
370
|
+
)
|
371
|
+
```
|
372
|
+
|
373
|
+
### Layout, Content, and Strict Regions
|
374
|
+
|
375
|
+
Control the match level for specific regions:
|
376
|
+
|
377
|
+
```ruby
|
378
|
+
# Layout region - only structure matters, not colors or content
|
379
|
+
eyes.check('With Layout Region',
|
380
|
+
Applitools::Selenium::Target.window.layout(:css, '.dynamic-content')
|
381
|
+
)
|
382
|
+
|
383
|
+
# Content region - content matters, but not exact colors
|
384
|
+
eyes.check('With Content Region',
|
385
|
+
Applitools::Selenium::Target.window.content(:css, '.important-text')
|
386
|
+
)
|
387
|
+
|
388
|
+
# Strict region - requires closer match than global setting
|
389
|
+
eyes.check('With Strict Region',
|
390
|
+
Applitools::Selenium::Target.window.strict(:css, '.logo')
|
391
|
+
)
|
392
|
+
```
|
393
|
+
|
394
|
+
### DOM Capture
|
395
|
+
|
396
|
+
DOM capture enhances visual testing by capturing the DOM structure of the page:
|
397
|
+
|
398
|
+
```ruby
|
399
|
+
# Enable DOM capture globally
|
400
|
+
eyes.send_dom = true
|
401
|
+
|
402
|
+
# For a specific check
|
403
|
+
eyes.check('With DOM', Applitools::Selenium::Target.window.send_dom(true))
|
404
|
+
|
405
|
+
# Enable DOM-based matching
|
406
|
+
eyes.check('Use DOM', Applitools::Selenium::Target.window.use_dom(true))
|
407
|
+
```
|
408
|
+
|
409
|
+
## Visual Grid / Ultrafast Grid
|
410
|
+
|
411
|
+
Applitools Visual Grid (also called Ultrafast Grid) allows running tests on multiple browsers and devices in parallel.
|
412
|
+
|
413
|
+
### Configuring Visual Grid
|
414
|
+
|
415
|
+
```ruby
|
416
|
+
# Create Visual Grid runner
|
417
|
+
runner = Applitools::Selenium::VisualGridRunner.new(10) # Concurrent sessions
|
418
|
+
eyes = Applitools::Selenium::Eyes.new(visual_grid_runner: runner)
|
419
|
+
|
420
|
+
# Configure browsers and devices
|
421
|
+
eyes.configure do |config|
|
422
|
+
config.app_name = 'My App'
|
423
|
+
config.test_name = 'Visual Grid Test'
|
424
|
+
config.viewport_size = { width: 1200, height: 800 }
|
425
|
+
|
426
|
+
# Add desktop browsers
|
427
|
+
config.add_browser(1200, 800, Applitools::Selenium::BrowserTypes::CHROME)
|
428
|
+
config.add_browser(1200, 800, Applitools::Selenium::BrowserTypes::FIREFOX)
|
429
|
+
config.add_browser(1200, 800, Applitools::Selenium::BrowserTypes::EDGE_CHROMIUM)
|
430
|
+
|
431
|
+
# Add mobile emulation
|
432
|
+
config.add_device_emulation(Applitools::Selenium::Devices::iPhone_X,
|
433
|
+
Applitools::Selenium::Orientations::PORTRAIT)
|
434
|
+
end
|
435
|
+
```
|
436
|
+
|
437
|
+
### Cross-Browser Testing
|
438
|
+
|
439
|
+
```ruby
|
440
|
+
# Configure multiple browsers
|
441
|
+
eyes.configure do |config|
|
442
|
+
# Latest versions
|
443
|
+
config.add_browser(1200, 800, Applitools::Selenium::BrowserTypes::CHROME)
|
444
|
+
config.add_browser(1200, 800, Applitools::Selenium::BrowserTypes::FIREFOX)
|
445
|
+
config.add_browser(1200, 800, Applitools::Selenium::BrowserTypes::SAFARI)
|
446
|
+
config.add_browser(1200, 800, Applitools::Selenium::BrowserTypes::EDGE_CHROMIUM)
|
447
|
+
|
448
|
+
# Specific versions
|
449
|
+
config.add_browser(1200, 800, Applitools::Selenium::BrowserTypes::CHROME_ONE_VERSION_BACK)
|
450
|
+
config.add_browser(1200, 800, Applitools::Selenium::BrowserTypes::FIREFOX_TWO_VERSIONS_BACK)
|
451
|
+
end
|
452
|
+
```
|
453
|
+
|
454
|
+
### Cross-Device Testing
|
455
|
+
|
456
|
+
```ruby
|
457
|
+
# Configure multiple devices
|
458
|
+
eyes.configure do |config|
|
459
|
+
# iOS devices
|
460
|
+
config.add_device_emulation(Applitools::Selenium::Devices::iPhone_X,
|
461
|
+
Applitools::Selenium::Orientations::PORTRAIT)
|
462
|
+
config.add_device_emulation(Applitools::Selenium::Devices::iPad_Pro,
|
463
|
+
Applitools::Selenium::Orientations::LANDSCAPE)
|
464
|
+
|
465
|
+
# Android devices
|
466
|
+
config.add_device_emulation(Applitools::Selenium::Devices::Pixel_3,
|
467
|
+
Applitools::Selenium::Orientations::PORTRAIT)
|
468
|
+
config.add_device_emulation(Applitools::Selenium::Devices::Galaxy_S9_Plus,
|
469
|
+
Applitools::Selenium::Orientations::PORTRAIT)
|
470
|
+
end
|
471
|
+
```
|
472
|
+
|
473
|
+
## Best Practices
|
474
|
+
|
475
|
+
1. **Efficient Test Organization**
|
476
|
+
- Use descriptive app and test names
|
477
|
+
- Organize visual baselines by app/test name
|
478
|
+
- Use batch info to group related tests
|
479
|
+
|
480
|
+
2. **Optimizing Checks**
|
481
|
+
- Check specific elements when possible instead of full page
|
482
|
+
- Use appropriate match levels (layout for dynamic content)
|
483
|
+
- Define ignore regions for highly dynamic elements
|
484
|
+
- Use floating regions for elements that may shift position
|
485
|
+
|
486
|
+
3. **Working with Dynamic Content**
|
487
|
+
- Use `layout` match level for dynamic text
|
488
|
+
- Ignore regions with timestamps, counters, or random data
|
489
|
+
- Use the content match level for areas with text that changes but structure doesn't
|
490
|
+
|
491
|
+
4. **Visual Grid Optimization**
|
492
|
+
- Set an appropriate concurrency level based on your license
|
493
|
+
- Group browser configurations logically
|
494
|
+
- Prefer Visual Grid Runner for multiple browser/device tests
|
495
|
+
|
496
|
+
5. **Error Handling**
|
497
|
+
- Always call `abort_if_not_closed` in the `ensure` block
|
498
|
+
- Handle test results properly
|
499
|
+
- Close the WebDriver in the `ensure` block
|
500
|
+
|
501
|
+
## Troubleshooting
|
502
|
+
|
503
|
+
### Common Issues
|
504
|
+
|
505
|
+
1. **Authentication Errors**
|
506
|
+
- Ensure your API key is set correctly
|
507
|
+
- Check if you need a proxy configuration
|
508
|
+
|
509
|
+
2. **Screenshot Mismatches**
|
510
|
+
- Use layout match level for dynamic content
|
511
|
+
- Define ignore regions for highly dynamic elements
|
512
|
+
- Check if you need to wait longer before taking screenshots
|
513
|
+
|
514
|
+
3. **Timing Issues**
|
515
|
+
- Increase the `wait_before_screenshots` value
|
516
|
+
- Use explicit waits in your Selenium code before checks
|
517
|
+
|
518
|
+
4. **Browser Inconsistencies**
|
519
|
+
- Use specific browser versions in Visual Grid
|
520
|
+
- Consider using `force_full_page_screenshot`
|
521
|
+
- Check stitching mode (`css` vs `scroll`)
|
522
|
+
|
523
|
+
5. **Visual Grid Issues**
|
524
|
+
- Check that your license supports the number of concurrent sessions
|
525
|
+
- Ensure you're calling `runner.get_all_test_results` and `runner.stop`
|
526
|
+
|
527
|
+
### Debugging Tips
|
528
|
+
|
529
|
+
1. Enable verbose logging:
|
530
|
+
```ruby
|
531
|
+
eyes.log_handler = Logger.new(STDOUT)
|
532
|
+
eyes.log_handler.level = Logger::DEBUG
|
533
|
+
```
|
534
|
+
|
535
|
+
2. Use debug screenshots:
|
536
|
+
```ruby
|
537
|
+
eyes.debug_screenshots = true
|
538
|
+
```
|
539
|
+
|
540
|
+
3. Check test results in the Applitools dashboard for detailed information.
|
541
|
+
|
542
|
+
4. For specific Visual Grid issues, check the specific browser renderings in the dashboard.
|
543
|
+
|
544
|
+
## FAQ
|
545
|
+
|
546
|
+
**Q: What's the difference between Classic Runner and Visual Grid Runner?**
|
547
|
+
A: Classic Runner runs tests sequentially on your local browser, while Visual Grid Runner executes tests in parallel across multiple browsers and devices in the Applitools cloud.
|
548
|
+
|
549
|
+
**Q: How do I handle dynamic content that changes between test runs?**
|
550
|
+
A: You can:
|
551
|
+
- Use `layout` match level for the entire page or specific regions
|
552
|
+
- Define ignore regions for elements that frequently change
|
553
|
+
- Use floating regions for elements that may move slightly
|
554
|
+
|
555
|
+
**Q: Can I use Eyes with my existing Selenium tests?**
|
556
|
+
A: Yes, the SDK integrates seamlessly with existing Selenium WebDriver tests. You just need to create an Eyes instance, wrap your driver, and add check commands.
|
557
|
+
|
558
|
+
**Q: How do I test responsive designs?**
|
559
|
+
A: Use the Visual Grid to test your application across multiple viewport sizes and devices in parallel.
|
560
|
+
|
561
|
+
**Q: How can I exclude ads or dynamic content from comparison?**
|
562
|
+
A: Use the `ignore` method on the Target to specify regions that should be ignored during comparison:
|
563
|
+
```ruby
|
564
|
+
eyes.check('Ignore Ads', Applitools::Selenium::Target.window.ignore(:css, '.ad-container'))
|
565
|
+
```
|
566
|
+
|
567
|
+
**Q: Does the SDK support testing with iframes?**
|
568
|
+
A: Yes, use the `frame` method on the Target to test content inside iframes:
|
569
|
+
```ruby
|
570
|
+
eyes.check('Frame Content', Applitools::Selenium::Target.frame('frame-name'))
|
571
|
+
```
|
572
|
+
|
573
|
+
**Q: Can I use custom match settings for different elements on the page?**
|
574
|
+
A: Yes, you can define specific regions with different match levels in a single check:
|
575
|
+
```ruby
|
576
|
+
eyes.check('Mixed Match Levels',
|
577
|
+
Applitools::Selenium::Target.window
|
578
|
+
.layout(:css, '.dynamic-content')
|
579
|
+
.strict(:css, '.logo')
|
580
|
+
.content(:css, '.product-description')
|
581
|
+
)
|
582
|
+
```
|
583
|
+
|
584
|
+
## Documentation
|
585
|
+
|
586
|
+
For comprehensive guides and tutorials, please refer to:
|
587
|
+
|
588
|
+
- **[Selenium Ruby Quickstart Guide](https://applitools.com/tutorials/sdks/selenium-ruby/quickstart)** - Learn how to get started with Selenium WebDriver in Ruby
|
589
|
+
|
590
|
+
For API documentation and additional resources, visit:
|
591
|
+
- [Applitools Documentation Portal](https://applitools.com/docs)
|
592
|
+
- [Applitools SDK API Reference](https://applitools.com/docs/api/eyes-sdk/index-gen/classindex-ruby.html)
|
593
|
+
|
594
|
+
## API Reference
|
595
|
+
|
596
|
+
### `Applitools::Selenium::Eyes`
|
597
|
+
|
598
|
+
Core methods:
|
599
|
+
- `initialize(options)` - Creates a new Eyes instance
|
600
|
+
- `configure { |config| ... }` - Configure the SDK with a block
|
601
|
+
- `open(options)` - Starts a test
|
602
|
+
- `check(name, target)` - Performs a checkpoint
|
603
|
+
- `check_window(tag, fully)` - Performs a window checkpoint
|
604
|
+
- `check_region(how, what, options)` - Performs a region checkpoint
|
605
|
+
- `close(raise_exception)` - Closes a test
|
606
|
+
- `abort_if_not_closed` - Aborts an open test
|
607
|
+
|
608
|
+
Configuration methods:
|
609
|
+
- `force_full_page_screenshot=` - Sets full page screenshot mode
|
610
|
+
- `hide_scrollbars=` - Controls hiding scrollbars
|
611
|
+
- `stitch_mode=` - Sets the stitching mode (css or scroll)
|
612
|
+
- `match_level=` - Sets the default match level
|
613
|
+
- `set_viewport_size` - Sets the browser's viewport size
|
614
|
+
|
615
|
+
### `Applitools::Selenium::Target`
|
616
|
+
|
617
|
+
Factory methods:
|
618
|
+
- `Target.window` - Creates a target for the entire window
|
619
|
+
- `Target.region(...)` - Creates a target for a specific region
|
620
|
+
- `Target.frame(...)` - Creates a target for a frame
|
621
|
+
|
622
|
+
Instance methods:
|
623
|
+
- `fully(fully)` - Sets whether to capture the full page
|
624
|
+
- `timeout(timeout_ms)` - Sets the match timeout
|
625
|
+
- `ignore(...)` - Defines regions to ignore
|
626
|
+
- `floating(...)` - Defines floating regions
|
627
|
+
- `layout(...)` - Defines layout regions
|
628
|
+
- `content(...)` - Defines content regions
|
629
|
+
- `strict(...)` - Defines strict regions
|
630
|
+
- `match_level(match_level)` - Sets the match level for this target
|
631
|
+
- `send_dom(send_dom)` - Sets whether to send DOM with this check
|
632
|
+
- `use_dom(use_dom)` - Sets whether to use DOM for matching
|
633
|
+
|
634
|
+
### `Applitools::Selenium::Configuration`
|
635
|
+
|
636
|
+
Main methods:
|
637
|
+
- `app_name=` - Sets the application name
|
638
|
+
- `test_name=` - Sets the test name
|
639
|
+
- `viewport_size=` - Sets the viewport size
|
640
|
+
- `batch=` - Sets the batch information
|
641
|
+
- `force_full_page_screenshot=` - Controls full page screenshots
|
642
|
+
- `hide_scrollbars=` - Controls hiding scrollbars
|
643
|
+
- `stitch_mode=` - Sets the stitching mode
|
644
|
+
- `match_level=` - Sets the default match level
|
645
|
+
- `add_browser(width, height, browser_type)` - Adds a browser for Visual Grid
|
646
|
+
- `add_device_emulation(device, orientation)` - Adds a device for Visual Grid
|
647
|
+
|
648
|
+
### `Applitools::ClassicRunner` and `Applitools::Selenium::VisualGridRunner`
|
649
|
+
|
650
|
+
- `initialize(concurrency)` - Creates a new runner
|
651
|
+
- `get_all_test_results` - Gets results for all tests
|
652
|
+
- `stop` - Stops the runner (Visual Grid only)
|
653
|
+
|
654
|
+
## License
|
655
|
+
|
656
|
+
This SDK is distributed under the Applitools SDK License Agreement. See the [LICENSE](LICENSE) file for more details.
|
657
|
+
|
658
|
+
**Important:** This SDK may be used solely for your personal, non-commercial purposes. For commercial use, please contact your Applitools representative or visit [applitools.com](https://applitools.com) to obtain a commercial license.
|
data/eyes_selenium.gemspec
CHANGED
@@ -13,11 +13,13 @@ Gem::Specification.new do |spec|
|
|
13
13
|
spec.description = 'Provides SDK for writing Applitools Selenium-based tests'
|
14
14
|
spec.summary = 'Applitools Ruby Selenium SDK'
|
15
15
|
spec.homepage = 'https://www.applitools.com'
|
16
|
-
spec.license = '
|
16
|
+
spec.license = 'Proprietary'
|
17
17
|
|
18
18
|
spec.files = `git ls-files lib/applitools/selenium`.split($RS) + [
|
19
19
|
'lib/eyes_selenium.rb',
|
20
20
|
'lib/applitools/eyes_selenium/version.rb',
|
21
|
+
'LICENSE',
|
22
|
+
'README.md',
|
21
23
|
'CHANGELOG.md',
|
22
24
|
'eyes_selenium.gemspec',
|
23
25
|
'Rakefile',
|
@@ -25,7 +27,7 @@ Gem::Specification.new do |spec|
|
|
25
27
|
spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
|
26
28
|
spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
|
27
29
|
spec.require_paths = %w(lib)
|
28
|
-
spec.add_dependency 'eyes_core', "= 6.7.
|
30
|
+
spec.add_dependency 'eyes_core', "= 6.7.2"
|
29
31
|
spec.add_dependency 'selenium-webdriver', '>= 3'
|
30
32
|
spec.add_dependency 'css_parser'
|
31
33
|
spec.add_dependency 'crass'
|
@@ -23,7 +23,6 @@ module BrowserType
|
|
23
23
|
SAFARI = :'safari'
|
24
24
|
SAFARI_ONE_VERSION_BACK = :'safari-one-version-back'
|
25
25
|
SAFARI_TWO_VERSIONS_BACK = :'safari-two-versions-back'
|
26
|
-
SAFARI_EARLY_ACCESS = :'safari-earlyaccess'
|
27
26
|
IOS_SAFARI = :safari
|
28
27
|
|
29
28
|
EDGE_CHROMIUM = :'edgechromium'
|
@@ -62,7 +61,6 @@ module BrowserType
|
|
62
61
|
SAFARI,
|
63
62
|
SAFARI_ONE_VERSION_BACK,
|
64
63
|
SAFARI_TWO_VERSIONS_BACK,
|
65
|
-
SAFARI_EARLY_ACCESS,
|
66
64
|
IE_11,
|
67
65
|
EDGE_LEGACY,
|
68
66
|
IE_10,
|