Update dev version

* Add zh-TW and EN comments.
* Fix type-hint

Author: JE-Chen

dev_requirements.txt

@@ -2,4 +2,5 @@ build
 twine
 sphinx
 je_web_runner_dev
-sphinx-rtd-theme
+sphinx-rtd-theme
+Pyside6

je_web_runner/__main__.py

@@ -12,39 +12,58 @@
 
 if __name__ == "__main__":
     try:
+        # 處理單一檔案的執行
+        # Execute actions from a single JSON file
         def preprocess_execute_action(file_path: str):
             execute_action(read_action_json(file_path))
 
 
+        # 處理整個資料夾的執行
+        # Execute actions from all JSON files in a directory
         def preprocess_execute_files(file_path: str):
             execute_files(get_dir_files_as_list(file_path))
 
 
+        # 處理字串輸入的 JSON 執行
+        # Execute actions from a JSON string
         def preprocess_read_str_execute_action(execute_str: str):
             if sys.platform in ["win32", "cygwin", "msys"]:
+                # Windows 平台可能需要兩次 json.loads
+                # On Windows, sometimes double json.loads is required
                 json_data = json.loads(execute_str)
                 execute_str = json.loads(json_data)
             else:
                 execute_str = json.loads(execute_str)
             execute_action(execute_str)
 
 
+        # 對應 argparse 參數與處理函式
+        # Mapping argparse options to handler functions
         argparse_event_dict = {
             "execute_file": preprocess_execute_action,
             "execute_dir": preprocess_execute_files,
             "execute_str": preprocess_read_str_execute_action
         }
+
+        # 建立 argparse 解析器
         parser = argparse.ArgumentParser()
         parser.add_argument("-e", "--execute_file", type=str, help="choose action file to execute")
         parser.add_argument("-d", "--execute_dir", type=str, help="choose dir include action file to execute")
         parser.add_argument("--execute_str", type=str, help="execute json str")
+
+        # 解析參數
         args = parser.parse_args()
         args = vars(args)
+
+        # 執行對應的處理函式
         for key, value in args.items():
             if value is not None:
                 argparse_event_dict.get(key)(value)
+
+        # 如果沒有任何參數，拋出例外
         if all(value is None for value in args.values()):
             raise WebRunnerExecuteException(argparse_get_wrong_data)
+
     except Exception as error:
         print(repr(error), file=sys.stderr)
-        sys.exit(1)
+        sys.exit(1)

je_web_runner/element/web_element_wrapper.py

@@ -1,4 +1,4 @@
-from typing import List
+from typing import List, Union
 
 from selenium.webdriver.remote.webelement import WebElement
 from selenium.webdriver.support.ui import Select
@@ -9,15 +9,19 @@
 
 
 class WebElementWrapper(object):
-
     def __init__(self):
-        self.current_web_element: [WebElement] = None
-        self.current_web_element_list: [List[WebElement]] = None
+        # 當前操作的單一 WebElement
+        # Current active WebElement
+        self.current_web_element: Union[WebElement, None] = None
+
+        # 當前操作的 WebElement 清單
+        # Current list of WebElements
+        self.current_web_element_list: Union[List[WebElement], None] = None
 
     def submit(self) -> None:
         """
-        current web element submit
-        :return: None
+        提交當前 WebElement
+        Submit the current WebElement
         """
         web_runner_logger.info("WebElementWrapper submit")
         try:
@@ -29,8 +33,8 @@ def submit(self) -> None:
 
     def clear(self) -> None:
         """
-        current web element clear
-        :return: None
+        清除當前 WebElement 的內容
+        Clear the content of the current WebElement
         """
         web_runner_logger.info("WebElementWrapper clear")
         try:
@@ -40,10 +44,12 @@ def clear(self) -> None:
             web_runner_logger.error(f"WebElementWrapper clear, failed: {repr(error)}")
             record_action_to_list("Web element clear", None, error)
 
-    def get_property(self, name: str) -> str:
+    def get_property(self, name: str) -> None | str | bool | WebElement | dict:
         """
-        :param name: name of property
-        :return: property value as str
+        取得 WebElement 的屬性
+        Get property of the WebElement
+        :param name: 屬性名稱 / property name
+        :return: 屬性值 / property value
         """
         web_runner_logger.info(f"WebElementWrapper get_property, name: {name}")
         param = locals()
@@ -54,10 +60,12 @@ def get_property(self, name: str) -> str:
             web_runner_logger.error(f"WebElementWrapper get_property, name: {name}, failed: {repr(error)}")
             record_action_to_list("Web element get_property", param, error)
 
