osn-selenium 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

osn_selenium/trio_bidi/mapping/_js_snippets.py

@@ -0,0 +1,285 @@
+__all__ = ["CAPTURE", "NAVIGATION", "WEB_ELEMENT", "WINDOW"]
+
+
+class WINDOW:
+	"""
+	JavaScript snippets for window-related operations.
+
+	Attributes:
+		SET_ORIENTATION (str): Snippet to lock screen orientation.
+		GET_ORIENTATION (str): Snippet to retrieve the current screen orientation type.
+	"""
+	
+	SET_ORIENTATION = "screen.orientation.lock('{orientation}')"
+	GET_ORIENTATION = "screen.orientation.type"
+
+
+class WEB_ELEMENT:
+	"""
+	JavaScript snippets for web element interactions with internal guards for W3C compatibility.
+
+	Attributes:
+		SEND_KEYS_TO (str): Snippet to focus and append text with input validation.
+		IS_SELECTED (str): Snippet to check if an element is selectable and selected.
+		IS_ENABLED (str): Snippet to check enablement state.
+		GET_TEXT (str): Snippet to retrieve inner text.
+		GET_TAG (str): Snippet to retrieve tag name.
+		GET_SHADOW_ROOT (str): Snippet to retrieve shadow root with existence check.
+		GET_RECT (str): Snippet to retrieve dimensions.
+		GET_PROPERTY (str): Snippet to retrieve element property.
+		GET_CSS (str): Snippet to retrieve CSS value.
+		GET_ATTRIBUTE (str): Snippet to retrieve attribute.
+		GET_ARIA_ROLE (str): Snippet to retrieve ARIA role.
+		GET_ARIA_LABEL (str): Snippet to retrieve accessible label.
+		CLICK (str): Snippet to perform click with interactability guards.
+		CLEAR (str): Snippet to clear value with state guards.
+	"""
+	
+	_GUARDS = """
+	const guards = {
+		stale: (el) => {
+			if (!el.isConnected) throw new Error('stale element reference');
+		},
+		interactable: (el) => {
+			const rects = el.getClientRects();
+			const style = window.getComputedStyle(el);
+			
+			if (rects.length === 0 || style.visibility === 'hidden' || style.display === 'none') {
+				throw new Error('element not interactable');
+			}
+		},
+		state: (el) => {
+			if (el.disabled || el.readOnly) throw new Error('invalid element state');
+		},
+		selectable: (el) => {
+			const tag = el.tagName.toLowerCase();
+			const type = (el.getAttribute('type') || '').toLowerCase();
+			const canSelect = tag === 'option' || type === 'checkbox' || type === 'radio';
+			
+			if (!canSelect) throw new Error('element not selectable');
+		},
+		intercepted: (el) => {
+			const rect = el.getBoundingClientRect();
+			const x = rect.left + rect.width / 2;
+			const y = rect.top + rect.height / 2;
+			const topEl = document.elementFromPoint(x, y);
+			
+			if (topEl && topEl !== el && !el.contains(topEl)) {
+				throw new Error('element click intercepted: Element is obscured by ' + topEl.tagName);
+			}
+		}
+	};
+	"""
+	
+	CLICK = f"""
+function(el){{
+	{_GUARDS}
+	guards.stale(el);
+	guards.interactable(el);
+	guards.state(el);
+	guards.intercepted(el);
+	
+	el.click();
+}}
+"""
+	
+	CLEAR = f"""
+function(el){{
+	{_GUARDS}
+	guards.stale(el);
+	guards.interactable(el);
+	guards.state(el);
+	
+	el.value = '';
+	
+	el.dispatchEvent(new InputEvent('input', {{bubbles: true}}));
+	el.dispatchEvent(new Event('change', {{bubbles: true}}));
+}}
+"""
+	
+	GET_ARIA_ROLE = f"""
+function(el){{
+	{_GUARDS}
+	guards.stale(el);
+	
+	try {{
+		return el.getAttribute && el.getAttribute('role');
+	}} catch(e) {{
+		return '';
+	}}
+}}
+"""
+	
+	GET_ARIA_LABEL = f"""
+function(el){{
+	{_GUARDS}
+	guards.stale(el);
+	
+	try {{
+		var v = null;
+		
+		if (el.getAttribute) v = el.getAttribute('aria-label');
+		if (!v) v = el.getAttribute && el.getAttribute('alt');
+		
+		if (!v) {{
+			var txt = (el.textContent || '').trim();
+			if (txt) v = txt;
+		}}
+		
+		return v || '';
+	}} catch(e) {{
+		return '';
+	}}
+}}
+"""
+	
+	GET_TEXT = f"""
+function(el){{
+	{_GUARDS}
+	guards.stale(el);
+	
+	return el.innerText || '';
+}}
+"""
+	
+	GET_TAG = f"""
+function(el){{
+	{_GUARDS}
+	guards.stale(el);
+	
+	return (el.tagName || '').toLowerCase();
+}}
+"""
+	
+	GET_RECT = f"""
+function(el){{
+	{_GUARDS}
+	guards.stale(el);
+	
+	var r = el.getBoundingClientRect();
+	
+	return {{
+		x: Number(r.x || r.left || 0),
+		y: Number(r.y || r.top || 0),
+		width: Number(r.width || 0),
+		height: Number(r.height || 0)
+	}};
+}}
+"""
+	
+	GET_SHADOW_ROOT = f"""
+function(el){{
+	{_GUARDS}
+	guards.stale(el);
+	
+	const sr = el.shadowRoot;
+	
+	if (!sr) throw new Error('no such shadow root');
+	
+	return sr;
+}}
+"""
+	
+	IS_SELECTED = f"""
+function(el){{
+	{_GUARDS}
+	guards.stale(el);
+	guards.selectable(el);
+	
+	return Boolean(el.selected || el.checked);
+}}
+"""
+	
+	IS_ENABLED = f"""
+function(el){{
+	{_GUARDS}
+	guards.stale(el);
+	
+	return !el.disabled;
+}}
+"""
+	
+	GET_PROPERTY = f"""
+function(el, prop){{
+	{_GUARDS}
+	guards.stale(el);
+	
+	try {{
+		return el[prop];
+	}} catch(e) {{
+		return null;
+	}}
+}}
+"""
+	
+	GET_ATTRIBUTE = f"""
+function(el, attr){{
+	{_GUARDS}
+	guards.stale(el);
+	
+	try {{
+		return el.getAttribute(attr);
+	}} catch(e) {{
+		return null;
+	}}
+}}
+"""
+	
+	GET_CSS = f"""
+function(el, prop){{
+	{_GUARDS}
+	guards.stale(el);
+	
+	try {{
+		return window.getComputedStyle(el).getPropertyValue(prop);
+	}} catch(e) {{
+		return null;
+	}}
+}}
+"""
+	
+	SEND_KEYS_TO = f"""
+function(el, text){{
+	{_GUARDS}
+	guards.stale(el);
+	guards.interactable(el);
+	guards.state(el);
+	
+	try {{
+		el.focus();
+		el.value = (el.value || '') + String(text || '');
+		
+		try {{
+			el.dispatchEvent(new InputEvent('input', {{bubbles: true}}));
+		}} catch(e) {{
+			el.dispatchEvent(new Event('input', {{bubbles: true}}));
+		}}
+		
+		try {{
+			el.dispatchEvent(new Event('change', {{bubbles: true}}));
+		}} catch(e) {{ }}
+	}} catch (e) {{ }}
+}}
+"""
+
+
+class NAVIGATION:
+	"""
+	JavaScript snippets for navigation and page information.
+
+	Attributes:
+		GET_TITLE (str): Snippet to retrieve the document title.
+	"""
+	
+	GET_TITLE = "document.title"
+
+
+class CAPTURE:
+	"""
+	JavaScript snippets for capturing page state.
+
+	Attributes:
+		GET_PAGE_SOURCE (str): Snippet to retrieve the full outer HTML of the document.
+	"""
+	
+	GET_PAGE_SOURCE = "document.documentElement.outerHTML"

