Remove support for Opera browser; update Gradle build script

In this release, I removed all implementation and documentation related to the Opera browser. The company that produces this browser has declined to publish a driver that fully supports the W3C protocol, which means that it can't be used with Selenium 4. I also removed the last vestige of support for PhantomJS.

I finally decided to resolve the deprecation warnings that Gradle would emit when executing build and test tasks. ChatGPT was very helpful in cleaning up my clunky Groovy implementation.

Remove support for the PhantomJS headless browser

In this release, I removed support for the long-abandoned PhantomJS headless browser. The owner of the project discontinued development in early 2018, and archived the project in early 2023. Consequently, it has gotten no feature updates or security fixes for many years. Given that there are several other alternative headless options, including HtmlUnit, continuing support for PhantomJS seems a bit redundant.

Fix a few windows-specific issues

This commit fixes longstanding issues with the HTTP client used to communicate with Grid servers. I was creating a generic client with no defined timeouts and infinite retries. This works fine when everything is normal, but it can lead to execution deadlocks whenever things are in a bad state.

I also fixed an issue interacting with the Appium Windows engine, which throws a generic WebDriverException instead of UnsupportedCommandException in response to driver.switchto().defaultContent().

Fix Selenium 3 regression

In this release, I fixed a recent regression in support for Selenium 3.

Fix issue targeting Macintosh native applications on Selenium 3

In this release, I fixed a minor issue that affected tests that target native Macintosh applications with Appium and Selenium 3.

Fix issues running on native platforms

In this release, I fixed a few minor issues that were causing execution on Appium native platforms to fail.

Upgrade to Selenium 4.40.0; add comprehensive documentation for new JavaScript runtime

In this release, I upgraded to the latest Selenium release (version 4.40.0). I also added comprehensive documentation for the new JavaScript execution runtime added in the previous Selenium Foundation release (version 32.0.1).

Deterministic JavaScript Execution and Unified Exception Handling

🚀 Major Enhancements

JavaScript Execution Runtime

• Introduced a robust JavaScript execution runtime (__wdRuntime) supporting:

  • Synchronous and asynchronous execution
  • Promise-aware completion handling
  • Deterministic result and error envelopes
  • Configurable timeout enforcement for async scripts

• Replaced legacy glue-library injection with idempotent runtime injection

• Added standardized execution templates (exec-sync.format, exec-async.format) for consistent behavior across browsers

Cross-Language Exception Propagation

• Added a unified Java ⇄ JavaScript exception bridge

• JavaScript can now explicitly fail with a requested Java exception type:

  __wd.fail("com.example.MyException", "message");

• Java exceptions are instantiated reflectively and validated against policy

---

🧩 Exception Architecture Overhaul

New Exception Base and Types

• Introduced SeleniumFoundationException, extending WebDriverException

• Added:

  • ScriptExecutionException for script/runtime failures
  • JavaScriptStackTrace as a carrier for browser-side stack traces

• Introduced an ExceptionPolicy SPI to control which exception types may be propagated

Behavioral Changes

• JavaScript stack traces are now attached as suppressed exceptions when available
• Framework exceptions integrate cleanly with Selenium’s reporting and retry mechanisms

⚠️ Potentially Breaking Change
Code that catches specific RuntimeException or WebDriverException subclasses may observe different exception types.

---

🧪 Shadow DOM & Browser Handling Improvements

• Shadow host validation now fails via runtime-mediated exception propagation
• Removed browser-specific exception suppression in favor of consistent runtime behavior
• Tests explicitly skip unsupported environments rather than relying on error detection
• Improved Safari and iOS Safari stability for Shadow DOM access

---

🔧 API & Utility Improvements

JavaScript Utilities

• JsUtility refactored to:

  • Use the new runtime exclusively
  • Support configurable async timeouts
  • Remove deprecated injection paths

WebDriver Utilities

• Added WebDriverUtils.getAutomationEngine(SearchContext)
• Android activity launching now uses shared capability resolution logic
• Improved page refresh stability by waiting for load completion after navigation

---

🧹 Internal Cleanup & Maintenance

• Removed deprecated JavaScript glue libraries
• Simplified exception propagation and handling paths
• Updated documentation and examples to reflect version 32.0.1

---

📌 Summary

Version 32.0.1 introduces a modern, deterministic JavaScript execution and error-propagation model, unifies framework exception handling, and improves reliability across browsers—especially for Shadow DOM and async script execution.

Highly recommended for users relying on JavaScript execution, Shadow DOM interaction, or custom exception handling.

Fix frame handling to work everywhere; skip specific tests in unsupported configurations

• I revised the frame-handling implementation to eliminate reliance on driver.switchTo().parentFrame(), which is unsupported on some platforms.
• I added a switchToParentFrame() method to the WrapsContext interface and defined implementations that switch to the parent frame using Selenium Foundation's context hierarchy.
• I eliminated the use of WebDriverManager/SeleniumManager for desktop Safari.
• I moved the test-method skip functions to TestBase to eliminate code duplication.
• I specified skipping of several tests for scenarios that aren't supported by Desktop Safari in Selenium 3 and Safari for iOS.

Enable driving Safari on iOS; use normal search for 'optional' elements

In this release, I enabled interactions with the Safari browser on iOS:

• I added a new XCUITest.safari personality and an additional record to the Grid hub configuration.
• I extended that utilization of pre-W3C Shadow Root support to include Safari on iOS, changing the name of the search context class from FirefoxShadowRoot to ShadowDomBridge to more accurately summarize the purpose of this class.
• To enable execution of the web application feature tests, I added XCUITestPlugin to the list of plug-ins supported by the web-app target platform.

Also included in this release:

• I eliminated the use of JavaScript code in the implementation for 'optional' and indexed elements so that this feature is available on platforms that lack JavaScript support.
• I fixed a long-standing bug in WebDriverUtils where I'd failed to qualify the getPlaform(org.openqa.selenium.SearchContext) method as static, which rendered this method inaccessible.