-    def get_dom_attribute(self, name: str) -> str:
+    def get_dom_attribute(self, name: str) -> str | None:
         """
-        :param name: name of dom
-        :return: dom attribute value as str
+        取得 DOM 屬性
+        Get DOM attribute
+        :param name: DOM 屬性名稱 / DOM attribute name
+        :return: 屬性值 / attribute value
         """
         web_runner_logger.info(f"WebElementWrapper get_dom_attribute, name: {name}")
         param = locals()
@@ -68,10 +76,12 @@ def get_dom_attribute(self, name: str) -> str:
             web_runner_logger.error(f"WebElementWrapper get_dom_attribute, name: {name}, failed: {repr(error)}")
             record_action_to_list("Web element get_dom_attribute", param, error)
 
-    def get_attribute(self, name: str) -> str:
+    def get_attribute(self, name: str) -> str | None:
         """
-        :param name: name of web element
-        :return:web element attribute value as str
+        取得 WebElement 的屬性
+        Get attribute of the WebElement
+        :param name: 屬性名稱 / attribute name
+        :return: 屬性值 / attribute value
         """
         web_runner_logger.info(f"WebElementWrapper get_attribute, name: {name}")
         param = locals()
@@ -82,23 +92,25 @@ def get_attribute(self, name: str) -> str:
             web_runner_logger.error(f"WebElementWrapper get_attribute, name: {name}, failed: {repr(error)}")
             record_action_to_list("Web element get_attribute", param, error)
 
-    def is_selected(self) -> bool:
+    def is_selected(self) -> bool | None:
         """
-        check current web element is selected or not
-        :return: True or False
+        檢查 WebElement 是否被選取
+        Check if WebElement is selected
+        :return: True/False
         """
         web_runner_logger.info("WebElementWrapper is_selected")
         try:
             record_action_to_list("Web element is_selected", None, None)
             return self.current_web_element.is_selected()
         except Exception as error:
-            web_runner_logger.error(f"WebElementWrapper get_attribute, failed: {repr(error)}")
+            web_runner_logger.error(f"WebElementWrapper is_selected, failed: {repr(error)}")
             record_action_to_list("Web element is_selected", None, error)
 
-    def is_enabled(self) -> bool:
+    def is_enabled(self) -> bool | None:
         """
-        check current web element is enable or not
-        :return: True or False
+        檢查 WebElement 是否可用
+        Check if WebElement is enabled
+        :return: True/False
         """
         web_runner_logger.info("WebElementWrapper is_enabled")
         try:
@@ -110,9 +122,9 @@ def is_enabled(self) -> bool:
 
     def input_to_element(self, input_value: str) -> None:
         """
-        input value to current web element
-        :param input_value: what value we want to input to current web element
-        :return: None
+        輸入文字到 WebElement
+        Input text into WebElement
+        :param input_value: 要輸入的文字 / text to input
         """
         web_runner_logger.info(f"WebElementWrapper input_to_element, input_value: {input_value}")
         param = locals()
@@ -121,14 +133,13 @@ def input_to_element(self, input_value: str) -> None:
             record_action_to_list("Web element input_to_element", param, None)
         except Exception as error:
             web_runner_logger.error(
-                f"WebElementWrapper input_to_element, input_value: {input_value}, "
-                f"failed: {repr(error)}")
+                f"WebElementWrapper input_to_element, input_value: {input_value}, failed: {repr(error)}")
             record_action_to_list("Web element input_to_element", param, error)
 
     def click_element(self) -> None:
         """
-        click current web element
-        :return: None
+        點擊 WebElement
+        Click the WebElement
         """
         web_runner_logger.info("WebElementWrapper click_element")
         try:
@@ -138,10 +149,11 @@ def click_element(self) -> None:
             web_runner_logger.error(f"WebElementWrapper click_element, failed: {repr(error)}")
             record_action_to_list("Web element click_element", None, error)
 
-    def is_displayed(self) -> bool:
+    def is_displayed(self) -> bool | None:
         """
-        check current web element is displayed or not
-        :return: True or False
+        檢查 WebElement 是否顯示
+        Check if WebElement is displayed
+        :return: True/False
         """
         web_runner_logger.info("WebElementWrapper is_displayed")
         try:
@@ -151,10 +163,12 @@ def is_displayed(self) -> bool:
             web_runner_logger.error(f"WebElementWrapper is_displayed, failed: {repr(error)}")
             record_action_to_list("Web element is_displayed", None, error)
 
