Automaton Tools module
======================
The automaton tools module provide an abstraction of the selenium web driver through a "BrowserServer" object.
Note on documentation
=====================
The documentation is build upon the doctest's files. It includes some weird sections such as "Teardown"
section: Don't be afraid is testing part ;)
Documentation is on [ReadTheDocs](https://eaiwebautomationtools.readthedocs.io)
System requirements
===================
This module has been developed with Python 3.7 and uses selenium version 3.14.
All code is accessible on [GitHub](https://github.com/Hidden-goblin/eaiwebautomationtools)
BrowserServer object
=====================
The BrowserServer is packaged with the webdriver-manager. You can require:
- chrome
- headless-chrome
- firefox
- edge
- opera
- safari (it's not managed by webdriver-manager: you have to provide the path to the webdriver)
Serve the webdriver
-------------------
When everything is set you can call "serve()" method which open the browser of the specified type.
You can stop the webdriver by invoking the "close()" method.
Interacting with the browser
============================
The main feature is unifying the way you choose to interact with the browser.
An element is described by a dictionary in which we give a type and a value.
The **type** is one of the following:
- id: the element identifier,
- name: the element name,
- class\_name: the element class name,
- css: the element css path,
- link\_text: the link full text,
- partial\_link\_text: the link partial text,
- tag\_name: the element tag name
- xpath: the element xpath
The **value** contains the actual value for the **type**. For example an element with the "id" type must have
the id's value to be correctly defined. In the same way an element with the "tag_name" type and a value "div" may return all div on the web page.
To avoid, as much as possible, this multi-definition you can add a **text** dictionary key which try to locate the element with this exact text. **You may find an element with an empty text so use it with care.**
Although the BrowserServer class is a must have, you can use the module spaces separately. I will quickly present here only the BrowserServer class method but the module spaces functions only add a "driver" attribute which hold the selemium web driver to use.
finders
-------
This module space is about finding and returning web element.
- find\_element(field,\[web_element\]): return the first element which match the criteria. Use the web_element as base element in order to find nested element.
- find\_elements(field, \[web_element\]): return all elements which match the criteria in a list. Use the web_element as base element in order to find nested element.
- find\_from\_elements(field,text, \[web_element\]): return the first element which match the criteria and has the text. Use the web_element as base element in order to find nested element.
information
-----------
This module space is about retrieving data from the web page or the browser.
- is\_field\_exist(field,until): return the first element which match the criteria within "until" second. Return None otherwise.
- is\_field\_contains\_text(field,text): return true if the field contains the text even in the value, false otherwise.
- is\_alert\_present(until): return true if an alert is present within "until" second.
- element\_text(field): return the field text.
- how\_many\_windows(): return the number of opened windows.
- is\_field\_displayed(field): return true if the field is displayed.
- is\_field\_enabled(field): return true if the field is enabled.
navigators
----------
This module space is about browsing tag and web browsing.
- go\_to\_url(url): return 0 if successful and go to the specified url.
- enter\_frame(field): return 0 if successful and enter the page frame/iframe.
- go\_to\_window(handle,title): return 0 if successful and gain focus on the window defined by its handle ot its title.
alerts
------
This module space is about the alert popups.
- intercept\_alert(messages, accept, value): return 0 if successful. You can specify a list of message which one must be displayed on the alert, accept or reject the alert (Ok or dimiss) and enter a value where the alert prompt for a user input.
- alert\_message(): return the alert message if an alert is displayed.
actions
-------
This module space is about filling, selecting and clicking on web element.
- fill\_element(field,value): return 0 if successful, fill the field with the value
- fill\_elements(fields, data): return 0 if successful, fill each field in the fields dictionary with the value hold in the data dictionary. You can have a larger fields dictionary than the data but each data entry must be found in the fields dictionary.
- select\_in\_dropdown(field,visible\_text,value): return 0 if successful, select in the field dropdown the element either described by its visible text or its hidden value.
- click\_element(field): return 0 if successful, perform a left click on the field.
- mouse\_click(field): return 0 if successful, perform a chain action moving the mouse on the element and mouse click element.
- set\_checked(field,is\_checked): return 0 if successful, set the checkbox field so that the is\_checked value is always true i.e. checked if is\_checked set to true and not checked if is\_checked set to false.
Other documentation
===================
Please find in the test folder doctest files which describe almost all methods here.
Moreover don't hesitate to use the python help(method/class) directly from the python console in order to access the docstring.
To Do
=====
- Add a multi-selection for dropdown
- Add a drag & drop functionality
- Add a get handles functionality
Release Notes
=============
- version 1.1.9:
- update path to find ChromeType in webdriver-manager package
- version 1.1.8:
- add information method to check if an element is in the viewport
- browserServer.is\_element\_in\_viewport(field, [webElement])
- information.is\_field\_in\_viewport(driver, field, [webElement])
- version 1.1.7:
- Rewrite __serve_chrome method to lower complexity
- version 1.1.6:
- replace `selenium.webdriver.chrome.options.Options.headless` with `selenium.webdriver.chrome.options.Options.add_argument("--headless")`.
No clue on the reason the previous behaviour stopped working.
- version 1.1.5:
- fix removal of opera from webdriver
- `click_element` raise NoSuchElementException when element is not found
- version 1.1.4:
- fix merge issue
- version 1.1.3:
- update import following webdriver manager change packaging structure
- version 1.1.2:
- fix missing version in headless webdriver
- version 1.1.1:
- add browser_version attribute. It allows to specify a browser version so that the webdriver manager will use this specific version.
- version 1.1.0:
- add selenium 4 support. Relative locator are not included in the current "field" model
- version 1.0.14:
- fix missing `web_element` variable in `BrowserServer.set_checkbox` method
- add `mouse_click` method in the actions
- version 1.0.13:
- fix missing `avoid_move_to` passing value to find_from_elements when using find_element in conjunction with `text` parameter.
- version 1.0.12:
- lower log level for finder(s) actions
- add wait_for_another_window in information
- add typing annotations and minimal docstring on BrowserServer
- fix test_01_01
- fix case browser_name is None
- version 1.0.11:
- lower log level for polling actions
- version 1.0.10:
- add chromium from DriverManager in BrowserServer
- version 1.0.9:
- actions and finders return None if element not found
- version 1.0.8:
- add avoid_move_to option on find_element in order to retrieve an element without moving to it
- add minor tests
- version 1.0.7:
- add caller_message to move_to method in order to track down issue in the logs
- add execute_script method to BrowserServer
- is_displayed polls every 0.2s for 10s in order to check if field is displayed
- is_field_exist polls even with StaleElementReferenceException
- use polling2 instead of webdriver wait where applicable
- version 1.0.6:
- new test server: now using flask as a test server
- use mkdocs and the doctest test repository in order to build the documentation
- add diver option setter
- add a generic move_to web element method
- version 1.0.5: Sorry for the interruption
- use webdriver manager in order to retrieve webdrivers.
- Enhance the webdriver handling.
- Allow providing a WebElement to find nested element(s).
- Enhance doctest coverage.
- Minor refactoring
- version 0.1: first release
Raw data
{
"_id": null,
"home_page": "https://eaiwebautomationtools.readthedocs.io/",
"name": "eaiautomatontools",
"maintainer": null,
"docs_url": null,
"requires_python": "!=2.*,>=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Eric A\u00efvayan",
"author_email": "eric.aivayan@free.fr",
"download_url": "https://files.pythonhosted.org/packages/7a/08/a3fcd808708521e62156394b6a6f88b9f53855ef880ad241fa2ff7e36549/eaiautomatontools-1.2.0.tar.gz",
"platform": null,
"description": "Automaton Tools module\n======================\n\nThe automaton tools module provide an abstraction of the selenium web driver through a \"BrowserServer\" object.\n\nNote on documentation\n=====================\n\nThe documentation is build upon the doctest's files. It includes some weird sections such as \"Teardown\" \nsection: Don't be afraid is testing part ;)\n\nDocumentation is on [ReadTheDocs](https://eaiwebautomationtools.readthedocs.io)\n\nSystem requirements\n===================\n\nThis module has been developed with Python 3.7 and uses selenium version 3.14.\n\nAll code is accessible on [GitHub](https://github.com/Hidden-goblin/eaiwebautomationtools)\n\nBrowserServer object\n=====================\n\nThe BrowserServer is packaged with the webdriver-manager. You can require:\n\n- chrome\n- headless-chrome\n- firefox\n- edge\n- opera\n- safari (it's not managed by webdriver-manager: you have to provide the path to the webdriver)\n\n\nServe the webdriver\n-------------------\n\nWhen everything is set you can call \"serve()\" method which open the browser of the specified type.\n\nYou can stop the webdriver by invoking the \"close()\" method.\n\nInteracting with the browser\n============================\n\nThe main feature is unifying the way you choose to interact with the browser.\n\nAn element is described by a dictionary in which we give a type and a value.\n\nThe **type** is one of the following:\n\n- id: the element identifier,\n- name: the element name,\n- class\\_name: the element class name,\n- css: the element css path,\n- link\\_text: the link full text,\n- partial\\_link\\_text: the link partial text,\n- tag\\_name: the element tag name\n- xpath: the element xpath\n\n\n\nThe **value** contains the actual value for the **type**. For example an element with the \"id\" type must have \nthe id's value to be correctly defined. In the same way an element with the \"tag_name\" type and a value \"div\" may return all div on the web page.\n\nTo avoid, as much as possible, this multi-definition you can add a **text** dictionary key which try to locate the element with this exact text. **You may find an element with an empty text so use it with care.**\n\nAlthough the BrowserServer class is a must have, you can use the module spaces separately. I will quickly present here only the BrowserServer class method but the module spaces functions only add a \"driver\" attribute which hold the selemium web driver to use.\n\nfinders\n-------\n\nThis module space is about finding and returning web element.\n\n- find\\_element(field,\\[web_element\\]): return the first element which match the criteria. Use the web_element as base element in order to find nested element. \n- find\\_elements(field, \\[web_element\\]): return all elements which match the criteria in a list. Use the web_element as base element in order to find nested element.\n- find\\_from\\_elements(field,text, \\[web_element\\]): return the first element which match the criteria and has the text. Use the web_element as base element in order to find nested element.\n\ninformation\n-----------\n\nThis module space is about retrieving data from the web page or the browser.\n\n- is\\_field\\_exist(field,until): return the first element which match the criteria within \"until\" second. Return None otherwise.\n- is\\_field\\_contains\\_text(field,text): return true if the field contains the text even in the value, false otherwise.\n- is\\_alert\\_present(until): return true if an alert is present within \"until\" second.\n- element\\_text(field): return the field text.\n- how\\_many\\_windows(): return the number of opened windows.\n- is\\_field\\_displayed(field): return true if the field is displayed.\n- is\\_field\\_enabled(field): return true if the field is enabled.\n\nnavigators\n----------\n\nThis module space is about browsing tag and web browsing.\n\n- go\\_to\\_url(url): return 0 if successful and go to the specified url.\n- enter\\_frame(field): return 0 if successful and enter the page frame/iframe.\n- go\\_to\\_window(handle,title): return 0 if successful and gain focus on the window defined by its handle ot its title.\n\nalerts\n------\n\nThis module space is about the alert popups.\n\n- intercept\\_alert(messages, accept, value): return 0 if successful. You can specify a list of message which one must be displayed on the alert, accept or reject the alert (Ok or dimiss) and enter a value where the alert prompt for a user input. \n- alert\\_message(): return the alert message if an alert is displayed.\n\nactions\n-------\n\nThis module space is about filling, selecting and clicking on web element.\n\n- fill\\_element(field,value): return 0 if successful, fill the field with the value\n- fill\\_elements(fields, data): return 0 if successful, fill each field in the fields dictionary with the value hold in the data dictionary. You can have a larger fields dictionary than the data but each data entry must be found in the fields dictionary. \n- select\\_in\\_dropdown(field,visible\\_text,value): return 0 if successful, select in the field dropdown the element either described by its visible text or its hidden value. \n- click\\_element(field): return 0 if successful, perform a left click on the field.\n- mouse\\_click(field): return 0 if successful, perform a chain action moving the mouse on the element and mouse click element.\n- set\\_checked(field,is\\_checked): return 0 if successful, set the checkbox field so that the is\\_checked value is always true i.e. checked if is\\_checked set to true and not checked if is\\_checked set to false.\n\nOther documentation\n===================\n\nPlease find in the test folder doctest files which describe almost all methods here.\n\nMoreover don't hesitate to use the python help(method/class) directly from the python console in order to access the docstring.\n\nTo Do\n=====\n\n- Add a multi-selection for dropdown\n- Add a drag & drop functionality\n- Add a get handles functionality\n\nRelease Notes\n=============\n- version 1.1.9:\n - update path to find ChromeType in webdriver-manager package\n- version 1.1.8:\n - add information method to check if an element is in the viewport\n - browserServer.is\\_element\\_in\\_viewport(field, [webElement])\n - information.is\\_field\\_in\\_viewport(driver, field, [webElement])\n- version 1.1.7:\n - Rewrite __serve_chrome method to lower complexity\n- version 1.1.6:\n - replace `selenium.webdriver.chrome.options.Options.headless` with `selenium.webdriver.chrome.options.Options.add_argument(\"--headless\")`.\nNo clue on the reason the previous behaviour stopped working.\n- version 1.1.5:\n - fix removal of opera from webdriver\n - `click_element` raise NoSuchElementException when element is not found\n- version 1.1.4:\n - fix merge issue\n- version 1.1.3:\n - update import following webdriver manager change packaging structure\n- version 1.1.2:\n - fix missing version in headless webdriver\n- version 1.1.1:\n - add browser_version attribute. It allows to specify a browser version so that the webdriver manager will use this specific version.\n- version 1.1.0:\n - add selenium 4 support. Relative locator are not included in the current \"field\" model\n- version 1.0.14:\n - fix missing `web_element` variable in `BrowserServer.set_checkbox` method\n - add `mouse_click` method in the actions\n- version 1.0.13:\n - fix missing `avoid_move_to` passing value to find_from_elements when using find_element in conjunction with `text` parameter. \n- version 1.0.12:\n - lower log level for finder(s) actions\n - add wait_for_another_window in information\n - add typing annotations and minimal docstring on BrowserServer\n - fix test_01_01\n - fix case browser_name is None\n- version 1.0.11:\n - lower log level for polling actions\n- version 1.0.10:\n - add chromium from DriverManager in BrowserServer\n- version 1.0.9:\n - actions and finders return None if element not found \n- version 1.0.8:\n - add avoid_move_to option on find_element in order to retrieve an element without moving to it\n - add minor tests\n- version 1.0.7:\n - add caller_message to move_to method in order to track down issue in the logs\n - add execute_script method to BrowserServer\n - is_displayed polls every 0.2s for 10s in order to check if field is displayed\n - is_field_exist polls even with StaleElementReferenceException\n - use polling2 instead of webdriver wait where applicable\n- version 1.0.6:\n - new test server: now using flask as a test server\n - use mkdocs and the doctest test repository in order to build the documentation\n - add diver option setter\n - add a generic move_to web element method\n- version 1.0.5: Sorry for the interruption \n - use webdriver manager in order to retrieve webdrivers. \n - Enhance the webdriver handling.\n - Allow providing a WebElement to find nested element(s).\n - Enhance doctest coverage.\n - Minor refactoring\n- version 0.1: first release\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "UI utilities in order to abstract selenium commands",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://eaiwebautomationtools.readthedocs.io/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3123dc40e38f85adcc7e75056eee99968a0198cc310f0e2d7f31923cb9a38e02",
"md5": "7a3e52dec9c8e0f61ad31bdbe26227c6",
"sha256": "1226f2ba21293594c7597a50c9ea3edefd95abaaf2cdaed635d0f777329e8832"
},
"downloads": -1,
"filename": "eaiautomatontools-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a3e52dec9c8e0f61ad31bdbe26227c6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "!=2.*,>=3.7",
"size": 43721,
"upload_time": "2024-08-24T19:47:52",
"upload_time_iso_8601": "2024-08-24T19:47:52.381709Z",
"url": "https://files.pythonhosted.org/packages/31/23/dc40e38f85adcc7e75056eee99968a0198cc310f0e2d7f31923cb9a38e02/eaiautomatontools-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7a08a3fcd808708521e62156394b6a6f88b9f53855ef880ad241fa2ff7e36549",
"md5": "16696739e25496676f46b51692cd8418",
"sha256": "819a6d77f3b291cfc788d18b5ac9d00f1adc8240f96c9bbee79c03d21182e4de"
},
"downloads": -1,
"filename": "eaiautomatontools-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "16696739e25496676f46b51692cd8418",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "!=2.*,>=3.7",
"size": 50941,
"upload_time": "2024-08-24T19:47:53",
"upload_time_iso_8601": "2024-08-24T19:47:53.933443Z",
"url": "https://files.pythonhosted.org/packages/7a/08/a3fcd808708521e62156394b6a6f88b9f53855ef880ad241fa2ff7e36549/eaiautomatontools-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-24 19:47:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "eaiautomatontools"
}
JSON