An all inclusive selenium framework for Python 2.7 and 3.6.

View the Project on GitHub neetjn/py-component-controller


build Documentation Status Code Health codecov

PyPI version Join the chat at

py-component-controller is an opinionated framework for structuring selenium test suites.

This project depends on the pyselenium-js project.

Official documentation be be read here.


What this project strives to do is deter from redundant tasks, and help provide an interface to tackeling larger web applications. This project is a wrapper for the official selenium bindings and pyselenium-js, offering a more object orientated approach. py-component-controller also includes polyfills for conforming webdriver behavior – such as the safari webdriver’s handling of multiple element queries.


The official selenium bindings for Python feel rather dated, and a single interaction such as checking an element’s visibility after clicking it can take a myriad of api calls. Additionally, the official Selenium bindings operate in the most natural way a user would operate against a given web page; simple actions such as clicking on an element can be disasterous for modern web applications using a z-index on panels and more commonly modals, because the selenium bindings attempt to get the element’s coordinate position before actually executing the click. Using pyselenium-js under the hood, this framework can alleviate the many burdens regularly encountered while using selenium.

py-component-controller also offers a very easy-to-use interface for structuring selenium tests, with method chaining functionality. Take the following example,

app = App(webdriver, base_url, {
  'header': Header,
  'footer': Footer,
  'home': Home

assert app.components.header.log_in\
  .wait_visible(timeout=1, error=True)\

Looks easy to maintain, no?


A component represents an area in the web application user interface that your test is interacting with. Component objects were created to represent every possible element a controller and/or test would need to reference. Component objects allow us to define an element once, and reference it however many times we need by it’s defined property. If any major changes are made to our target interface, we can change the definition of a component’s property once and it will work across all of our given controllers and tests. Reference: Page Object

Controllers were created to utilize our defined component objects and to farm out tedious rudimentary tasks such as navigating and managing our context. Controllers allow us to define our logic in a behavioral manner, outside of our test cases, keeping everything clean, simple, and manageable. Controllers also allow us to reference a browser once and pass it to all of our defined components. Reference: Page Object Model


This project was created using selenium 3.12.0, and pyseleniumjs 1.3.8.

Support is available for both Python 2.7 and 3.6.

py-component-controller can be installed using pip like so,

pip install pyscc

For more information refer to the official documentation here


All module related e2e tests are in the tests subdirectory. This project uses pipenv, so to setup your environment install pipenv from pip using pip install pipenv and create your environment with pipenv install --dev. For test coverage pytest is used; to run the suite use pipenv run pytest tests.

The mock site can be accessed here; it was created using Riot.js 3, SkeletonCSS, and webpack 3. It was designed to represent a common website layout with responsive capabilities.



Contributing guidelines are as follows,

Copyright (c) 2018 John Nolette Licensed under the Apache License, Version 2.0.