Applitools Eyes Universal SDK for Ruby

Gem Version

The eyes_universal gem provides the crucial bridge between Ruby SDKs and the Applitools Universal SDK binary. This cross-platform component ensures consistent behavior across all Applitools SDKs.

Overview

The Eyes Universal SDK is a foundational component that powers the Applitools visual testing infrastructure. It provides a platform-specific binary that handles core visual testing operations, ensuring consistent behavior across different programming languages and platforms.

Purpose

This gem serves as the integration layer between Ruby-based Applitools SDKs and the Universal SDK binary. It's automatically included as a dependency when you use any Applitools SDK for Ruby and handles:

  • Binary lifecycle management
  • Cross-platform compatibility
  • Communication protocol implementation
  • Process monitoring and error handling

Key Components

Universal Server Control

The UniversalServerControl class manages the lifecycle of the Universal SDK binary server process:

  • Starts the platform-specific executable
  • Provides communication via a socket interface
  • Manages server shutdown and cleanup

Executable Finder

The UniversalServerGemFinder module is responsible for:

  • Finding the correct binary for the current platform (Windows, macOS, Linux, etc.)
  • Supporting various CPU architectures (x86_64, ARM64, etc.)
  • Locating the binary in the gem's installation directory

Universal Binary Manager

The UniversalBinaryManager handles:

  • Extracting platform-specific binaries from the packaged tarball
  • Setting up proper permissions for the binaries
  • Managing version compatibility

Platform Support

The gem includes binaries for multiple platforms:

  • Windows (core-win.exe)
  • macOS (core-macos)
  • macOS ARM64 (core-macos-arm64)
  • Linux (core-linux)
  • Linux ARM64 (core-linux-arm64)
  • Alpine Linux (core-alpine)

Communication Protocol

The gem establishes a communication path between Ruby code and the Universal SDK binary:

  1. The binary is started as a separate process
  2. A TCP socket connection is created to communicate with the binary
  3. Commands and data are sent over this socket
  4. Results and responses are received and parsed back into Ruby objects

Usage

While this gem is not meant to be used directly by end users, it's automatically included when you use any of the Applitools SDKs for Ruby. The typical usage pattern is:

# This happens internally in eyes_selenium, eyes_images, etc.
require 'eyes_universal'

# Later, when a test session needs to be started:
server_control = Applitools::EyesUniversal::UniversalServerControl.instance
socket = server_control.new_server_socket_connection

# The socket is then used for communication with the Universal SDK

Error Handling

The gem includes robust error handling for various scenarios:

  • Binary not found for the current platform
  • Server process fails to start
  • Communication errors with the server
  • Timeouts waiting for responses

Error messages are designed to be informative and help with troubleshooting.

Environment Variables

The gem respects several environment variables:

  • APPLITOOLS_SHOW_LOGS: When set, displays detailed server logs
  • RUBY_PLATFORM: Used to determine the correct binary for the platform

Advanced Features

Proxy Support

The gem supports communication through a proxy server, which is useful in corporate environments that restrict direct internet access.

Socket Management

Multiple socket connections can be created to the same server instance, allowing parallel operations.

Server Monitoring

The gem includes a monitoring thread that detects if the server process exits unexpectedly.

FAQ

What happens if the binary is not found for my platform?

If the appropriate binary cannot be found, the gem will throw an error with detailed information about which binary it was looking for and where it searched.

Does this work on Docker/container environments?

Yes, the gem is designed to work in containerized environments, including Alpine Linux containers (using the core-alpine binary).

How is version compatibility managed between the gem and the binaries?

The binaries are packaged with each gem version, ensuring compatibility. When upgrading the gem, you automatically get the corresponding binary version.

Can I specify which binary to use manually?

While not recommended, you can override the binary selection by setting environment variables or modifying the filename method in the UniversalServerGemFinder module.

How do I debug issues with the Universal SDK binary?

Set the APPLITOOLS_SHOW_LOGS environment variable to see detailed logs from the server process, which can help diagnose issues.

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.