diff --git a/README.md b/README.md index e6c94b7f..6de8e620 100644 --- a/README.md +++ b/README.md @@ -286,6 +286,7 @@ any | `appium.options.common.base.AppiumOptions` `safari` | `appium.options.ios.SafariOptions` `mac2` | `appium.options.mac.Mac2Options` `windows` | `appium.options.WindowsOptions` +`wincore` | `appium.options.windows.WincoreOptions` `gecko` | `appium.options.GeckoOptions` `flutterintegration` | `appium.options.flutter_integration.FlutterOptions` diff --git a/appium/options/windows/__init__.py b/appium/options/windows/__init__.py index 2a4617c6..3844c2bf 100644 --- a/appium/options/windows/__init__.py +++ b/appium/options/windows/__init__.py @@ -1,3 +1,4 @@ +from .wincore.base import WincoreOptions from .windows.base import WindowsOptions -__all__ = ['WindowsOptions'] +__all__ = ['WincoreOptions', 'WindowsOptions'] diff --git a/appium/options/windows/wincore/__init__.py b/appium/options/windows/wincore/__init__.py new file mode 100644 index 00000000..b98df66d --- /dev/null +++ b/appium/options/windows/wincore/__init__.py @@ -0,0 +1,3 @@ +from .base import WincoreOptions + +__all__ = ['WincoreOptions'] diff --git a/appium/options/windows/wincore/base.py b/appium/options/windows/wincore/base.py new file mode 100644 index 00000000..9e357842 --- /dev/null +++ b/appium/options/windows/wincore/base.py @@ -0,0 +1,310 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from datetime import timedelta +from os import PathLike, fspath + +from appium.options.common.app_option import AppOption +from appium.options.common.automation_name_option import AUTOMATION_NAME +from appium.options.common.base import PLATFORM_NAME, AppiumOptions +from appium.options.common.postrun_option import PostrunOption +from appium.options.common.prerun_option import PrerunOption +from appium.options.windows.windows.app_arguments_option import AppArgumentsOption +from appium.options.windows.windows.app_top_level_window_option import AppTopLevelWindowOption +from appium.options.windows.windows.app_working_dir_option import AppWorkingDirOption +from appium.options.windows.windows.wait_for_app_launch_option import WAIT_FOR_APP_LAUNCH, WaitForAppLaunchOption + +SHOULD_CLOSE_APP = 'shouldCloseApp' +FORCE_QUIT = 'ms:forcequit' +ISOLATED_SCRIPT_EXECUTION = 'isolatedScriptExecution' +SMOOTH_POINTER_MOVE = 'smoothPointerMove' +DELAY_BEFORE_CLICK = 'delayBeforeClick' +DELAY_AFTER_CLICK = 'delayAfterClick' +LOG_FILE = 'logFile' +PERF_METRICS = 'perfMetrics' +WEBVIEW_ENABLED = 'webviewEnabled' +WEBVIEW_DEVTOOLS_PORT = 'webviewDevtoolsPort' +CHROMEDRIVER_EXECUTABLE_PATH = 'chromedriverExecutablePath' +EDGEDRIVER_EXECUTABLE_PATH = 'edgedriverExecutablePath' +CHROMEDRIVER_CDN_URL = 'chromedriverCdnUrl' +EDGEDRIVER_CDN_URL = 'edgedriverCdnUrl' +FFMPEG_EXECUTABLE_PATH = 'ffmpegExecutablePath' + +MAX_WAIT_FOR_APP_LAUNCH_SECONDS = 120 + + +class WincoreOptions( + AppiumOptions, + PrerunOption, + PostrunOption, + AppOption, + AppTopLevelWindowOption, + AppWorkingDirOption, + WaitForAppLaunchOption, + AppArgumentsOption, +): + @property + def wait_for_app_launch(self) -> timedelta | None: + """ + Maximum wait duration for the application window to appear after launch. + Values up to 120 are interpreted as seconds by Wincore; larger values are + interpreted as milliseconds. + """ + value = self.get_capability(WAIT_FOR_APP_LAUNCH) + if value is None: + return None + if value > MAX_WAIT_FOR_APP_LAUNCH_SECONDS: + return timedelta(milliseconds=value) + return timedelta(seconds=value) + + @wait_for_app_launch.setter + def wait_for_app_launch(self, value: timedelta | int | float) -> None: + """ + Set how long to wait for the application window (or main window after a splash + screen) to appear after launch. Numeric values up to 120 are read as seconds and + larger values as milliseconds. ``timedelta`` values longer than 120 seconds are + serialized in milliseconds. + """ + if isinstance(value, timedelta): + seconds = value.total_seconds() + serialized: int | float = round(seconds * 1000) if seconds > MAX_WAIT_FOR_APP_LAUNCH_SECONDS else seconds + else: + serialized = value + self.set_capability(WAIT_FOR_APP_LAUNCH, serialized) + + @property + def should_close_app(self) -> bool | None: + """ + Whether to close the application window when the session ends. + """ + return self.get_capability(SHOULD_CLOSE_APP) + + @should_close_app.setter + def should_close_app(self, value: bool) -> None: + """ + Set whether to close the application window when the session ends. + Defaults to True on the driver side; has no effect in Root sessions. + """ + self.set_capability(SHOULD_CLOSE_APP, value) + + @property + def force_quit(self) -> bool | None: + """ + Whether to kill the application process instead of closing its window on session end. + """ + return self.get_capability(FORCE_QUIT) + + @force_quit.setter + def force_quit(self, value: bool) -> None: + """ + Set whether to terminate the application process instead of closing its window + when the application is closed at the end of the session. + """ + self.set_capability(FORCE_QUIT, value) + + @property + def isolated_script_execution(self) -> bool | None: + """ + Whether PowerShell scripts run without loading the user profile. + """ + return self.get_capability(ISOLATED_SCRIPT_EXECUTION) + + @isolated_script_execution.setter + def isolated_script_execution(self, value: bool) -> None: + """ + Set whether PowerShell scripts (windows: powerShell, prerun, postrun) run + without loading the user profile. + """ + self.set_capability(ISOLATED_SCRIPT_EXECUTION, value) + + @property + def smooth_pointer_move(self) -> str | None: + """ + Easing curve used for mouse pointer moves. + """ + return self.get_capability(SMOOTH_POINTER_MOVE) + + @smooth_pointer_move.setter + def smooth_pointer_move(self, value: str) -> None: + """ + Set the easing curve for mouse pointer moves, such as 'linear', 'ease', + 'ease-in', 'ease-out', 'ease-in-out', or 'cubic-bezier(x1,y1,x2,y2)'. + """ + self.set_capability(SMOOTH_POINTER_MOVE, value) + + @property + def delay_before_click(self) -> timedelta | None: + """ + Duration of the pointer move to an element before clicking it. + """ + value = self.get_capability(DELAY_BEFORE_CLICK) + return None if value is None else timedelta(milliseconds=value) + + @delay_before_click.setter + def delay_before_click(self, value: timedelta | int) -> None: + """ + Set the duration of the pointer move to an element before clicking it, + either as a timedelta or an integer number of milliseconds. + """ + self.set_capability(DELAY_BEFORE_CLICK, round(value.total_seconds() * 1000) if isinstance(value, timedelta) else value) + + @property + def delay_after_click(self) -> timedelta | None: + """ + Duration to wait after each click. + """ + value = self.get_capability(DELAY_AFTER_CLICK) + return None if value is None else timedelta(milliseconds=value) + + @delay_after_click.setter + def delay_after_click(self, value: timedelta | int) -> None: + """ + Set the duration to wait after each click, either as a timedelta or + an integer number of milliseconds. + """ + self.set_capability(DELAY_AFTER_CLICK, round(value.total_seconds() * 1000) if isinstance(value, timedelta) else value) + + @property + def log_file(self) -> str | bool | None: + """ + File path or boolean flag controlling session log mirroring. + """ + return self.get_capability(LOG_FILE) + + @log_file.setter + def log_file(self, value: str | PathLike[str] | bool) -> None: + """ + Mirror the driver session log to a file. Pass True for a timestamped default + path, a directory path ending in a separator, or an explicit file path. + """ + self.set_capability(LOG_FILE, value if isinstance(value, bool) else fspath(value)) + + @property + def perf_metrics(self) -> bool | None: + """ + Whether per-session performance counters are enabled. + """ + return self.get_capability(PERF_METRICS) + + @perf_metrics.setter + def perf_metrics(self, value: bool) -> None: + """ + Enable or disable per-session performance counters for driver calls. + """ + self.set_capability(PERF_METRICS, value) + + @property + def webview_enabled(self) -> bool | None: + """ + Whether automation of WebView2, Chrome, and Edge content over CDP is enabled. + """ + return self.get_capability(WEBVIEW_ENABLED) + + @webview_enabled.setter + def webview_enabled(self, value: bool) -> None: + """ + Enable or disable automation of WebView2, Chrome, and Edge content over + the Chrome DevTools Protocol. + """ + self.set_capability(WEBVIEW_ENABLED, value) + + @property + def webview_devtools_port(self) -> int | None: + """ + Remote debugging port used to connect to WebView2 or browser CDP. + """ + return self.get_capability(WEBVIEW_DEVTOOLS_PORT) + + @webview_devtools_port.setter + def webview_devtools_port(self, value: int) -> None: + """ + Set the remote debugging port to connect to for WebView2 or browser automation. + """ + self.set_capability(WEBVIEW_DEVTOOLS_PORT, value) + + @property + def chromedriver_executable_path(self) -> str | None: + """ + Path to a local Chromedriver binary. + """ + return self.get_capability(CHROMEDRIVER_EXECUTABLE_PATH) + + @chromedriver_executable_path.setter + def chromedriver_executable_path(self, value: str | PathLike[str]) -> None: + """ + Set the path to a local Chromedriver binary to use instead of downloading one. + """ + self.set_capability(CHROMEDRIVER_EXECUTABLE_PATH, fspath(value)) + + @property + def edgedriver_executable_path(self) -> str | None: + """ + Path to a local Microsoft Edge WebDriver binary. + """ + return self.get_capability(EDGEDRIVER_EXECUTABLE_PATH) + + @edgedriver_executable_path.setter + def edgedriver_executable_path(self, value: str | PathLike[str]) -> None: + """ + Set the path to a local Microsoft Edge WebDriver (msedgedriver) binary + to use instead of downloading one. + """ + self.set_capability(EDGEDRIVER_EXECUTABLE_PATH, fspath(value)) + + @property + def chromedriver_cdn_url(self) -> str | None: + """ + Custom CDN URL used to download Chromedriver. + """ + return self.get_capability(CHROMEDRIVER_CDN_URL) + + @chromedriver_cdn_url.setter + def chromedriver_cdn_url(self, value: str) -> None: + """ + Set a custom CDN URL to download Chromedriver from. + """ + self.set_capability(CHROMEDRIVER_CDN_URL, value) + + @property + def edgedriver_cdn_url(self) -> str | None: + """ + Custom CDN URL used to download Microsoft Edge WebDriver. + """ + return self.get_capability(EDGEDRIVER_CDN_URL) + + @edgedriver_cdn_url.setter + def edgedriver_cdn_url(self, value: str) -> None: + """ + Set a custom CDN URL to download Microsoft Edge WebDriver from. + """ + self.set_capability(EDGEDRIVER_CDN_URL, value) + + @property + def ffmpeg_executable_path(self) -> str | None: + """ + Path to a local FFmpeg binary used for screen recording. + """ + return self.get_capability(FFMPEG_EXECUTABLE_PATH) + + @ffmpeg_executable_path.setter + def ffmpeg_executable_path(self, value: str | PathLike[str]) -> None: + """ + Set the path to a local FFmpeg binary used by screen recording. + """ + self.set_capability(FFMPEG_EXECUTABLE_PATH, fspath(value)) + + @property + def default_capabilities(self) -> dict: + return { + AUTOMATION_NAME: 'Wincore', + PLATFORM_NAME: 'Windows', + } diff --git a/test/unit/options/__init__.py b/test/unit/options/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/test/unit/options/wincore_options_test.py b/test/unit/options/wincore_options_test.py new file mode 100644 index 00000000..39a4a7f9 --- /dev/null +++ b/test/unit/options/wincore_options_test.py @@ -0,0 +1,254 @@ +import json +from datetime import timedelta +from pathlib import Path + +import httpretty + +from appium import webdriver +from appium.options.windows import WincoreOptions +from appium.options.windows.wincore import WincoreOptions as WincoreOptionsDirect +from test.helpers.constants import SERVER_URL_BASE + + +def test_wincore_default_capabilities(): + assert WincoreOptions is WincoreOptionsDirect + options = WincoreOptions() + + assert options.platform_name == 'Windows' + assert options.automation_name == 'Wincore' + assert options.to_capabilities() == { + 'automationName': 'Wincore', + 'platformName': 'Windows', + } + assert options.to_w3c() == { + 'capabilities': { + 'firstMatch': [{}], + 'alwaysMatch': { + 'platformName': 'Windows', + 'appium:automationName': 'Wincore', + }, + } + } + + +def test_wincore_unset_properties_return_none(): + options = WincoreOptions() + + assert options.app is None + assert options.app_top_level_window is None + assert options.app_arguments is None + assert options.app_working_dir is None + assert options.prerun is None + assert options.postrun is None + assert options.wait_for_app_launch is None + assert options.should_close_app is None + assert options.force_quit is None + assert options.isolated_script_execution is None + assert options.smooth_pointer_move is None + assert options.delay_before_click is None + assert options.delay_after_click is None + assert options.log_file is None + assert options.perf_metrics is None + assert options.webview_enabled is None + assert options.webview_devtools_port is None + assert options.chromedriver_executable_path is None + assert options.edgedriver_executable_path is None + assert options.chromedriver_cdn_url is None + assert options.edgedriver_cdn_url is None + assert options.ffmpeg_executable_path is None + + +def test_wincore_capabilities_roundtrip(): + options = WincoreOptions() + options.app = r'C:\Windows\System32\notepad.exe' + options.app_arguments = '/A test.txt' + options.app_working_dir = r'C:\Temp' + options.prerun = {'script': 'Write-Output "pre"'} + options.postrun = {'command': 'Write-Output "post"'} + options.should_close_app = False + options.force_quit = True + options.isolated_script_execution = True + options.smooth_pointer_move = 'ease-in-out' + options.delay_before_click = timedelta(seconds=1.15) + options.delay_after_click = 75 + options.log_file = True + options.perf_metrics = True + options.webview_enabled = True + options.webview_devtools_port = 9222 + options.chromedriver_executable_path = '/tools/chromedriver.exe' + options.edgedriver_executable_path = '/tools/msedgedriver.exe' + options.chromedriver_cdn_url = 'https://mirror.example/chromedriver' + options.edgedriver_cdn_url = 'https://mirror.example/edgedriver' + options.ffmpeg_executable_path = '/tools/ffmpeg.exe' + + assert options.app == r'C:\Windows\System32\notepad.exe' + assert options.app_arguments == '/A test.txt' + assert options.app_working_dir == r'C:\Temp' + assert options.prerun == {'script': 'Write-Output "pre"'} + assert options.postrun == {'command': 'Write-Output "post"'} + assert options.should_close_app is False + assert options.force_quit is True + assert options.isolated_script_execution is True + assert options.smooth_pointer_move == 'ease-in-out' + assert options.delay_before_click == timedelta(milliseconds=1150) + assert options.delay_after_click == timedelta(milliseconds=75) + assert options.log_file is True + assert options.perf_metrics is True + assert options.webview_enabled is True + assert options.webview_devtools_port == 9222 + assert options.chromedriver_executable_path == '/tools/chromedriver.exe' + assert options.edgedriver_executable_path == '/tools/msedgedriver.exe' + assert options.chromedriver_cdn_url == 'https://mirror.example/chromedriver' + assert options.edgedriver_cdn_url == 'https://mirror.example/edgedriver' + assert options.ffmpeg_executable_path == '/tools/ffmpeg.exe' + + w3c_caps = options.to_w3c()['capabilities']['alwaysMatch'] + assert w3c_caps == { + 'platformName': 'Windows', + 'appium:automationName': 'Wincore', + 'appium:app': r'C:\Windows\System32\notepad.exe', + 'appium:appArguments': '/A test.txt', + 'appium:appWorkingDir': r'C:\Temp', + 'appium:prerun': {'script': 'Write-Output "pre"'}, + 'appium:postrun': {'command': 'Write-Output "post"'}, + 'appium:shouldCloseApp': False, + 'ms:forcequit': True, + 'appium:isolatedScriptExecution': True, + 'appium:smoothPointerMove': 'ease-in-out', + 'appium:delayBeforeClick': 1150, + 'appium:delayAfterClick': 75, + 'appium:logFile': True, + 'appium:perfMetrics': True, + 'appium:webviewEnabled': True, + 'appium:webviewDevtoolsPort': 9222, + 'appium:chromedriverExecutablePath': '/tools/chromedriver.exe', + 'appium:edgedriverExecutablePath': '/tools/msedgedriver.exe', + 'appium:chromedriverCdnUrl': 'https://mirror.example/chromedriver', + 'appium:edgedriverCdnUrl': 'https://mirror.example/edgedriver', + 'appium:ffmpegExecutablePath': '/tools/ffmpeg.exe', + } + + +def test_wincore_wait_for_app_launch_seconds_and_milliseconds(): + options = WincoreOptions() + + options.wait_for_app_launch = 10 + assert options.to_capabilities()['ms:waitForAppLaunch'] == 10 + assert options.wait_for_app_launch == timedelta(seconds=10) + + options.wait_for_app_launch = 120 + assert options.to_capabilities()['ms:waitForAppLaunch'] == 120 + assert options.wait_for_app_launch == timedelta(seconds=120) + + options.wait_for_app_launch = 5000 + assert options.to_capabilities()['ms:waitForAppLaunch'] == 5000 + assert options.wait_for_app_launch == timedelta(seconds=5) + + options.wait_for_app_launch = timedelta(seconds=15) + assert options.to_capabilities()['ms:waitForAppLaunch'] == 15.0 + assert options.wait_for_app_launch == timedelta(seconds=15) + + options.wait_for_app_launch = timedelta(seconds=120) + assert options.to_capabilities()['ms:waitForAppLaunch'] == 120.0 + assert options.wait_for_app_launch == timedelta(seconds=120) + + options.wait_for_app_launch = timedelta(seconds=150) + assert options.to_capabilities()['ms:waitForAppLaunch'] == 150000 + assert options.wait_for_app_launch == timedelta(seconds=150) + + options.wait_for_app_launch = timedelta(seconds=120, milliseconds=500) + assert options.to_capabilities()['ms:waitForAppLaunch'] == 120500 + assert options.wait_for_app_launch == timedelta(seconds=120, milliseconds=500) + + options.wait_for_app_launch = 0 + assert options.wait_for_app_launch == timedelta(0) + + +def test_wincore_zero_delays_and_pathlike_values(): + options = WincoreOptions() + options.delay_before_click = 0 + options.delay_after_click = timedelta(0) + options.log_file = False + + assert options.delay_before_click == timedelta(0) + assert options.delay_after_click == timedelta(0) + assert options.log_file is False + + log_path = Path('logs') / 'session.log' + chrome_path = Path('drivers') / 'chromedriver.exe' + edge_path = Path('drivers') / 'msedgedriver.exe' + ffmpeg_path = Path('bin') / 'ffmpeg.exe' + + options.log_file = log_path + options.chromedriver_executable_path = chrome_path + options.edgedriver_executable_path = edge_path + options.ffmpeg_executable_path = ffmpeg_path + + assert options.log_file == str(log_path) + assert options.chromedriver_executable_path == str(chrome_path) + assert options.edgedriver_executable_path == str(edge_path) + assert options.ffmpeg_executable_path == str(ffmpeg_path) + + +def test_wincore_load_and_unset_capabilities(): + options = WincoreOptions().load_capabilities( + { + 'appTopLevelWindow': '0x001A0B2C', + 'shouldCloseApp': False, + 'ms:forcequit': True, + 'ms:waitForAppLaunch': 2500, + 'appium:delayBeforeClick': 120, + 'appium:delayAfterClick': 50, + 'appium:webviewDevtoolsPort': 9333, + } + ) + + assert options.app_top_level_window == '0x001A0B2C' + assert options.should_close_app is False + assert options.force_quit is True + assert options.wait_for_app_launch == timedelta(milliseconds=2500) + assert options.delay_before_click == timedelta(milliseconds=120) + assert options.delay_after_click == timedelta(milliseconds=50) + assert options.webview_devtools_port == 9333 + + options.set_capability('ms:forcequit', None) + options.set_capability('delayBeforeClick', None) + assert options.force_quit is None + assert options.delay_before_click is None + + +@httpretty.activate +def test_wincore_create_session_request_payload(): + options = WincoreOptions() + options.app = 'Root' + options.should_close_app = False + options.force_quit = True + options.wait_for_app_launch = timedelta(seconds=30) + options.delay_before_click = timedelta(milliseconds=200) + options.webview_enabled = True + + httpretty.register_uri( + httpretty.POST, + f'{SERVER_URL_BASE}/session', + body=json.dumps({'value': {'sessionId': 'wincore-session', 'capabilities': {}}}), + ) + + driver = webdriver.Remote(SERVER_URL_BASE, options=options) + assert driver.session_id == 'wincore-session' + + request_json = json.loads(httpretty.last_request().body.decode('utf-8')) + assert request_json == { + 'capabilities': { + 'firstMatch': [{}], + 'alwaysMatch': { + 'platformName': 'Windows', + 'appium:automationName': 'Wincore', + 'appium:app': 'Root', + 'appium:shouldCloseApp': False, + 'ms:forcequit': True, + 'ms:waitForAppLaunch': 30.0, + 'appium:delayBeforeClick': 200, + 'appium:webviewEnabled': True, + }, + } + }