Applitools Eyes Appium SDK for Ruby

Gem Version

The Applitools Eyes Appium SDK for Ruby extends visual testing capabilities to mobile applications using Appium. This SDK enables automated visual testing for both native mobile apps and hybrid applications across iOS and Android platforms.

Table of Contents

  1. Overview
  2. Installation
  3. Key Components
  4. Basic Usage
  5. Advanced Features
  6. Best Practices
  7. Troubleshooting
  8. FAQ
  9. Documentation
  10. API Reference

Overview

The Applitools Eyes Appium SDK for Ruby extends the Eyes Selenium SDK to provide visual testing capabilities for mobile applications using Appium. It seamlessly integrates with your existing Appium test automation to add AI-powered visual validations.

Key Features

  • Cross-Platform Support: Works with both iOS and Android applications
  • Native & Hybrid Apps: Supports pure native apps and hybrid apps with WebViews
  • Automatic Platform Detection: Intelligently detects the platform and adjusts behavior accordingly
  • Region-Based Testing: Target specific UI elements for precise visual validation
  • WebView Context Handling: Seamlessly switch between native and WebView contexts
  • Mobile Native Grid Integration: Leverage cloud-based device testing for scalability

The SDK handles platform-specific complexities such as status bar heights, device pixel ratios, and screenshot capture mechanisms, allowing you to focus on writing tests rather than dealing with mobile-specific implementation details.

Installation

Add the gem to your Gemfile:

gem 'eyes_appium'

Or install it directly:

gem install eyes_appium

Dependencies

The Eyes Appium SDK has the following dependencies:

  • eyes_selenium - Core Applitools functionality for Selenium-based testing
  • appium_lib (>= 10.6.0) - Appium Ruby client
  • selenium-webdriver (>= 3, < 4.30) - WebDriver implementation

Dependency Update: The SDK has been optimized to reduce mandatory dependencies. WebDriver-related dependencies are now more flexible to improve compatibility across different environments.

Key Components

Eyes Class

Applitools::Appium::Eyes is the main class that provides the core functionality for visual testing of mobile applications. It extends Applitools::Selenium::SeleniumEyes and customizes the behavior for mobile applications.

Key features:

  • Detects the platform (iOS or Android) automatically
  • Provides native app testing capabilities
  • Handles status bar height and device pixel ratio
  • Manages different region providers based on the platform

Target Class

Applitools::Appium::Target extends the Selenium Target class to handle mobile-specific targeting. It provides methods to:

  • Target specific elements in mobile applications
  • Handle region-based checks
  • Support WebView contexts
  • Define areas to ignore, floating regions, and layout regions

Driver Class

Applitools::Appium::Driver extends Applitools::Selenium::Driver to integrate with Appium's driver. It wraps the Appium driver to provide additional functionality for visual testing.

Screenshot Handling

The SDK includes platform-specific screenshot handling for:

  • iOS devices and simulators
  • Android devices and emulators

These handle platform-specific aspects of screenshots, such as status bar height and device pixel ratio.

Basic Usage

Initializing Eyes

require 'eyes_appium'

# Initialize the Eyes SDK
eyes = Applitools::Appium::Eyes.new
eyes.api_key = 'YOUR_API_KEY'

# Optional: Configure logging
eyes.log_handler = Logger.new(STDOUT)

Opening a Test

# Define Appium capabilities
caps = {
  deviceName: 'iPhone 12',
  platformName: 'iOS',
  platformVersion: '14.5',
  app: '/path/to/your/app.ipa',
  automationName: 'XCUITest'
}

# Initialize Appium driver
appium_opts = {
  server_url: 'http://127.0.0.1:4723/wd/hub'
}
driver = Appium::Driver.new({ caps: caps, appium_lib: appium_opts }, true)
driver.start_driver

# Start the test
eyes.open(
  app_name: 'My Mobile App',
  test_name: 'Login Screen Test',
  driver: driver
)

Capturing Screenshots

Full Window Check

# Check the entire screen
eyes.check_window('Home Screen')

Region Check

# Check a specific element by accessibility ID
eyes.check('Profile Button', Applitools::Appium::Target.region(accessibility_id: 'profile_button'))

# Check a specific element by XPath
eyes.check('Login Form', Applitools::Appium::Target.region(xpath: '//android.widget.EditText'))

Configuring Match Settings

# Set the match level
eyes.match_level = Applitools::MatchLevel::LAYOUT

# Configure layout regions
target = Applitools::Appium::Target.window.layout(id: 'dynamic_content')
eyes.check('With Layout Region', target)

# Ignore regions
target = Applitools::Appium::Target.window.ignore(id: 'timestamp')
eyes.check('Ignoring Timestamp', target)

Closing a Test

# Complete the test
results = eyes.close(false)
puts "Test results: #{results.to_s}"

# Always include in a ensure block
ensure
  # If the test was not closed, abort it
  eyes.abort_if_not_closed

  # Close the Appium driver
  driver.driver_quit

Advanced Features

Handling Native and WebView Contexts

The SDK provides seamless handling of both native app contexts and WebView contexts:

# Switch to WebView context
webview_contexts = driver.available_contexts
driver.set_context(webview_contexts.find { |c| c.include?('WEBVIEW') })

# Check WebView content
eyes.check('WebView Content', Applitools::Appium::Target.window.webview)

# Switch back to native context
driver.set_context('NATIVE_APP')

