Package: e2e.pom
e2e.pom - Page Object Modelling for End-to-End TestingUsee2e.pomto easily create reusable Page Object Models that offer
functionality and error scenarios more naturally than Selenium can.Extend available locators with plugins likee2e.pom.extjsfor
ExtJS/Sencha Locators, or write your own!Eliminate iframe-handling in your tests — let the model take care of
where your elements reside. In fact, all elements are guaranteed to be
found within their parent model so you can write unique selectors
without specifying a long ancestry within the selector itself!All actions are logged with human-friendly labels, with human-friendly
exceptions indicating exactly where things went wrong.Beta Noticee2e.pomis still inbeta, but the API is expected to be stable. The
project is very open to suggestions and feedback at this stage!This project follows SemVer. It is expected that the first major release (1.x)
willnotdiffer in API functionality much from the alpha/beta track
(0.x).Python 3.6+ is currently required. No support for 2.x is ever planned since
it is soon to be unsupported. Please feel free to file an issue if you need
support for an earlier Python version and simply cannot upgrade.Modelling ExamplesPages and their components are easy to model on a class-member basis.
You do not need to pass around a driver, nor do you need to write
properties or methods. There is no need to override__init__properly either; just author your static model and be done with it!classLoginForm(pom.Region):username_field=pom.Element("Username").by_css('.username')password_field=pom.Element("Password").by_css('.password')login_button=pom.Element("Login btn").by_css('#login-submit')classLoginPage(pom.Page):login_form=LoginForm("Login form").by_css('.login')# ...login_pg=LoginPage("https://my-login-service.local:8443",driver)login_pg.login_form.wait_for_visible()login_pg.login_form.username_field.set_text('Admin1')login_pg.login_form.password_field.set_text('Sup3rS3cret!')login_pg.login_form.login_button.click()IFrame HandlingHandling iframes with Selenium is incredibly annoying.e2e.pomprovides a special component that you can use as a hidden parent so that
test authors do not need to be concerned about the iframe at all.classLoginForm(pom.Region):# Same as Example Model aboveclassLoginPage(pom.Page):# Hide the iframe POM component so the test doesn't need to be aware by# overriding the parent of the Form._login_service_iframe=pom.IFrame("LoginService iframe").by_css('iframe#login-service')login_form=LoginForm("Login form").by_css('.login',parent=_login_service_iframe)# Use exactly as before, like the iframe isn't even there!login_pg.login_form.wait_for_visible()The POM framework will then handle switching to the correct iframes.
Even if a servicebecomesresident within an iframe that was otherwise
inline before, you only need to change themodeland not the test
code!In addition, features likeis_visible()are mindful of iframes. That
is, unlike using Selenium directly, if the iframe is not displayed thene2e.apicounts all of its children as invisible.Hidden RegionsLike the above case for IFrames, you may want to hide a certain part of
the model but otherwise use it as a parent to other components. This is
often useful for ensuring elements are found within a certain part of
the page, but would be too verbose to specify in every test.classServicePage(pom.Page):_nav_bar=pom.Region("Navigation bar").by_css('.upper-nav-container')settings_button=pom.Element("Setting btn").by_css('.gear-icon')# You can now do this...service_pg.settings_button.click()# Instead of having to do thisservice_pg.navigation_bar.settings_button.click()This is especially useful when you have, like in the above example,
multiple elements that use.gear-iconbut are obviously referring to
one particular instance of it. If it is beneficial to the clarity of
your model though, you may want tonothide the parent since the
increased verbosity may make your test’s actions more clear to others.Interacting with ElementsWhile some available methods are similar to Selenium’s API, they have
differing requirements and behaviours.For example, the concept of “visibility” is now more user-friendly.
Whether an element isvisibleto the user depends not only on the
display info of the element, but whether the element exists at all. With
Selenium, entirely different code is required to handle that difference!
Withe2e.pom, it isjustthe visiblility functions. This allows
product developers to use techniques like DOM caching without needing to
change the test code. This way,e2e.pomis checkinguser intentrather thanimplementation details.# Case 1: With Selenium, element not in DOM. Can also assert NoSuchElement was raised.assertdriver.find_elements_by_xpath(...)==[]# Case 2: With Selenium, element in DOMassertdriver.find_elements_by_xpath(...).is_displayed()# With happy-path-only POM frameworks (not e2e.pom)try:assertmodelled_element.is_displayed()exceptNoSuchElementException:pass# With e2e.pom (works for both above cases)assertmodelled_element.is_visible()Nothinghappens until you call a method on an element. This is to give
clarity as to when the finding, attribute checking, and interaction
takes place within a test.# Selenium: All of these do something with the driver, even the properties!element=driver.find_element_by_css_selector(...)element.textelement.is_displayed()element.click()element.clear()andelement.send_keys("some text")# e2e.pom: Consistent API. Methods == driver actions.element.get_text()element.is_visible()element.click()element.set_text("some text")All user-like interaction methods require visibility of the element. If
the element is not visible, a user cannot interact with it. Exceptions
will be raised with the exact details (e.g. if it was because a parent
could not be located, the exception will state this).Sets of ElementsSometimes you are intentionally referring to a group of similar
elements, like rows of a particular type. You can’t use apom.Elementfor this because they requireuniquelyfinding an
element. In this case, you can usepom.ElementCollection.Rich VisibilityTo-do.Using Locators Provided by Third-Party PluginsIn certain projects, alternative locator methods may be available that
are more deterministic of exact elements.A first-party example of this,e2e.pom.extjs, provides locators for
pages built with ExtJS/Sencha.This extensibility has a few drawbacks to be aware of:The genericby(...)must be used instead of something likeby_css(...)Many setups will fail to type-check or auto-complete this correctly.Using it is very easy though! Just ensure it is installed, then use the
providedLocatorclass directly in theby()construction.frome2eimportpomfrome2e.pomimportextjsclassServicePage(pom.Page):alert_popup=pom.Element("Alert").by(extjs.Locator('panel[title=Alert]'))Developing Locator ExtensionsPlease usee2e.pom.extjsas an implementation guide.The following are recommended:The extension locator class should be calledLocatorwhere
possible.find_withinis the only method needing implementation. It will be
passedeitheraWebDriveror aWebElement. For theWebElement, youmustassure that anything returned by your
Locator is within the givenWebElement.Don’t forget to register the entrypoint!Pytest Hooks & Fixtures (BETA)Note:This feature is under development andwillchange. Feedback is
much appreciated!A information-providing fixture is provided for dumping info useful in
test failure analysis.You must register the drivers you use with this fixture. We recognize
users will have their own ways of managing drivers, so this is the best
way currently.deftest_my_thing(e2e_pom_dumper:pom.fixtures.DumperFixture):my_driver=...# However you get thise2e_pom_dumper.register_driver(my_driver)# Now you can use the driver!After that, the following features are provided:On test failure, two DOMs are dumped to HTML files:The current frame/iframe at the time of failure (if not the root
frame)The root frameA screenshot is taken at the outermost/root framePerformance ConsiderationsCertain features like Collections as parents can result in a lot of
Selenium requests being issued. If you test against a busy Selenium
Grid, this can definitely slow things down!I do not normally recommend the below workarounds (because they bypass
some significant benefits of the framwork), but you may find them
necessary in your case.Avoid apom.Collectionparent if it represents many elements
(e.g. rows in a large table). Every found element for the collection
is searched for the next child.Reduce POM depth where possible. Since each child causes a Selenium
find request on interaction, reducing the size of that parentage can
speed things up.For the first case, this can be easy to work around with a dynamic model
if you are targeting a particular item.classMyTable(pom.Container):rows=pom.Collection('Rows').by_css('tr')defrow_by_title(self,title:str):label=f'Row by title [{title}]'xpath=f'.//td[text()="{title}]/ancestor::tr"'# Do this IF Selenium performance isn't critical to you (most cases)returnpom.Element(label).by_xpath(xpath,parent=rows)# Do this IF and ONLY IF Selenium performance is very important to youreturnpom.Element(label).by_xpath(xpath)Note howrowsis on the model directly, but also used as a parent
override in the method. However, skippingrowsas a parent means we
can forego some more detailed information on failure while making less
Selenium calls.Making Richer ModelsGeneric type information can be passed regarding the type of located
elements.This is especially useful forpom.ElementCollections. For example,
you may want to have aniconproperty modelled on each dropdown item
returned from a collection. This is normally modelled by a Findable
component (e.g.pom.Containerorpom.Element), but these cannot
be used forfoundelements (those returned bypom.ElementCollection.get()). Enter, generics.On construction ofanyfindable POM type, you can specify the concrete
type returned byfindable.get()or acted on via operations likefindable.click(). By default, this is apom.dom.ElementReference, but you may extend it to provide more
functionality.# TODO: assert Reference parents actually work!classDropdown(pom.Container):classIconItem(pom.dom.ElementReference):icon=pom.Element("Icon").by_css(".option-icon")items=pom.ElementCollection("Dropdown items",IconItem).by_css("option")first_item=...dropdown.items.get()[0]assert'gear-icon'infirst_item.icon.get_attribute('class')The type ofitemsis now apom.ElementCollection<IconItem>. If
it was not specified, it would be apom.ElementCollection<dom.ElementReference>.This works because while an ElementReference is not “Findable”, itis“Parentable”. That is, it can be a parent, and thus contain other
modelled children.In the future, a pom.HybridElement may exist that can be used to
represent these items both as a Findable and a Found object to avoid
code duplication.Basically, a rich interface is what you write.Changelog for e2e.pom0.1.8 (2023-01-04)Remove deprecated _find_within that was causes static analysis issuesAdded wait methods from ElementReferences0.1.7 (2022-09-20)Allow ElementCollection to be a direct parent0.1.5 (2022-09-20)Better error reporting for issues while findingAdded DOM presence wait methods0.1.4 (2022-09-12)[Issue 2] Fix ElementReference naming and parent chain for logging0.1.3 (2022-08-24)Fix: Missing import0.1.2 (2022-08-22)Type-hint fixes at the module-level, and a couple method signature fixesNew way to wait for page transitions:pom.Page.expect_transition0.1.1 (2022-06-26)Packaging and requirements fixesAdded some left-behind critical missing functions!Fixed typos on exception names0.1.0 (2022-05-09)Exported modelling core to e2e.common, imported and used hereFixed some type-hints based on updated mypy versionsFixed some issues mypy had detecting types in the package at allUpdated tags to support Python 3.9, 3.100.0.1 (11-19-2020)Initial release! Elements, Collections, IFrames, and Pages.Copyright 2019-2022 Nicholas KroekerLicensed under the Apache License, Version 2.0 (the “License”);
you may not use this file except in compliance with the License.
You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an “AS IS” BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.