browserist 1.4.5

Extension for the Selenium web driver that makes browser automation even easier

👩‍💻 Browserist Extension for Selenium 👨‍💻

browserist

1. The belief that web browsers account for differences in websites or web applications in all of their ability and that a particular web browser is superior to others.
2. Discrimination or prejudice based on web browser.

Despite the urban definition, Browserist is a Python extension of the Selenium web driver that makes it even easier to use different browsers for testing and automation.

Main features of Browserist:

• Improves stability and speed
• Simple syntax
• Hassle-free setup that works across browsers: Chrome, Firefox, Edge, Safari, Opera, Internet Explorer
• Extended library of browser automation functions and tools without elaborate code
• Supports IntelliSense type hints and other capabilites of Python 3.10 that makes development more efficient

How to Install

Ready to try? Learn how to install.

Getting Started

The default browser is Chrome (except Edge for Windows). Simply type:

from browserist import Browser

browser = Browser()
browser.open.url("http://example.com/")
browser.quit()

Or use the built-in context manager so the browser automatically closes when done or if an error occurs:

from browserist import Browser

with Browser() as browser:
    browser.open.url("http://example.com/")

Browser Types

If you want to use other browser types, e.g. Firefox, Edge, etc., define this in the settings:

from browserist import Browser, BrowserSettings, BrowserType

settings = BrowserSettings(type = BrowserType.FIREFOX)
with Browser(settings) as browser:
    browser.open.url("http://example.com/")

Supported Browsers

Name	Type
Chrome	BrowserType.CHROME
Edge	BrowserType.EDGE
Firefox	BrowserType.FIREFOX
Internet Explorer	BrowserType.INTERNET_EXPLORER
Opera	BrowserType.OPERA
Safari	BrowserType.SAFARI

Navigation

Similar to Selenium, use simple commands to automate the browser:

Action	How	Description
Forward	browser.forward()	Press the browser's back button
Back	browser.back()	Press the browser's forward button
Refresh	browser.refresh()	Refresh the current page
Quit	browser.quit()	Close the browser

Improved Stability and Less Code

Browserist improves stability with less code. As a browsers need time to render a page, especially single-page applications, Selenium is often used with explicit timeouts:

from selenium import webdriver
from selenium.webdriver.common.by import By

driver = webdriver.Chrome()

driver.get("http://example.com/")
driver.implicitly_wait(3)
search_box = driver.find_element(By.XPATH, "//xpath/to/input")
search_button = driver.find_element(By.XPATH, "//xpath/to/button")
search_box.send_keys("Lorem ipsum")
search_button.click()
driver.quit()

Browserist does the same with less and cleaner code, yet also with increased stability and without explicit/implicit waits:

from browserist import Browser

with Browser() as browser:
    browser.open.url("http://example.com/")
    browser.input.value("//xpath/to/input", "Lorem ipsum")
    browser.click.button("//xpath/to/button")

As you can't click a button that's not ready in the DOM, Browserist simply checks if elements are ready before interacting with them:

Timing:	Too short ->	Just right	<- Too long
Example:	time.sleep(1)	wait.for_element()	time.sleep(10)
Consequence:	Code breaks	Stable and fast	Slow

Settings

If you want a headless browser with Selenium, you typically would use different settings from browser to browser. Browserist solves this problem so that settings for Chrome, Firefox, Edge, etc. are standardised. For example, you can easily scale test runs across different browsers in a lightweight, headless configuration:

from browserist import Browser, BrowserSettings, BrowserType

chrome = BrowserSettings(type = BrowserType.CHROME, headless = True, disable_images = True)
edge = BrowserSettings(type = BrowserType.EDGE, headless = True, disable_images = True)
firefox = BrowserSettings(type = BrowserType.FIREFOX, headless = True, disable_images = True)

for settings in [chrome, edge, firefox]:
    with Browser(settings) as browser:
        browser.open.url("http://example.com/")

Use BrowserSettings with the following options:

Setting	Option	Default	Description
type	BrowserType	BrowserType.CHROME	Set browser type, e.g. Chrome, Edge, Firefox, etc.
headless	True or False	False	Run the browser in headless mode. May not be supported by all browsers.
disable_images	True or False	False	Neither request nor render images, which typically improves loading speed. May not be supported by all browsers.
page_load_strategy	PageLoadStrategy	PageLoadStrategy.NORMAL	Set page load strategy.
path_to_executable	Path to file	System default	If the browser executable isn't in a default folder, select which file to use.
screenshot_dir	Path to directory	System default	Set where to save sreenshots. Default is the directory of Browserist.
timeout	TimeoutSettings	TimeoutStrategy.STOP and 5 seconds	Set timeout strategy and time.
viewport	DeviceViewportSize or (width, height)	Browser default	Emulate viewport size as device or set custom value in pixels.

Timeout Strategy

What happens if a function times out: Should the browser stop or continue its operation?

Define a general strategy and timeout in seconds:

• Default is 5 seconds per function (note that a function-specific timeout overrides this)
• The strategy can be TimeoutStrategy.STOP (default) or TimeoutStrategy.CONTINUE

from browserist import Browser, BrowserSettings, TimeoutSettings, TimeoutStrategy

timeout_settings = TimeoutSettings(strategy = TimeoutStrategy.CONTINUE, seconds = 10)
settings = BrowserSettings(timeout = timeout_settings)

with Browser(settings) as browser:
    browser.open.url("http://example.com/")

Strategy Options

Option	Description
TimeoutStrategy.STOP	Default. Fail fast upon timeout and raise errors.
TimeoutStrategy.CONTINUE	Continue despite timeouts and most errors (syntax errors excluded).

Emulate Viewport of Common Devices

You can set the viewport to emulate common device sizes or to a custom size. Note that it's recommended to run emulations in headless mode since an open browser may have minimum or maximum dimensions, either limited by the browser window or the monitor. Example:

from browserist import Browser, BrowserSettings, common_devices

settings = BrowserSettings(headless = True)

with Browser(settings) as browser:
    browser.viewport.set.size_by_device(common_devices.Apple.IPHONE_SE)
    browser.open.url("http://example.com/")
    browser.viewport.set.size(768, 1024)

Thank You for Supporting

Donate

This module is free to use. And if you like it, feel free to buy me a coffee.

Contribute

If you have suggestions or changes to the module, feel free to add to the code and create a pull request.

Report Bugs

Report bugs and issues here.

👩‍💻 How to Install Browserist 👨‍💻

Prerequisites

• Python 3.10 or higher
• Selenium
• Relevant browsers: Chrome, Firefox, Edge, Safari, Opera, Internet Explorer

PyPI

Assuming that Python is installed already, execute this command in the terminal:

pip3 install browserist

If you already have installed Browserist, use this command to upgrade to latest version:

pip3 install --upgrade browserist

Homebrew

If you already have installed the Homebrew package manager for Mac and Linux, execute this terminal command to tap Browserist:

brew tap jakob-bagterp/browserist

And then install:

brew install browserist

Recommended Add-Ons

ChromeDriver for Google Chrome

pip3 install chromedriver

brew install chromedriver

More info here.

Microsoft Edge Driver

More info and download here.

GeckoDriver for Mozilla Firefox

brew install geckodriver

More info here.

Getting Started

Ready to go? Learn how to use Browserist.

                             Apache License
                       Version 2.0, January 2004
                    http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

   "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.

   "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.

   "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.

   "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.

   "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.

   "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.

   "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).

   "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.

   "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."

   "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.

3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:

   (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and

   (b) You must cause any modified files to carry prominent notices stating that You changed the files; and

   (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and

   (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.

   You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

APPENDIX: How to apply the Apache License to your work.

  To apply the Apache License to your work, attach the following
  boilerplate notice, with the fields enclosed by brackets "[]"
  replaced with your own identifying information. (Don't include
  the brackets!)  The text should be enclosed in the appropriate
  comment syntax for the file format. We also recommend that a
  file or class name and description of purpose be included on the
  same "printed page" as the copyright notice for easier
  identification within third-party archives.

Copyright 2022 Jakob Bagterp

Licensed 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 at

   http://www.apache.org/licenses/LICENSE-2.0

Unless 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.