update method to match selenium 4 find_element (#13)

Author: cle-b

.gitignore

@@ -105,3 +105,5 @@ venv.bak/
 
 # mypy
 .mypy_cache/
+
+demo.py

Makefile

@@ -20,13 +20,13 @@ typing:
 check: lint typing
 
 firefox:
-	docker compose up -d selenium-firefox
+	docker compose up -d --force-recreate selenium-firefox
 
 testfirefox:	
 	pytest -v tests/ --driver Remote --capability browserName firefox --website http://website/ -x 
 
 chrome:
-	docker compose up -d selenium-chrome
+	docker compose up -d --force-recreate selenium-chrome
 
 testchrome:
 	pytest -v tests/ --driver Remote --capability browserName chrome --website http://website/ -x 

README.md

@@ -4,9 +4,9 @@ Niobium extends the Python Selenium client with nice features.
 
 ## Why Niobium
 
-Selenium is probably the better tool for web automation. But sometimes it's hard to write a clean automation script. 
+Selenium is a good tool for web automation, but sometimes it's hard to write a clean automation script.
 
-With Niobium you can keep using Selenium and simplify your scripts. For example, Niobium adds a new element locator, find_element_by_image, which adds image recognition capacity in order to find an element in the webpage.
+With Niobium, you can keep using Selenium while simplifying your scripts. For example, Niobium adds a new element locator,` By.IMAGE`, which enables image recognition in `WebDriver.find_element` to locate an element on the webpage.
 
 The goal of Niobium is not to replace Selenium. We only want to add to Selenium the functions we will love to see in Selenium natively.
 
@@ -22,31 +22,37 @@ Niobium is available on Pypi, so simply use pip.
 
 In order to use Niobium, you just need to import it in your script. Selenium will be automatically extended. 
 
-    from selenium import webdriver
+```python
     import niobium
+    from selenium import webdriver
 
     driver = webdriver.Firefox()
     driver.implicitly_wait(10)
     driver.get("https://www.python.org/")
 
-    driver.find_element_by_image("logo_python.png")
+    driver.find_element(By.IMAGE, "logo_python.png")
 
     driver.quit()
+```
 
 In order to avoid warning with your linter, you can import selenium from niobium.
 
+```python
     from niobium import selenium
 
     driver = selenium.webdriver.Firefox()
     ...
+```
 
 or simply disable the warning, like in this example for flake8
 
-    from selenium import webdriver
+```python
     import niobium  # noqa: F401
+    from selenium import webdriver
 
     driver = webdriver.Firefox()
     ...
+```
 
 If you use pytest and especially pytest-selenium, just import niobium in your conftest.py.
 
@@ -58,4 +64,4 @@ If you use pytest and especially pytest-selenium, just import niobium in your co
 
 Some features implemented in Niobium are here only to help you when there is no other easy solution. If you do a bad usage of Niobium features, it can result to a bad performance in your script, or it will be difficult to maintain it. Please read the documentation in order to know the special warnings for the use of these features.
 
-Niobium do not modify the Selenium library package. The patches are only applied at runtime.
+Niobium do not modify the Selenium library package. The patches are only applied at runtime. This is the reason why the autocompletion is not updated correctly.

docs/image.md

@@ -6,55 +6,67 @@ Niobium adds computer vision to Selenium.
 
 You can locate an image in the page using the following method:
 
-    find_element_by_image(filename)
+```python
+    find_element(By.IMAGE, filename)
+```
 
 And to find multiple images (this method returns a list)
 
-    find_elements_by_image(filename)
+```python
+    find_elements(By.IMAGE, filename)
+```
 
-These methods have the same behavior than the classic find_element methods but they return an ImageElement instead of a WebElement.
+These methods have the same behavior than the classic `find_element` methods but they return an `ImageElement` instead of a `WebElement` if you use the `By.IMAGE` selector.
 
 They take only one argument which is the path to the PNG image that you search.
 
 ## Find element by image
 
-The methods find_element_by_image and find_elements_by_image are available only from the WebDriver object. Only the visible page is analyzed in order to locate the image.
+The methods `find_element` and `find_elements` using the selector `By.IMAGE` are available only from the `WebDriver` object. Only the visible page is analyzed in order to locate the image.
 
+```python
     from selenium import webdriver
     import niobium # noqa: F401
 
     driver = webdriver.Firefox()
     driver.implicitly_wait(10)
     driver.get("https://www.python.org/")
 
-    driver.find_element_by_image("logo_python.png")
+    driver.find_element(By.IMAGE, "logo_python.png")
 
     driver.quit()
+```
 
 ## Click on the image
 
 You can click on the element.
 
-    driver.find_element_by_image("logo_python.png").click()
+```python
+    driver.find_element(By.IMAGE, "logo_python.png").click()
+```
 
 By default, the click is performed on the center of the element.
 
 ## Click with offset
 
 You can click to a specific location related to the top left corner of the element with the `click_at(xoffset, yoffset)` function.
 
-    driver.find_element_by_image("logo_python.png").click_at(100, -100) 
+```python
+    driver.find_element(By.IMAGE, "logo_python.png").click_at(100, -100) 
+```
 
 ## Move the cursor over the element
 
 You can move the cursor to the center of the element with the `move_to()` function.
 
-    driver.find_element_by_image("logo_python.png").move_to()
+```python
+    driver.find_element(By.IMAGE, "logo_python.png").move_to()
+```
 
 ## Move the cursor with offset
 
 You can move the cursor to a specific location related to the top left corner of the element with the `move_at(xoffset, yoffset)` function.
 
-    driver.find_element_by_image("logo_python.png").move_at(20, 20)
-
-
+```python
+    driver.find_element(By.IMAGE, "logo_python.png").move_at(20, 20)
+```

docs/index.md

@@ -4,9 +4,9 @@ Niobium extends the Python Selenium client with nice features.
 
 ## Why Niobium
 
-Selenium is probably the better tool for web automation. But sometimes it's hard to write a clean automation script. 
+Selenium is a good tool for web automation, but sometimes it's hard to write a clean automation script.
 
-With Niobium you can keep using Selenium and simplify your scripts. For example, Niobium adds a new element locator, find_element_by_image, which adds image recognition capacity in order to find an element in the webpage.
+With Niobium, you can keep using Selenium while simplifying your scripts. For example, Niobium adds a new element locator,` By.IMAGE`, which enables image recognition in `WebDriver.find_element` to locate an element on the webpage.
 
 The goal of Niobium is not to replace Selenium. We only want to add to Selenium the functions we will love to see in Selenium natively.
 
@@ -22,36 +22,42 @@ Niobium is available on Pypi, so simply use pip.
 
 In order to use Niobium, you just need to import it in your script. Selenium will be automatically extended. 
 
-    from selenium import webdriver
+```python
     import niobium
+    from selenium import webdriver
 
     driver = webdriver.Firefox()
     driver.implicitly_wait(10)
     driver.get("https://www.python.org/")
 
-    driver.find_element_by_image("logo_python.png")
+    driver.find_element(By.IMAGE, "logo_python.png")
 
     driver.quit()
+```
 
 In order to avoid warning with your linter, you can import selenium from niobium.
 
+```python
     from niobium import selenium
 
     driver = selenium.webdriver.Firefox()
     ...
+```
 
 or simply disable the warning, like in this example for flake8
 
-    from selenium import webdriver
+```python
     import niobium  # noqa: F401
+    from selenium import webdriver
 
     driver = webdriver.Firefox()
     ...
+```
 
 If you use *pytest* and especially *pytest-selenium*, just import niobium in your `conftest.py`.
 
 ## Warnings
 
 Some features implemented in Niobium are here only to help you when there is no other easy solution. If you do a bad usage of Niobium features, it can result to a bad performance in your script, or it will be difficult to maintain it. Please read the documentation in order to know the special warnings for the use of these features.
 
-Niobium do not modify the Selenium library package. The patches are only applied at runtime.
+Niobium do not modify the Selenium library package. The patches are only applied at runtime. This is the reason why the autocompletion is not updated correctly.

docs/webelement_action.md

@@ -1,21 +1,27 @@
 # WebElement new actions
 
-Niobium make easier the mouse action on a WebElement.
+Niobium make easier the mouse action on a `WebElement`.
 
 ## Click with offset
 
 You can click to a specific location related to the top left corner of the element with the `click_at(xoffset, yoffset)` function.
 
-    driver.find_element(By.ID,"myelt").click_at(100, -100) 
+```python
+    driver.find_element(By.ID, "myelt").click_at(100, -100) 
+```
 
 ## Move the cursor over the element
 
 You can move the cursor to the center of the element with the `move_to()` function.
 
-    driver.find_element(By.ID,"myelt").move_to()
+```python
+    driver.find_element(By.ID, "myelt").move_to()
+```
 
 ## Move the cursor with offset
 
 You can move the cursor to a specific location related to the top left corner of the element with the `move_at(xoffset, yoffset)` function.
 
-    driver.find_element(By.ID,"myelt").move_at(20, 20)
+```python
+    driver.find_element(By.ID, "myelt").move_at(20, 20)
+```

docs/webelement_wait.md

@@ -1,20 +1,24 @@
 # WebElement excpected conditions
 
-Niobium make easier the waiting of expected conditions on a WebElement.
+Niobium make easier the waiting of expected conditions on a `WebElement`.
 
 ## Wait until element is displayed and enabled
 
-You just have to call the `wait()` function on a WebElement. 
+You just have to call the `wait()` function on a `WebElement`. 
 
-    driver.find_element(By.ID,"myelt").wait()
+```python
+    driver.find_element(By.ID, "myelt").wait()
+```
 
 By default, the timeout is the same the implicitly_wait timeout.
 
 ## Wait using a specific timeout
 
 You can specify the maximum time to wait using the `timeout` argument (in seconds).
 
-    driver.find_element(By.ID,"myelt").wait(timeout=5)
+```python
+    driver.find_element(By.ID, "myelt").wait(timeout=5)
+```
 
 ## Choose expected conditions to wait
 
@@ -27,15 +31,18 @@ Two expected conditions are available:
 
 If value is None, the expected condition is not checked.
 
-    driver.find_element(By.ID,"myelt").wait(displayed=False, enabled=False)
-
-    driver.find_element(By.ID,"myelt").wait(enabled=False)
+```python
+    driver.find_element(By.ID, "myelt").wait(displayed=False,  enabled=False)
 
+    driver.find_element(By.ID, "myelt").wait(enabled=False)
+```
 
 ## Chain action after wait()
 
 You can chain all available actions after the wait.
 
-    driver.find_element(By.ID,"myelt").wait(timeout=5).click()
+```python
+    driver.find_element(By.ID, "myelt").wait(timeout=5).click()
+```
 
 It's usefull when you have to wait until an element is visible before to click on it.

niobium/__init__.py

@@ -1,5 +1,5 @@
 import selenium
-from .patch import (
+from niobium.patch import (
     patch_image,
     patch_timeout,
     patch_webelement_action,
@@ -13,4 +13,4 @@
 
 __all__ = ["selenium"]
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"

niobium/find_image.py

@@ -1,14 +1,27 @@
 import io
+from typing import Optional
+from typing import Union
+
 
 import cv2
 import numpy as np
 from PIL import Image
 from selenium.common.exceptions import NoSuchElementException
 from selenium.common.exceptions import WebDriverException
+from selenium.webdriver.common.by import By as OriginalBy
 from selenium.webdriver.remote.webdriver import WebDriver
+from selenium.webdriver.remote.webelement import WebElement
+
+
+from niobium.image_element import ImageElement
+from niobium.timeout import ImplicitWait
 
-from .image_element import ImageElement
-from .timeout import ImplicitWait
+original_webdriver_find_element = WebDriver.find_element
+original_webdriver_find_elements = WebDriver.find_elements
+
+
+class By(OriginalBy):
+    IMAGE = "image"
 
 
 def match_template(img_src, img_template, threshold=0.9):
@@ -31,7 +44,7 @@ def match_template(img_src, img_template, threshold=0.9):
         return []
 
 
-def find_elements_by_image(self: WebDriver, filename: str):
+def find_elements_by_image(self: WebDriver, filename: str) -> list[ImageElement]:
     """
     Locate all the occurence of an image in the webpage.
 
@@ -57,7 +70,7 @@ def find_elements_by_image(self: WebDriver, filename: str):
     ]
 
 
-def find_element_by_image(self: WebDriver, filename: str):
+def find_element_by_image(self: WebDriver, filename: str) -> ImageElement:
     """
     Locate an image in the webpage.
 
@@ -84,3 +97,21 @@ def find_element_by_image(self: WebDriver, filename: str):
         )
     else:
         return elements[0]
+
+
+def find_element(
+    self: WebDriver, by=By.ID, value: Optional[str] = None
+) -> Union[WebElement, ImageElement]:
+    if by == By.IMAGE and value is not None:
+        return find_element_by_image(self, value)
+    else:
+        return original_webdriver_find_element(self, by, value)
+
+
+def find_elements(
+    self: WebDriver, by=By.ID, value: Optional[str] = None
+) -> Union[list[WebElement], list[ImageElement]]:
+    if by == By.IMAGE and value is not None:
+        return find_elements_by_image(self, value)
+    else:
+        return original_webdriver_find_elements(self, by, value)