osn_selenium/trio_bidi/mapping/_utils.py

@@ -0,0 +1,4 @@
+__all__ = ["ELEMENT_KEY", "SHADOW_ROOT_KEY"]
+
+ELEMENT_KEY = "element-6066-11e4-a52e-4f735466cecf"
+SHADOW_ROOT_KEY = "shadow-6066-11e4-a52e-4f735466cecf"

osn_selenium/trio_bidi/mapping/request_functions/__init__.py

@@ -0,0 +1,87 @@
+from typing import Any, Dict
+from osn_selenium.exceptions.bidi_bridge import (
+	CommandNotMappedToBiDiError
+)
+from osn_selenium.trio_bidi.mapping.request_functions._cdp import (
+	MAPPED_REQUEST_CDP_COMMANDS
+)
+from osn_selenium.trio_bidi.mapping.request_functions._file import (
+	MAPPED_REQUEST_FILE_COMMANDS
+)
+from osn_selenium.trio_bidi.mapping.request_functions._alert import (
+	MAPPED_REQUEST_ALERT_COMMANDS
+)
+from osn_selenium.trio_bidi.mapping.request_functions._script import (
+	MAPPED_REQUEST_SCRIPT_COMMANDS
+)
+from osn_selenium.trio_bidi.mapping.request_functions._window import (
+	MAPPED_REQUEST_WINDOW_COMMANDS
+)
+from osn_selenium.trio_bidi.mapping.request_functions._capture import (
+	MAPPED_REQUEST_CAPTURE_COMMANDS
+)
+from osn_selenium.trio_bidi.mapping.request_functions._element import (
+	MAPPED_REQUEST_ELEMENT_COMMANDS
+)
+from osn_selenium.trio_bidi.mapping.request_functions._switch_to import (
+	MAPPED_REQUEST_SWITCH_TO_COMMANDS
+)
+from osn_selenium.trio_bidi.mapping.request_functions._navigation import (
+	MAPPED_REQUEST_NAVIGATION_COMMANDS
+)
+from osn_selenium.trio_bidi.mapping.request_functions._web_element import (
+	MAPPED_REQUEST_WEB_ELEMENT_COMMANDS
+)
+from osn_selenium.trio_bidi.mapping.request_functions._shadow_root import (
+	MAPPED_REQUEST_SHADOW_ROOT_COMMANDS
+)
+from osn_selenium.trio_bidi._typehints import (
+	CURRENT_BROWSING_CONTEXT_TYPEHINT,
+	MAP_REQUEST_FUNCTION_TYPEHINT,
+	REQUEST_PARAMS_TYPEHINT
+)
+
+
+__all__ = ["map_request"]
+
+_MAPPED_REQUEST_COMMANDS: Dict[str, MAP_REQUEST_FUNCTION_TYPEHINT] = {
+	**MAPPED_REQUEST_ALERT_COMMANDS,
+	**MAPPED_REQUEST_CAPTURE_COMMANDS,
+	**MAPPED_REQUEST_CDP_COMMANDS,
+	**MAPPED_REQUEST_ELEMENT_COMMANDS,
+	**MAPPED_REQUEST_FILE_COMMANDS,
+	**MAPPED_REQUEST_NAVIGATION_COMMANDS,
+	**MAPPED_REQUEST_SCRIPT_COMMANDS,
+	**MAPPED_REQUEST_SHADOW_ROOT_COMMANDS,
+	**MAPPED_REQUEST_SWITCH_TO_COMMANDS,
+	**MAPPED_REQUEST_WEB_ELEMENT_COMMANDS,
+	**MAPPED_REQUEST_WINDOW_COMMANDS,
+}
+
+
+def map_request(
+		command: str,
+		params: REQUEST_PARAMS_TYPEHINT,
+		context_id: CURRENT_BROWSING_CONTEXT_TYPEHINT
+) -> Dict[str, Any]:
+	"""
+	Maps a W3C WebDriver command to its corresponding BiDi protocol request.
+
+	Args:
+		command (str): The W3C command name.
+		params (REQUEST_PARAMS_TYPEHINT): The parameters associated with the command.
+		context_id (CURRENT_BROWSING_CONTEXT_TYPEHINT): The browsing context ID for the command.
+
+	Returns:
+		Dict[str, Any]: The mapped BiDi request dictionary.
+
+	Raises:
+		CommandNotMappedToBiDiError: If the command does not have a defined mapping.
+	"""
+	
+	function = _MAPPED_REQUEST_COMMANDS.get(command, None)
+	
+	if function is not None:
+		return function(params, context_id)
+	
+	raise CommandNotMappedToBiDiError(command=command)