# Check native content
eyes.check_window('Native Content')

Region-based Testing

For more precise testing, you can target specific UI elements:

# Check a specific element by its ID
eyes.check('Username Field', Applitools::Appium::Target.region(id: 'username_field'))

# Check an element with surrounding padding
eyes.check(
  'Password Field With Padding',
  Applitools::Appium::Target.region(
    accessibility_id: 'password_field',
    padding: { top: 10, right: 20, bottom: 10, left: 20 }
  )
)

Best Practices

  1. Proper Test Cleanup

    • Always use eyes.abort_if_not_closed in the ensure block to ensure proper cleanup even if tests fail.
    • Close the Appium driver in the ensure block to prevent resource leaks.

  2. Efficient Region Selection

    • Target specific elements when possible instead of the entire window to make tests more focused and faster.
    • Use accessibility IDs for element identification when possible (more robust than XPaths).

  3. Handle Device Rotation

    • If your app supports both portrait and landscape modes, test in both orientations.
    • Reset orientation between tests to ensure consistent starting conditions.

  4. Manage WebView vs Native Context

    • Be explicit about context switching when testing hybrid apps.
    • Use check_window for native contexts and check with Target.window.webview() for WebView contexts.

  5. Device-Specific Testing

    • Test on multiple device types and OS versions to ensure compatibility.
    • Use device-specific configurations when necessary.

  6. Error Handling

    • Use proper exception handling to catch and log Appium and Eyes exceptions separately.
    • Consider retry mechanisms for flaky mobile interactions.

Troubleshooting

Common Issues

  1. Screenshots Are Offset or Incorrectly Sized

    • Issue: Status bar height or device pixel ratio might not be correctly detected.
    • Solution: Use eyes.status_bar_height = custom_height to manually set the status bar height.

  2. Element Not Found During Checks

    • Issue: Element locators might be platform-specific or timing-related.
    • Solution: Add implicit waits or explicit waits before performing checks.

  3. Context Switching Problems

    • Issue: Cannot interact with elements after switching contexts.
    • Solution: Verify the available contexts and ensure proper switching back to the native context.

  4. Test Timeout Issues

    • Issue: Tests time out during visual comparison.
    • Solution: Increase the match timeout using eyes.match_timeout = 10000 (in milliseconds).

  5. Differences in iOS vs Android Results

    • Issue: Tests pass on one platform but fail on another.
    • Solution: Use platform-specific baselines and matching settings.

Debugging Tips

  1. Enable verbose logging:

    eyes.log_handler = Logger.new(STDOUT)
eyes.log_handler.level = Logger::DEBUG

  2. Use visual debugger by setting:

    eyes.save_debug_screenshots = true

  3. Check Appium server logs for connection or driver-related issues.

  4. Verify the device/emulator configuration matches your test capabilities.

FAQ

Q: Can I use Eyes Appium SDK with cloud-based Appium providers like Sauce Labs or BrowserStack?
A: Yes, you can use the Eyes Appium SDK with any Appium server, including cloud-based services. Just configure the appropriate server URL and capabilities.

Q: How do I handle dynamic content in my mobile app?
A: Use ignore regions for content that changes, or use the layout match level for areas with dynamic content but consistent structure.

Q: Can I test scrollable content in my mobile app?
A: Yes, but you'll need to combine Appium's scrolling capabilities with Eyes' checking. Scroll to each position and perform a check, or use the fully option with caution.

Q: Does Eyes Appium SDK work with real devices, emulators, or both?
A: The SDK works with both real devices and emulators/simulators. Real devices are recommended for more accurate visual testing.

Q: How do I handle different screen sizes and resolutions?
A: Use Applitools' responsive testing features, and consider using device-specific baselines if necessary.

Q: Can I use features like Visual Grid with mobile testing?
A: Yes, for hybrid apps with WebViews, you can use the Ultrafast Grid for the web portions. For native apps, use the Mobile Native Grid (MNG).

Documentation

For comprehensive guides and tutorials on mobile testing with Applitools, please refer to:

For API documentation and additional resources, visit:

API Reference

Applitools::Appium::Eyes

Core methods:

  • open(options) - Starts a test session
  • check(tag, target) - Performs a checkpoint
  • check_window(tag = nil, match_timeout = USE_DEFAULT_MATCH_TIMEOUT) - Performs a full window checkpoint
  • check_region(*args) - Performs a region checkpoint
  • close(throw_exception = true) - Closes a test session
  • abort_if_not_closed - Aborts an open test

Configuration methods:

  • use_system_screenshot(value = true) - Controls if system screenshots are used

Static methods:

  • set_mobile_capabilities(caps, api_key = nil, server_url = nil, proxy = nil) - Sets up MNG capabilities
  • set_nmg_capabilities - Alias for set_mobile_capabilities

Applitools::Appium::Target

  • window - Creates a target for the entire window
  • region(*args) - Creates a target for a specific region
  • ignore(*args) - Defines regions to ignore
  • floating(*args) - Defines floating regions
  • layout(*args) - Defines layout regions
  • strict(*args) - Defines strict regions
  • content(*args) - Defines content regions
  • accessibility(*args) - Defines accessibility regions
  • timeout(timeout_ms) - Sets the match timeout
  • webview(value = true) - Specifies WebView context for the check

License

This SDK is distributed under the Applitools SDK License Agreement. See the LICENSE file for more details.

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 to obtain a commercial license.