# croco-selenium
<a href="https://github.com/CrocoFactory"><img alt="Croco Logo" src="https://raw.githubusercontent.com/CrocoFactory/.github/main/branding/logo/bookmark_rounded.png" width="100"></a>
[](https://pypi.org/project/croco-selenium/)
[](https://pypi.org/project/croco-selenium/)
[](https://pypi.org/project/croco-selenium/)
[](https://pypi.org/project/croco-selenium/)
[](https://pypi.org/project/croco-selenium/)
The package providing ways to interact with Selenium Web Driver actions, such as clicking, sending keys etc.
- **[Bug reports](https://github.com/CrocoFactory/croco-selenium/issues)**
- **[Actions Overview](#actions-overview)**
When we use Selenium, it's not convenient to use WebDriverWait with its cluttered chain actions. Instead of many imports
and instances (By, WebDriverWait, expected_conditions) you can use fast and robust actions.
Package's source code is made available under the [MIT License](LICENSE)
The project is made by the **[Croco Factory](https://github.com/CrocoFactory)** team
# Quick Start
You can use actions, by the following way.
```python
from selenium.webdriver.chrome.webdriver import WebDriver
from croco_selenium import click
driver = WebDriver()
click(driver, 10, '//input[@type="submit"]')
```
If you don't want to pass driver every using of actions, you can create an instance of ActionPerformer
```python
from selenium.webdriver.chrome.webdriver import WebDriver
from croco_selenium import ActionPerformer
driver = WebDriver()
action_performer = ActionPerformer(driver)
timeout = 10
action_performer.send_keys(timeout, '//input[@type="password"]', 'password')
action_performer.click(timeout, '//input[@type="submit"]')
```
One of the best ways to use actions is create an instance of ChromeDriver and perform
actions by calling methods on it. That class derived from ActionPerformer and ChromiumDriver
```python
import os
from croco_selenium import ChromeDriver, Proxy
proxy = Proxy(host='123.89.46.72', port=8000, username='croco', password='webDriver')
project_dir = os.path.dirname(os.path.abspath(__file__))
extension_paths = [os.path.join(project_dir, 'extensions/metamask.crx')]
driver = ChromeDriver(proxy=proxy, extension_paths=extension_paths)
driver.get('https://facebook.com')
driver.send_keys(15, '//input[@id="email"]', 'hello@world.com')
```
# Actions Overview
You can perform the following [actions](#actions), using croco-selenium:
- **[add_cookies](#add_cookies)**
- **[click](#click)**
- **[close_tabs](#close_tabs)**
- **[get_element](#get_element)**
- **[get_elements](#get_elements)**
- **[get_element_attribute](#get_element_attribute)**
- **[get_element_text](#get_element_text)**
- **[send_keys](#send_keys)**
- **[silent_send_keys](#silent_send_keys)**
- **[switch_to_another_window](#switch_to_another_window)**
- **[switch_to_frame](#switch_to_frame)**
- **[switch_to_parent_frame](#switch_to_parent_frame)**
- **[wait_for_invisibility](#wait_for_invisibility)**
- **[wait_for_windows](#wait_for_windows)**
And there are 3 useful [decorators](#decorators):
- **[handle_pop_up](#handle_pop_up)**
- **[handle_in_new_tab](#handle_in_new_tab)**
- **[handle_new_tab](#handle_new_tab)**
## Actions
<h3 id="add_cookies">add_cookies</h3>
Adds cookies to a current page. It takes valid string containing json, list of cookies or one cookie as dictionary.
```python
from croco_selenium import ChromeDriver
timeout = 10
driver = ChromeDriver()
cookies = '{"domain":".facebook.com","expirationDate":1689249734,"httpOnly":true,"name":"c_user","path":"/","secure":true,"value":"100083466604886"}'
driver.get('facebook.com')
driver.add_cookies(cookies)
```
<h3 id="click">click</h3>
Clicks on element in browser
```python
from croco_selenium import ChromeDriver
timeout = 10
driver = ChromeDriver()
driver.click(timeout, '//input[@type="submit"]')
```
<h3 id="close_tabs">close_tabs</h3>
Closes all tabs in browser. It's convenient to use, when you add extensions to your browser and their windows occur with
starting a driver.
```python
import os
from croco_selenium import ChromeDriver
project_dir = os.path.dirname(os.path.abspath(__file__))
extension_paths = [os.path.join(project_dir, 'extensions/metamask.crx')]
driver = ChromeDriver(extension_paths=extension_paths)
driver.close_tabs()
driver.get('https://facebook.com')
driver.send_keys(15, '//input[@id="email"]', 'hello@world.com')
```
<h3 id="get_element">get_element</h3>
Returns an element in browser
```python
from croco_selenium import ChromeDriver
timeout = 10
driver = ChromeDriver()
element = driver.get_element(timeout, '//input[@type="submit"]')
element.click()
```
<h3 id="get_elements">get_elements</h3>
Returns an elements in browser
```python
from croco_selenium import ChromeDriver
timeout = 10
driver = ChromeDriver()
elements = driver.get_elements(timeout, '//input')
for element in elements:
element.click()
```
<h3 id="get_element_attribute">get_element_attribute</h3>
Returns an element's attribute in browser
```python
from croco_selenium import ChromeDriver
timeout = 10
driver = ChromeDriver()
assert driver.get_element_attribute(timeout, '//input[@type="checkbox"]', 'checked')
```
<h3 id="get_element_text">get_element_text</h3>
Returns element's text in browser
```python
from croco_selenium import ChromeDriver
timeout = 10
driver = ChromeDriver()
print(driver.get_element_text(timeout, '//h1'))
```
<h3 id="send_keys">send_keys</h3>
Sends keys in browser
```python
from croco_selenium import ChromeDriver
timeout = 10
driver = ChromeDriver()
driver.send_keys(timeout, '//input[@type="password"]', 'password')
driver.click(timeout, '//input[@type="submit"]')
```
<h3 id="silent_send_keys">silent_send_keys</h3>
Sends keys with delay between characters in browser. It's convenient to use when you would like to hide your bot activity
```python
from croco_selenium import ChromeDriver
timeout = 10
driver = ChromeDriver()
driver.silent_send_keys(timeout, '//input[@type="password"]', 'password')
driver.click(timeout, '//input[@type="submit"]')
```
<h3 id="switch_to_another_window">switch_to_another_window</h3>
Switches to a different window from current window in browser. It's convenient to use, when you have two windows to be handled
```python
from croco_selenium import ChromeDriver
timeout = 10
driver = ChromeDriver()
driver.silent_send_keys(timeout, '//input[@type="password"]', 'password')
driver.click(timeout, '//input[@type="submit"]')
driver.switch_to_another_window(timeout)
driver.click(timeout, '//input[@type="submit"]')
driver.switch_to_another_window(timeout)
```
<h3 id="switch_to_frame">switch_to_frame</h3>
Switches to the frame
```python
from croco_selenium import ChromeDriver
timeout = 10
driver = ChromeDriver()
driver.switch_to_frame(timeout, '//iframe[@data-hcaptcha-widget-id]')
driver.click(timeout, '//input[@type="submit"]')
```
<h3 id="switch_to_parent_frame">switch_to_parent_frame</h3>
Switches to the parent frame
```python
from croco_selenium import ChromeDriver
timeout = 10
driver = ChromeDriver()
driver.switch_to_frame(timeout, '//iframe[@data-hcaptcha-widget-id]')
driver.click(timeout, '//input[@type="submit"]')
driver.switch_to_parent_frame()
```
<h3 id="wait_for_invisibility">wait_for_invisibility</h3>
Wait for element's invisibility in browser
```python
from croco_selenium import ChromeDriver
timeout = 10
driver = ChromeDriver()
driver.click(timeout, '//button')
driver.wait_for_invisibility(timeout, '//*[@id="popup"]')
```
<h3 id="wait_for_windows">wait_for_windows</h3>
Wait for occurring of number of windows
```python
from croco_selenium import ChromeDriver
timeout = 10
driver = ChromeDriver()
driver.wait_for_windows(timeout, 2)
```
## Decorators
<h3 id="handle_pop_up">handle_pop_up</h3>
Switches to another window, performs decorated function and switches back. Pop up has to be closed after performing
decorated function.
This decorator is usually used for browser extensions' pop-ups. Example of function performing
a third-party Metamask connection:
```python
from croco_selenium import ChromeDriver, handle_pop_up
from selenium.common import TimeoutException
@handle_pop_up()
def connect(driver: ChromeDriver, password: str) -> None:
try:
password_xpath = '//*[@id="password"]'
driver.send_keys(7, password_xpath, password)
unlock_xpath = '//button[@data-testid="unlock-submit"]'
driver.click(5, unlock_xpath)
except TimeoutException:
pass
for _ in range(3):
next_xpath = '//button[@data-testid="page-container-footer-next"]'
driver.click(10, next_xpath, ignored_exceptions=TimeoutException)
```
<h3 id="handle_in_new_tab">handle_in_new_tab</h3>
Opens new tab, performs decorated function, closes new tab and switches back. Here is example of function performing
getting of 2FA code from browser extension.
```python
from croco_selenium import ChromeDriver, handle_in_new_tab
@handle_in_new_tab()
def get_code(driver: ChromeDriver, account) -> str:
timeout = 15
driver.get('<EXTENSION_URL>')
code_field_xpath = '//*[contains(@class, "code")]'
code_fields = driver.get_elements(timeout, code_field_xpath)
code_field = code_fields[account.id]
code = code_field.text
return code
```
<h3 id="handle_new_tab">handle_new_tab</h3>
Performs decorated function in new tab and switches back. New tab has to be opened during performing decorated function.
# Installing croco-selenium
To install the package from PyPi you can use:
```sh
pip install croco-selenium
```
To install the package from GitHub you can use:
```sh
pip install git+https://github.com/CrocoFactory/croco-selenium.git
```
Raw data
{
"_id": null,
"home_page": "https://github.com/CrocoFactory/croco-selenium",
"name": "croco_selenium",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": null,
"author": "Alexey",
"author_email": "axbelenkov@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a5/09/e46c6c43324d00fbaf10db49a0f6300bf3ae3404ba34896c67b0f67a093c/croco_selenium-0.1.6.post2.tar.gz",
"platform": null,
"description": "# croco-selenium\n\n<a href=\"https://github.com/CrocoFactory\"><img alt=\"Croco Logo\" src=\"https://raw.githubusercontent.com/CrocoFactory/.github/main/branding/logo/bookmark_rounded.png\" width=\"100\"></a>\n\n[](https://pypi.org/project/croco-selenium/)\n[](https://pypi.org/project/croco-selenium/)\n[](https://pypi.org/project/croco-selenium/)\n[](https://pypi.org/project/croco-selenium/)\n[](https://pypi.org/project/croco-selenium/) \n\nThe package providing ways to interact with Selenium Web Driver actions, such as clicking, sending keys etc.\n \n- **[Bug reports](https://github.com/CrocoFactory/croco-selenium/issues)**\n- **[Actions Overview](#actions-overview)**\n\nWhen we use Selenium, it's not convenient to use WebDriverWait with its cluttered chain actions. Instead of many imports \nand instances (By, WebDriverWait, expected_conditions) you can use fast and robust actions.\n\nPackage's source code is made available under the [MIT License](LICENSE)\n\nThe project is made by the **[Croco Factory](https://github.com/CrocoFactory)** team\n\n# Quick Start\n \nYou can use actions, by the following way.\n\n```python\nfrom selenium.webdriver.chrome.webdriver import WebDriver\nfrom croco_selenium import click\ndriver = WebDriver()\nclick(driver, 10, '//input[@type=\"submit\"]')\n```\n\nIf you don't want to pass driver every using of actions, you can create an instance of ActionPerformer\n\n```python\nfrom selenium.webdriver.chrome.webdriver import WebDriver\nfrom croco_selenium import ActionPerformer\ndriver = WebDriver()\naction_performer = ActionPerformer(driver)\ntimeout = 10\n\naction_performer.send_keys(timeout, '//input[@type=\"password\"]', 'password')\naction_performer.click(timeout, '//input[@type=\"submit\"]')\n```\n\nOne of the best ways to use actions is create an instance of ChromeDriver and perform \nactions by calling methods on it. That class derived from ActionPerformer and ChromiumDriver\n\n```python\nimport os\nfrom croco_selenium import ChromeDriver, Proxy\nproxy = Proxy(host='123.89.46.72', port=8000, username='croco', password='webDriver')\nproject_dir = os.path.dirname(os.path.abspath(__file__))\nextension_paths = [os.path.join(project_dir, 'extensions/metamask.crx')]\n\ndriver = ChromeDriver(proxy=proxy, extension_paths=extension_paths)\ndriver.get('https://facebook.com')\ndriver.send_keys(15, '//input[@id=\"email\"]', 'hello@world.com')\n```\n\n# Actions Overview\nYou can perform the following [actions](#actions), using croco-selenium:\n\n- **[add_cookies](#add_cookies)**\n- **[click](#click)**\n- **[close_tabs](#close_tabs)**\n- **[get_element](#get_element)**\n- **[get_elements](#get_elements)**\n- **[get_element_attribute](#get_element_attribute)**\n- **[get_element_text](#get_element_text)**\n- **[send_keys](#send_keys)**\n- **[silent_send_keys](#silent_send_keys)**\n- **[switch_to_another_window](#switch_to_another_window)**\n- **[switch_to_frame](#switch_to_frame)**\n- **[switch_to_parent_frame](#switch_to_parent_frame)**\n- **[wait_for_invisibility](#wait_for_invisibility)**\n- **[wait_for_windows](#wait_for_windows)**\n\nAnd there are 3 useful [decorators](#decorators):\n\n- **[handle_pop_up](#handle_pop_up)**\n- **[handle_in_new_tab](#handle_in_new_tab)**\n- **[handle_new_tab](#handle_new_tab)**\n \n## Actions\n\n<h3 id=\"add_cookies\">add_cookies</h3>\nAdds cookies to a current page. It takes valid string containing json, list of cookies or one cookie as dictionary.\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ncookies = '{\"domain\":\".facebook.com\",\"expirationDate\":1689249734,\"httpOnly\":true,\"name\":\"c_user\",\"path\":\"/\",\"secure\":true,\"value\":\"100083466604886\"}'\ndriver.get('facebook.com')\ndriver.add_cookies(cookies)\n```\n\n<h3 id=\"click\">click</h3>\nClicks on element in browser\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\ndriver.click(timeout, '//input[@type=\"submit\"]')\n```\n\n<h3 id=\"close_tabs\">close_tabs</h3>\nCloses all tabs in browser. It's convenient to use, when you add extensions to your browser and their windows occur with \nstarting a driver.\n\n```python\nimport os\nfrom croco_selenium import ChromeDriver\n\nproject_dir = os.path.dirname(os.path.abspath(__file__))\nextension_paths = [os.path.join(project_dir, 'extensions/metamask.crx')]\n\ndriver = ChromeDriver(extension_paths=extension_paths)\ndriver.close_tabs()\ndriver.get('https://facebook.com')\ndriver.send_keys(15, '//input[@id=\"email\"]', 'hello@world.com')\n```\n\n<h3 id=\"get_element\">get_element</h3>\nReturns an element in browser\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\nelement = driver.get_element(timeout, '//input[@type=\"submit\"]')\nelement.click()\n```\n\n<h3 id=\"get_elements\">get_elements</h3>\nReturns an elements in browser\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\nelements = driver.get_elements(timeout, '//input')\n\nfor element in elements:\n element.click()\n```\n\n<h3 id=\"get_element_attribute\">get_element_attribute</h3>\nReturns an element's attribute in browser\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\nassert driver.get_element_attribute(timeout, '//input[@type=\"checkbox\"]', 'checked')\n```\n\n<h3 id=\"get_element_text\">get_element_text</h3>\nReturns element's text in browser\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\nprint(driver.get_element_text(timeout, '//h1'))\n```\n\n<h3 id=\"send_keys\">send_keys</h3>\nSends keys in browser\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ndriver.send_keys(timeout, '//input[@type=\"password\"]', 'password')\ndriver.click(timeout, '//input[@type=\"submit\"]')\n```\n\n<h3 id=\"silent_send_keys\">silent_send_keys</h3>\nSends keys with delay between characters in browser. It's convenient to use when you would like to hide your bot activity\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ndriver.silent_send_keys(timeout, '//input[@type=\"password\"]', 'password')\ndriver.click(timeout, '//input[@type=\"submit\"]')\n```\n\n<h3 id=\"switch_to_another_window\">switch_to_another_window</h3>\nSwitches to a different window from current window in browser. It's convenient to use, when you have two windows to be handled\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ndriver.silent_send_keys(timeout, '//input[@type=\"password\"]', 'password')\ndriver.click(timeout, '//input[@type=\"submit\"]')\ndriver.switch_to_another_window(timeout)\n\ndriver.click(timeout, '//input[@type=\"submit\"]')\ndriver.switch_to_another_window(timeout)\n```\n\n<h3 id=\"switch_to_frame\">switch_to_frame</h3>\nSwitches to the frame\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ndriver.switch_to_frame(timeout, '//iframe[@data-hcaptcha-widget-id]')\ndriver.click(timeout, '//input[@type=\"submit\"]')\n```\n\n<h3 id=\"switch_to_parent_frame\">switch_to_parent_frame</h3>\nSwitches to the parent frame\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ndriver.switch_to_frame(timeout, '//iframe[@data-hcaptcha-widget-id]')\ndriver.click(timeout, '//input[@type=\"submit\"]')\ndriver.switch_to_parent_frame()\n```\n\n<h3 id=\"wait_for_invisibility\">wait_for_invisibility</h3>\nWait for element's invisibility in browser\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ndriver.click(timeout, '//button')\ndriver.wait_for_invisibility(timeout, '//*[@id=\"popup\"]')\n```\n \n<h3 id=\"wait_for_windows\">wait_for_windows</h3>\nWait for occurring of number of windows\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ndriver.wait_for_windows(timeout, 2)\n```\n\n## Decorators\n<h3 id=\"handle_pop_up\">handle_pop_up</h3>\nSwitches to another window, performs decorated function and switches back. Pop up has to be closed after performing\ndecorated function.\n\nThis decorator is usually used for browser extensions' pop-ups. Example of function performing\na third-party Metamask connection:\n\n```python\nfrom croco_selenium import ChromeDriver, handle_pop_up\nfrom selenium.common import TimeoutException\n\n@handle_pop_up()\ndef connect(driver: ChromeDriver, password: str) -> None:\n try:\n password_xpath = '//*[@id=\"password\"]'\n driver.send_keys(7, password_xpath, password)\n\n unlock_xpath = '//button[@data-testid=\"unlock-submit\"]'\n driver.click(5, unlock_xpath)\n except TimeoutException:\n pass\n\n for _ in range(3):\n next_xpath = '//button[@data-testid=\"page-container-footer-next\"]'\n driver.click(10, next_xpath, ignored_exceptions=TimeoutException)\n```\n\n<h3 id=\"handle_in_new_tab\">handle_in_new_tab</h3>\nOpens new tab, performs decorated function, closes new tab and switches back. Here is example of function performing \ngetting of 2FA code from browser extension.\n\n```python\nfrom croco_selenium import ChromeDriver, handle_in_new_tab\n\n@handle_in_new_tab()\ndef get_code(driver: ChromeDriver, account) -> str:\n timeout = 15\n\n driver.get('<EXTENSION_URL>')\n\n code_field_xpath = '//*[contains(@class, \"code\")]'\n code_fields = driver.get_elements(timeout, code_field_xpath)\n\n code_field = code_fields[account.id]\n\n code = code_field.text\n return code\n```\n\n<h3 id=\"handle_new_tab\">handle_new_tab</h3>\nPerforms decorated function in new tab and switches back. New tab has to be opened during performing decorated function.\n\n\n# Installing croco-selenium\n\nTo install the package from PyPi you can use: \n\n```sh\npip install croco-selenium\n```\n \nTo install the package from GitHub you can use:\n\n```sh\npip install git+https://github.com/CrocoFactory/croco-selenium.git\n```",
"bugtrack_url": null,
"license": "MIT",
"summary": "The package providing ways to interact with Selenium Web Driver actions, such as clicking, sending keys etc.",
"version": "0.1.6.post2",
"project_urls": {
"Homepage": "https://github.com/CrocoFactory/croco-selenium",
"Repository": "https://github.com/CrocoFactory/croco-selenium"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "227f464ff3a72903b7b10627864ec4cfda980b7f44cb594fdd160c3fc9b47904",
"md5": "ecff108181c391a711b419a8e35c4aec",
"sha256": "f6a64330e0964c019cc71a41f3676b3648e0dd3a083b38ca46c9b0cf4057e5fa"
},
"downloads": -1,
"filename": "croco_selenium-0.1.6.post2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ecff108181c391a711b419a8e35c4aec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 12102,
"upload_time": "2024-09-23T16:27:36",
"upload_time_iso_8601": "2024-09-23T16:27:36.982229Z",
"url": "https://files.pythonhosted.org/packages/22/7f/464ff3a72903b7b10627864ec4cfda980b7f44cb594fdd160c3fc9b47904/croco_selenium-0.1.6.post2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a509e46c6c43324d00fbaf10db49a0f6300bf3ae3404ba34896c67b0f67a093c",
"md5": "94069d7f597b053605ec0f05eed11d89",
"sha256": "1cbbdf6f45b555b213388db02fa18632550e59e7bbf5d0a0c370088c34697d28"
},
"downloads": -1,
"filename": "croco_selenium-0.1.6.post2.tar.gz",
"has_sig": false,
"md5_digest": "94069d7f597b053605ec0f05eed11d89",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 11028,
"upload_time": "2024-09-23T16:27:39",
"upload_time_iso_8601": "2024-09-23T16:27:39.043270Z",
"url": "https://files.pythonhosted.org/packages/a5/09/e46c6c43324d00fbaf10db49a0f6300bf3ae3404ba34896c67b0f67a093c/croco_selenium-0.1.6.post2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-23 16:27:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CrocoFactory",
"github_project": "croco-selenium",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "croco_selenium"
}
JSON