osn_selenium/trio_bidi/mapping/request_functions/_alert.py

@@ -0,0 +1,102 @@
+from typing import Any, Dict
+from selenium.webdriver.remote.command import Command
+from osn_selenium.trio_bidi._internal_mappings import (
+	GET_INTERNAL_ALERT_TEXT
+)
+from osn_selenium.trio_bidi._typehints import (
+	CURRENT_BROWSING_CONTEXT_TYPEHINT,
+	MAP_REQUEST_FUNCTION_TYPEHINT,
+	REQUEST_PARAMS_TYPEHINT
+)
+
+
+__all__ = ["MAPPED_REQUEST_ALERT_COMMANDS"]
+
+
+def _map_set_alert_value_request(
+		params: REQUEST_PARAMS_TYPEHINT,
+		context_id: CURRENT_BROWSING_CONTEXT_TYPEHINT
+) -> Dict[str, Any]:
+	"""
+	Maps the 'set alert value' command to BiDi 'handleUserPrompt'.
+
+	Args:
+		params (REQUEST_PARAMS_TYPEHINT): Request parameters containing 'text'.
+		context_id (CURRENT_BROWSING_CONTEXT_TYPEHINT): The browsing context ID.
+
+	Returns:
+		Dict[str, Any]: The BiDi request.
+	"""
+	
+	return {
+		"method": "browsingContext.handleUserPrompt",
+		"params": {"context": context_id, "accept": True, "userText": params.get("text")}
+	}
+
+
+def _map_get_alert_text_request(
+		params: REQUEST_PARAMS_TYPEHINT,
+		context_id: CURRENT_BROWSING_CONTEXT_TYPEHINT
+) -> Dict[str, Any]:
+	"""
+	Maps the 'get alert text' command to an internal bridge command.
+
+	Args:
+		params (REQUEST_PARAMS_TYPEHINT): Request parameters.
+		context_id (CURRENT_BROWSING_CONTEXT_TYPEHINT): The browsing context ID.
+
+	Returns:
+		Dict[str, Any]: The internal BiDi request.
+	"""
+	
+	return {"method": GET_INTERNAL_ALERT_TEXT, "params": {}}
+
+
+def _map_dismiss_alert_request(
+		params: REQUEST_PARAMS_TYPEHINT,
+		context_id: CURRENT_BROWSING_CONTEXT_TYPEHINT
+) -> Dict[str, Any]:
+	"""
+	Maps the 'dismiss alert' command to BiDi 'handleUserPrompt' with accept=False.
+
+	Args:
+		params (REQUEST_PARAMS_TYPEHINT): Request parameters.
+		context_id (CURRENT_BROWSING_CONTEXT_TYPEHINT): The browsing context ID.
+
+	Returns:
+		Dict[str, Any]: The BiDi request.
+	"""
+	
+	return {
+		"method": "browsingContext.handleUserPrompt",
+		"params": {"context": context_id, "accept": False}
+	}
+
+
+def _map_accept_alert_request(
+		params: REQUEST_PARAMS_TYPEHINT,
+		context_id: CURRENT_BROWSING_CONTEXT_TYPEHINT
+) -> Dict[str, Any]:
+	"""
+	Maps the 'accept alert' command to BiDi 'handleUserPrompt' with accept=True.
+
+	Args:
+		params (REQUEST_PARAMS_TYPEHINT): Request parameters.
+		context_id (CURRENT_BROWSING_CONTEXT_TYPEHINT): The browsing context ID.
+
+	Returns:
+		Dict[str, Any]: The BiDi request.
+	"""
+	
+	return {
+		"method": "browsingContext.handleUserPrompt",
+		"params": {"context": context_id, "accept": True}
+	}
+
+
+MAPPED_REQUEST_ALERT_COMMANDS: Dict[str, MAP_REQUEST_FUNCTION_TYPEHINT] = {
+	Command.W3C_GET_ALERT_TEXT: _map_get_alert_text_request,
+	Command.W3C_ACCEPT_ALERT: _map_accept_alert_request,
+	Command.W3C_DISMISS_ALERT: _map_dismiss_alert_request,
+	Command.W3C_SET_ALERT_VALUE: _map_set_alert_value_request,
+}

