<!-- --8<-- [start:githubSection] -->

Selene: User-Oriented Web UI Browser Tests in Python

Overview of Selene

Selene is a concise and powerful library for writing browser UI tests in Python. It was built as a Pythonic port of the popular Selenide project from the Java world. Selene helps developers write readable and maintainable tests that "speak" in common English, making them easier to understand and share across teams.

Selene’s core strength is its user-oriented API, which abstracts the complexity of working with Selenium WebDriver. Tests can be written using simple, expressive syntax and support features like lazy-evaluated elements, automatic retry mechanisms for smarter implicit waiting for Ajax-like loading. With built-in PageObject support, it enables the reusability of web elements through Widgets.

Table of Contents

• Main Features
• Versions
  • Migration Guide
• Prerequisites
• Installation
• Usage
  • Quick Start
  • Core API
  • Advanced API
• Tutorials
• Expanded Examples
• Contribution
• Changelog

Main Features

• User-oriented API: Write test scripts in natural language with simple syntax that reads like common English.
• Ajax-like loading support: Built-in smart implicit waiting and retry mechanisms to handle dynamically loaded web elements.
• PageObjects support: Lazy-evaluated elements allows to build PageObjects composing elements over selectors or By.* tuple-like locators, allowing also to create reusable elements for different components.
• Extended list of expected conditions: Much bigger list of conditions aka matchers than in raw Selenium allows to implement more readable and concise assertions in tests.
• Extended list of predefined commands on element: Reduces the need of composing custom commands with ActionChains.
• Out of the box support of frames and shadow root.
• Flexible filtering of collections: Allows to build composable locators reducing the need of complex XPath-selectors and results in much more detailed error messages that helps with tests maintenance.
• Very detailed error messages: For both actions and assertions on elements.
• Automatic driver management: Automatically handles browser driver setup and teardown for quick, local executions.
• Highly customizable: Advanced users can configure or extend Selene for specific requirements. For example, you can customize your own selector templates. You also can customize same options (for example timeout) via same API on all levels: 1) globally; 2) on specific browser instance; 3) on specific element or collection of elements stored in a variable 4) for specific action or assertion on element.
• Support for both local and remote drivers: Selene supports a variety of environments, including local browsers, headless setups, and cloud services like Selenium Grid – in a similar way that Selenium supports it – by providing the corresponding driver options.
• Multiplatform support: Works with web and Appium's mobile or desktop drivers. Though, some options in config are platform-specific.

Versions

Selene currently supports two major versions:

• Latest Recommended Pre-Release Version (v2.0.0rc9):

  • Python versions: 3.8+
  • Selenium support: >=4.12.0
  • This version introduces an improved API, better performance, and is recommended for new projects.
  • Though is in alpha/beta stage, refining API, improving "migratability" and testing
  • Most active Selene users already upgraded to 2.0 alpha/beta and have been using it in production during last 2 years
  • The only risk is API changes, some commands are in progress of deprecation and renaming

• Stable Version (v1.0.2):

  • Python versions: 2.7, 3.5, 3.6, 3.7
  • Selenium support: <4.0.0
  • Use this version if your project requires compatibility with older Python versions.

For migration from v1.x to v2.x, follow the migration guide.

Migration Guide

From 1.0.2 to 2.0.0rc<LATEST>:

• Upgrade to Python 3.8+
• Update selene to 2.0.0rc<LATEST>
  • Replace the collection.first() method from .first() to .first
  • Ensure all conditions like text('foo') use the be.* or have.* syntax
  • Update other deprecated methods as needed

Examples of potential refactoring during migration:

• find&replace all
  • (text('foo')) to (have.text('foo'))
  • (visible) to (be.visible)
• smarter find&replace (with some manual refactoring)
  • .should(x, timeout=y) to .with_(timeout=y).should(x)
  • .should_not(be.*) to .should(be.not_.*) or .should(be.*.not_)
  • .should_not(have.*) to .should(have.no.*) or .should(have.*.not_)
  • .should_each(condition) to .should(condition.each)
• and add corresponding imports: from selene import be, have

Prerequisites

[Python 3.8+][python-38] is required.

Given [pyenv][pyenv] is installed, installing the needed version of Python is simple:

$ pyenv install 3.8.13
$ pyenv global 3.8.13
$ python -V
Python 3.8.13

Installation

via Poetry + Pyenv (Recommended)

Ensure [poetry][poetry] and [pyenv][pyenv] are installed, then:

poetry new my-tests-with-selene
cd my-tests-with-selene
pyenv local 3.8.13
poetry add selene --allow-prereleases  # for pre-release version
poetry install

via Pip

For the pre-release version (recommended for new projects):

pip install selene --pre

For the latest stable version:

pip install selene

from Sources

If you prefer to install Selene directly from the source code:

git clone https://github.com/yashaka/selene.git
cd selene
python setup.py install

Or using poetry:

poetry add git+https://github.com/yashaka/selene.git

Or using pip:

pip install git+https://github.com/yashaka/selene.git

Usage

Quick Start

Automate a simple Google search using Selene:

from selene import browser, be, have

browser.open('https://google.com/ncr')
browser.element('[name=q]').should(be.blank)\
    .type('selenium').press_enter()
browser.all('#rso>div').should(have.size_greater_than(5))\
    .first.should(have.text('Selenium automates browsers'))

# not mandatory, because will be closed automatically:
# browser.quit()

Core API

• Selene provides an intuitive API for interacting with web elements using modules like be, have or by.

• Lazy and Dynamic Elements: Selene elements are lazy and dynamic, meaning they are located each time an action is performed. This ensures interaction with the most up-to-date element.

• Here is a basic element interaction:

from selene import browser, by, be

# because elements are "lazy",
# you can store them in variable:
search_box = browser.element(by.name('q'))

# – even before the actual page will be loaded:
browser.open('https://google.com/ncr')
search_box.should(be.blank).type('Selenium').press_enter()

Selecting Element Locators

Choosing the correct element locators is crucial for reliable tests. Here are some tips:

1. Inspect the Element: Right-click on the web element and select Inspect to view its HTML in the browser's developer tools.

2. Use Unique Attributes: Look for unique attributes like id, name, or custom attributes to use in your selectors. Best practice is to negotiate with developers on using unique data-* attributes specifically for testing needs, like data-test-id.

3. Construct CSS or XPath Selectors: Build selectors that uniquely identify elements. For example, using conciser css-selectors #elementId, .className, or [name="q"], or using XPath for things that CSS can't handle: //*[text()="Submit"]/... Selene will automatically detect whether you provide a CSS or XPath selector.

4. Utilize Selene's Selector Helpers (optional): If you need most human-readable code, you can use by.name('q'), by.text('Submit') and other by.* helpers. Notice, that someone would prefer raw css selector like [name=q] over by.name('q') for the purpose of KISS principle.

5. Break down long selectors into smaller parts for better readability and maintainability: If to find an element you have a complex selector like in: browser.element('//*[@role="row" and contains(.,"Jon")]//*[@data-field="select-row"]'), decomposing it utilizing Selene's filtering collections API to browser.all('[role=row]').element_by(have.text('Jon')).element('[data-field=select-row]') will make it e