-    def value_of_css_property(self, property_name: str) -> str:
+    def value_of_css_property(self, property_name: str) -> str | None:
         """
-        :param property_name: name of property
-        :return: css property value as str
+        取得 CSS 屬性值
+        Get CSS property value
+        :param property_name: 屬性名稱 / property name
+        :return: 屬性值 / property value
         """
         web_runner_logger.info(f"WebElementWrapper value_of_css_property, property_name: {property_name}")
         param = locals()
@@ -166,10 +180,12 @@ def value_of_css_property(self, property_name: str) -> str:
                 f"WebElementWrapper value_of_css_property, property_name: {property_name}, failed: {repr(error)}")
             record_action_to_list("Web element value_of_css_property", param, error)
 
-    def screenshot(self, filename: str) -> bool:
+    def screenshot(self, filename: str) -> bool | None:
         """
-        :param filename: full file name not need .png extension
-        :return: Save True or not
+        對 WebElement 截圖並存檔
+        Take screenshot of WebElement and save
+        :param filename: 檔名 (不需加 .png) / filename (without .png)
+        :return: 是否成功 / True if success
         """
         web_runner_logger.info(f"WebElementWrapper screenshot, filename: {filename}")
         param = locals()
@@ -180,11 +196,11 @@ def screenshot(self, filename: str) -> bool:
             web_runner_logger.info(f"WebElementWrapper screenshot, filename: {filename}, failed: {repr(error)}")
             record_action_to_list("Web element screenshot", param, error)
 
-    # Web element wrapper add function
     def change_web_element(self, element_index: int) -> None:
         """
-        :param element_index: change to web element index
-        :return: web element list [element_index]
+        切換當前 WebElement
+        Change current WebElement
+        :param element_index: WebElement 清單索引 / index in WebElement list
         """
         web_runner_logger.info(f"WebElementWrapper change_web_element, element_index: {element_index}")
         param = locals()
@@ -198,33 +214,55 @@ def change_web_element(self, element_index: int) -> None:
 
     def check_current_web_element(self, check_dict: dict) -> None:
         """
-        :param check_dict: check web element dict {name: should be value}
+        檢查當前 WebElement 是否符合指定條件
+        Check if the current WebElement matches the given conditions
+
+        :param check_dict: 驗證用的字典 {屬性名稱: 預期值}
+                           Dictionary for validation {attribute_name: expected_value}
         :return: None
         """
         web_runner_logger.info(f"WebElementWrapper check_current_web_element, check_dict: {check_dict}")
         param = locals()
         try:
+            # 呼叫工具函式檢查 WebElement 的屬性
+            # Call utility function to check WebElement details
             check_web_element_details(self.current_web_element, check_dict)
+
+            # 紀錄成功動作
+            # Record successful action
             record_action_to_list("Web element check_current_web_element", param, None)
         except Exception as error:
+            # 錯誤處理與紀錄
+            # Handle and log error
             web_runner_logger.error(
-                f"WebElementWrapper change_web_element, check_dict: {check_dict}, "
-                f"failed: {repr(error)}")
+                f"WebElementWrapper check_current_web_element, check_dict: {check_dict}, failed: {repr(error)}"
+            )
             record_action_to_list("Web element check_current_web_element", param, error)
 
-    def get_select(self) -> Select:
+    def get_select(self) -> Select | None:
         """
-        get Select(current web element)
-        :return: Select(current web element)
+        取得 Select 物件 (用於操作下拉選單)
+        Get a Select object (for handling dropdown menus)
+
+        :return: Select(current web element) 或 None
+                 Select(current web element) or None
         """
         web_runner_logger.info("WebElementWrapper get_select")
         try:
+            # 紀錄成功動作
+            # Record successful action
             record_action_to_list("Web element get_select", None, None)
+
+            # 回傳 Select 包裝的 WebElement
+            # Return Select wrapper of the WebElement
             return Select(self.current_web_element)
         except Exception as error:
+            # 錯誤處理與紀錄
+            # Handle and log error
             web_runner_logger.error(f"WebElementWrapper get_select, failed: {repr(error)}")
             record_action_to_list("Web element get_select", None, error)
 
 
-# use this wrapper to use web element
-web_element_wrapper = WebElementWrapper()
+# 使用此包裝器來操作 WebElement
+# Use this wrapper to operate on WebElement
+web_element_wrapper = WebElementWrapper()