osn_selenium/trio_bidi/mapping/request_functions/_args_helpers.py

@@ -0,0 +1,225 @@
+from typing import (
+	Any,
+	Dict,
+	List,
+	Optional
+)
+from osn_selenium.instances.protocols import AnyInstanceWrapper
+from osn_selenium.trio_bidi.mapping._constants import BY_MAPPING_DICT
+from osn_selenium.trio_bidi.mapping._utils import (
+	ELEMENT_KEY,
+	SHADOW_ROOT_KEY
+)
+from selenium.webdriver.remote.webelement import (
+	WebElement as SeleniumWebElement
+)
+from osn_selenium.trio_bidi._typehints import (
+	CURRENT_BROWSING_CONTEXT_TYPEHINT,
+	REQUEST_PARAMS_TYPEHINT
+)
+
+
+__all__ = [
+	"build_bidi_element",
+	"build_locate_nodes_request",
+	"build_script_call_request",
+	"build_script_evaluate_request",
+	"convert_w3c_to_bidi_js",
+	"get_shadow_root_argument",
+	"get_web_element_argument"
+]
+
+
+def build_bidi_element(id_: str) -> Dict[str, Any]:
+	"""
+	Creates a BiDi element reference.
+
+	Args:
+		id_ (str): The shared ID of the element.
+
+	Returns:
+		Dict[str, Any]: The BiDi sharedId reference.
+	"""
+	
+	return {"sharedId": id_}
+
+
+def get_web_element_argument(params: REQUEST_PARAMS_TYPEHINT) -> Dict[str, Any]:
+	"""
+	Extracts the element ID from W3C parameters and creates a BiDi reference.
+
+	Args:
+		params (REQUEST_PARAMS_TYPEHINT): W3C parameters containing 'id'.
+
+	Returns:
+		Dict[str, Any]: The BiDi element reference.
+	"""
+	
+	return build_bidi_element(id_=params["id"])
+
+
+def get_shadow_root_argument(params: REQUEST_PARAMS_TYPEHINT) -> Dict[str, Any]:
+	"""
+	Extracts the shadow ID from W3C parameters and creates a BiDi reference.
+
+	Args:
+		params (REQUEST_PARAMS_TYPEHINT): W3C parameters containing 'shadowId'.
+
+	Returns:
+		Dict[str, Any]: The BiDi element reference.
+	"""
+	
+	return build_bidi_element(id_=params["shadowId"])
+
+
+def convert_w3c_to_bidi_js(w3c_value: Any) -> Dict[str, Any]:
+	"""
+	Converts a W3C-style JavaScript argument into a BiDi LocalValue.
+
+	Args:
+		w3c_value (Any): The value to convert.
+
+	Returns:
+		Dict[str, Any]: The BiDi LocalValue representation.
+
+	EXAMPLES
+	________
+	>>> convert_w3c_to_bidi_js("hello")
+	... {'type': 'string', 'value': 'hello'}
+	>>> convert_w3c_to_bidi_js(True)
+	... {'type': 'boolean', 'value': True}
+	"""
+	
+	if isinstance(w3c_value, AnyInstanceWrapper):
+		w3c_value = w3c_value.legacy
+	
+	if isinstance(w3c_value, SeleniumWebElement):
+		return {"sharedId": w3c_value.id}
+	
+	if isinstance(w3c_value, dict):
+		if ELEMENT_KEY in w3c_value:
+			return {"sharedId": w3c_value[ELEMENT_KEY]}
+	
+		if SHADOW_ROOT_KEY in w3c_value:
+			return {"sharedId": w3c_value[SHADOW_ROOT_KEY]}
+	
+	if w3c_value is None:
+		return {"type": "null"}
+	
+	if isinstance(w3c_value, bool):
+		return {"type": "boolean", "value": w3c_value}
+	
+	if isinstance(w3c_value, (int, float)):
+		return {"type": "number", "value": w3c_value}
+	
+	if isinstance(w3c_value, str):
+		return {"type": "string", "value": w3c_value}
+	
+	if isinstance(w3c_value, (list, tuple, set)):
+		return {
+			"type": "array",
+			"value": [convert_w3c_to_bidi_js(w3c_value=item) for item in w3c_value]
+		}
+	
+	if isinstance(w3c_value, dict):
+		return {
+			"type": "object",
+			"value": [
+				[
+					convert_w3c_to_bidi_js(w3c_value=key),
+					convert_w3c_to_bidi_js(w3c_value=value)
+				]
+				for key, value in w3c_value.items()
+			]
+		}
+	
+	return {"type": "undefined"}
+
+
+def build_script_evaluate_request(context_id: CURRENT_BROWSING_CONTEXT_TYPEHINT, expression: str) -> Dict[str, Any]:
+	"""
+	Builds a BiDi 'script.evaluate' request.
+
+	Args:
+		context_id (CURRENT_BROWSING_CONTEXT_TYPEHINT): The browsing context ID.
+		expression (str): The JS expression to evaluate.
+
+	Returns:
+		Dict[str, Any]: The BiDi request.
+	"""
+	
+	return {
+		"method": "script.evaluate",
+		"params": {
+			"expression": expression,
+			"target": {"context": context_id},
+			"awaitPromise": True,
+			"resultOwnership": "none",
+		}
+	}
+
+
+def build_script_call_request(
+		context_id: CURRENT_BROWSING_CONTEXT_TYPEHINT,
+		function: str,
+		args: Optional[List[Any]],
+		ownership: str
+) -> Dict[str, Any]:
+	"""
+	Builds a BiDi 'script.callFunction' request.
+
+	Args:
+		context_id (CURRENT_BROWSING_CONTEXT_TYPEHINT): The browsing context ID.
+		function (str): The function declaration.
+		args (Optional[List[Any]]): List of BiDi LocalValue arguments.
+		ownership (str): Result ownership type ('none', 'root').
+
+	Returns:
+		Dict[str, Any]: The BiDi request.
+	"""
+	
+	return {
+		"method": "script.callFunction",
+		"params": {
+			"functionDeclaration": function,
+			"arguments": args or [],
+			"target": {"context": context_id},
+			"awaitPromise": True,
+			"resultOwnership": ownership,
+		}
+	}
+
+
+def build_locate_nodes_request(
+		context_id: CURRENT_BROWSING_CONTEXT_TYPEHINT,
+		params: REQUEST_PARAMS_TYPEHINT,
+		max_nodes: Optional[int] = None,
+		start_nodes: Optional[List[Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
+	"""
+	Builds a BiDi 'browsingContext.locateNodes' request.
+
+	Args:
+		context_id (CURRENT_BROWSING_CONTEXT_TYPEHINT): The browsing context ID.
+		params (REQUEST_PARAMS_TYPEHINT): W3C search parameters ('using', 'value').
+		max_nodes (Optional[int]): Maximum number of nodes to return.
+		start_nodes (Optional[List[Dict[str, Any]]]): BiDi element references to start search from.
+
+	Returns:
+		Dict[str, Any]: The BiDi request.
+	"""
+	
+	strategy = BY_MAPPING_DICT.get(params["using"], params["using"])
+	
+	bidi_params: Dict[str, Any] = {
+		"context": context_id,
+		"locator": {"type": strategy, "value": params["value"]}
+	}
+	
+	if max_nodes:
+		bidi_params["maxNodeCount"] = max_nodes
+	
+	if start_nodes:
+		bidi_params["startNodes"] = start_nodes
+	
+	return {"method": "browsingContext.locateNodes", "params": bidi_params}