Pyleniumio

Changed

* **`Element.should().not_exist()` --> `Element.should().disappear()`**

If the intent is to check that the element is not on the page, then use:

python
py.should().not_find()


If the intent is to wait until an existing element does not exist anymore or "disappear", then you used to have to do

python
py.get().should().not_exist()


However, this is clearly confusing because the way `should not exist` reads would suggest that both options are the same. This has now been changed to more clearly reflect that intent.

python
py.get().should().disappear()


* **`Element.should().have_attr()` doesn't require the `value` argument**

There is a scenario when all you want to check on an element is that an attribute exists or not.

Example:

python
py.wait().until(lambda _: toggle.get_attribute('aria-checked'))


Unfortunately, `ElementShould.have_attr()` requires an attribute name AND a value. Trying to use it in this scenario is difficult to use or straight up doesn't work.

python
doesn't work
py.get(TOGGLE).should().have_attr('aria-checked', True)

doesn't work either
py.get(TOGGLE).should().have_attr('aria-checked', '')

this is just confusing...
py.get(TOGGLE).should().not_have_attr('aria-checked', None)

this may work if it sees the custom `aria-checked` attribute as "checked"
py.get(TOGGLE).should().be_checked()


**Solution**

Make the existing expectations not require the `value` argument.

* `should().have_attr(name, value=None)`
* `should().not_have_attr(name, value=None)`

Fixed

* `drag_and_drop.js` was not included in the pylenium installation. Now it is!
* Some typos

Added

This is a bigger change that sets us up for things we want to do with better reporting and BDD functionality. There may be some breaking changes depending how you wrote your tests.

For example, the property of `Element.text` is now a function `Element.text()` and `.find()` no longer has an `at_least_one` parameter.

Make sure you run your tests after upgrading to catch errors like `str is not invocable`. They should be easy to fix.

**PyleniumShould**

The use case of checking that an element is NOT on the page or DOM was much more common than anticipated. I have changed how the `.find()` and `.find_xpath()` functions behave to help with this, but there are now three easy to use "should" commands as well.

* **`.not_find()`**
* **`.not_find_xpath()`**
* **`.not_contain()`**

python
example usage
py.should().not_find('hidden-element')


**Driver**

Having these as properties was actually messing people up as they used Pylenium. Because almost all of the commands are functions, it was common that someone would try `py.url()` or `py.title()` only to see the test fail saying that `str is not invocable`. Changing these to functions feels more natural.

* `.url` property changed to `.url()` function
* `.title` property changed to `.title()` function

**XPaths**

Removed the `.xpath()` function from _Pylenium_ and _Element_ and replaced with `get` and `find` options. The `.xpath()` function _could_ return an empty list, a single element, or a list of 2 or more elements. The flexibility was pretty "clever", but it was not intuitive to work with. Separating it into two distinct functions to match the CSS versions of `get()` and `.find()` made more sense.

* `.get_xpath()`
* `find_xpath()`

python
single element with xpath
py.get_xpath('//input[name="q"]')

list of elements with xpath
py.find_xpath('//li')


**Find Elements**

The `.find()` and `.find_xpath()` functions on the _Pylenium_ and _Element_ objects will now return an empty list if none are found rather than throwing an exception. Dealing with an empty list is easier and cleaner than having to handle an exception.

However, this is not the case If the timeout is set to `0` \(zero\). The next section goes into more detail.

**Immediate Poll with timeout=0**

There are times when you don't want to use an awesome wait and a timeout of 1 second isn't good enough. For all of the _Find Element_ commands, you can now set the timeout to `0` \(zero\) to poll the DOM immediately as if you were using Selenium with no wait.

> This will still return an `Element` or `Elements` object if found, but no _wait_ is used.

Let's take a look at the `.get()` signature:

python
def get(self, css: str, timeout: int = None) -> Element


* If `timeout=None` \(default\), the function will use the default `wait_time` in `pylenium.json` which is 10 seconds.

python
use `wait_time` in pylenium.json
py.get('button').click()


* If `timeout > 0`, override the default wait\_time.

python
shorten it to 3 seconds instead
py.get('button', timeout=3).click()

---or---

give it even more time
py.get('button', timeout=30).click()


* If timeout=0, poll the DOM immediately without any waiting.

python
no waiting, immediately poll the DOM
py.get('button', timeout=0).click()


**Element and Elements**

Changed some properties to functions for the same reasons as the props in Driver.

* `Elements.length` property changed to `Elements.length()` function
* `Element.tag_name` property changed to `Element.tag_name()` function
* `Element.text` property changed to `Element.text()` function

**ElementsShould**

_Pylenium_ and _Element_ have their own Should classes for expectations. Most of our assertions and checks are done against them, but there were enough use cases against the length of the Elements that I wanted to include them to make it easier. Now when you have a list of elements \(Elements\), you can use `.should()`:

* `be_empty()`
* `not_be_empty()`
* `have_length()`
* `be_greater_than()`
* `be_less_than()`

Added

Pylenium CLI

Details

After a fresh install of pyleniumio, you now need to initialize pylenium using the Pylenium CLI:

bash
$ pylenium init


You can also see the available options using the `--help` argument.

bash
$ pylenium init --help


This will create the `conftest.py` file needed by Pylenium as well as the default `pylenium.json` config file.

{% hint style="info" %}
Run this command at the Project Root so Pylenium is globally accessible by all files/tests in your project.
{% endhint %}

Purpose

Originally, Pylenium would copy a conftest.py file and overwrite any existing conftest.py files the user had at the Project Root. This was a necessary side effect with how `setup.py` was working. With `pylenium init`, you now have the option to create or overwrite these files rather than needing to start from scratch.

`pylenium init` also creates a default `pylenium.json` so the user knows what config values they can change globally. This makes for a much easier experience for users.

This also removes the requirement of the user being in the context of a virtual environment. Although this is still 100% recommended, `pylenium init` can be executed in or out of the venv.

Added

* `options.add_extension()`
* `Element.open_shadow_dom()`

Details

**Add Extension**

You can now easily add extensions to your browser sessions by either using the `--extensions` CLI argument and passing in a list of file paths, or you can also do this in the `pylenium.json`

javascript
{
"driver": {
"extension_paths": ["path.crx", "other-path.crx"]
}
}


**Shadow DOM**

Shadow DOMs are a bit tricky, but you can now find elements within them by using the `Element.open_shadow_dom()` command. Check out this example using `chrome://extensions`:

python
def test_loading_extension_to_browser(py):
py.visit('chrome://extensions/')
shadow1 = py.get('extensions-manager').open_shadow_dom()
shadow2 = shadow1.get('extensions-item-list').open_shadow_dom()
extension_shadow_dom = shadow2.find('extensions-item')[1].open_shadow_dom()
assert extension_shadow_dom.get('name-and-version').should().contain_text('Get CRX')

Added

* `drag_to( css )`
* `drag_to_element( to_element )`

Details

`Element.drag_to( css )` will drag the current element to the element with the given CSS.

python
py.get('draggable-box').drag_to('drop-here')


`Element.drag_to_element( to_element )` will drag the current element to the given element.

python
to_element = py.get('drop-here')
py.get('draggable-box').drag_to(to_element)


python
one more example
from_element = py.get('draggable-box')
to_element = py.get('drop-here')

from_element.drag_to_element(to_element)

Added

* Page Load Wait Time
* Test Case Name into Capabilities for frameworks like Selenoid
* Add Experimental Options via `pylenium.json`

Details

**Page Load Wait Time**

By default, the Page Load timeout is `0` just like Selenium. However, there were cases where users wanted to control this globally or as needed per test case. You can now do this a few different ways:

bash
set it globally in CLI
--page_load_wait_time 10


javascript
// set it globally in pylenium.json
{
"page_load_wait_time": 10
}


python
override the global page_load_wait_time just for the current test
py.set_page_load_timeout(10)


**Test Case Name into Capabilities**

This was primarily for other frameworks like Selenoid and Zalenium that used this name to label the tests in their runners. For example, in Selenoid, you can filter tests by name. Before this change, the tests were given an unhelpful, generic name instead of the proper test name. That's fixed now :\)

**Add Experimental Options**

For users that want to use some of the experimental options for browsers, you can now do this within `pylenium.json`. This is a list of dictionaries \(key-value pairs\) that you want to include globally.

javascript
{
"experimental_options": [
{"useAutomationExtension": false},
{"otherName": "value"}
]
}