Repository files navigation

Helium is a Python library for automating browsers such as Chrome and Firefox.For example:

To get started with Helium, you need Python 3 and Chrome or Firefox.

I would recommend creating a virtual environment. This lets you install Heliumfor just your current project, instead of globally on your whole computer.

To create and activate a virtual environment, type the following commands intoa command prompt window:

python3 -m venv venv# On Mac/Linux:source venv/bin/activate# On Windows:call venv\scripts\activate.bat

Then, you can install Helium withpip:

python -m pip install helium

Now enterpython into the command prompt and (for instance) the commands inthe animation at the top of this page (from helium import *, ...).

I've compiled acheatsheet that quickly teaches you allyou need to know to be productive with Helium. For a more complete reference ofHelium's features, please see thedocumentation.

Under the hood, Helium forwards each call to Selenium. The difference is thatHelium's API is much more high-level. In Selenium, you need to use HTML IDs,XPaths and CSS selectors to identify web page elements. Helium on the other handlets you refer to elements by user-visible labels. As a result, Helium scriptsare typically 30-50% shorter than similar Selenium scripts. What's more, theyare easier to read and more stable with respect to changes in the underlying webpage.

Because Helium is simply a wrapper around Selenium, you can freely mix the twolibraries. For example:

# A Helium function:driver=start_chrome()# A Selenium API:driver.execute_script("alert('Hi!');")

So in other words, you don't lose anything by using Helium over pure Selenium.

In addition to its more high-level API, Helium simplifies further tasks that aretraditionally painful in Selenium:

• iFrames: Unlike Selenium, Helium lets you interact with elements insidenested iFrames, without having to first "switch to" the iFrame.
• Window management. Helium notices when popups open or close and focuses /defocuses them like a user would. You can also easily switch to a window by(parts of) its title. No more having to iterate over Selenium window handles.
• Implicit waits. By default, if you try click on an element with Seleniumand that element is not yet present on the page, your script fails. Helium bydefault waits up to 10 seconds for the element to appear.
• Explicit waits. Helium gives you a much nicer API for waiting for acondition on the web page to become true. For example: To wait for an elementto appear in Selenium, you would write:

  element=WebDriverWait(driver,10).until(EC.presence_of_element_located((By.ID,"myDynamicElement")))

  With Helium, you can write:

  wait_until(Button('Download').exists)

I have too little spare time to maintain this project for free. If you'd likemy help, please go to myweb site to ask about myconsulting rates. Otherwise, unless it is very easy for me, I will usually notrespond to emails or issues on the issue tracker. I will however accept andmerge PRs. So if you add some functionality to Helium that may be useful forothers, do share it with us by creating a Pull Request. For instructions, pleaseseeContributing below.

I find Helium extremely useful in my own projects and feel it should be morewidely known. Here's how you can help with this:

• Star this project on GitHub.
• Tell your friends and colleagues about it.
• Share it on Twitter with one click
• Share it on other social media
• Write a blog post about Helium.

With this, I think we can eventually make Helium the de-facto standard for webautomation in Python.

Pull Requests are very welcome. Please follow the same coding conventions as therest of the code, in particular the use of tabs over spaces. Also, read through myPR guidelines.Doing this will save you (and me) unnecessary effort.

Before you submit a PR, ensure that the tests still work:

pip install -Ur requirements/test.txtpython setup.pytest

This runs the tests against Chrome. To run them against Firefox, set theenvironment variableTEST_BROWSER tofirefox. Eg. on Mac/Linux:

TEST_BROWSER=firefox python setup.pytest

On Windows:

set TEST_BROWSER=firefoxpython setup.pytest

If you do add new functionality, you should also add tests for it. Please seethetests/ directory for what this might look like.

I (Michael Herrmann) originally developed Helium in 2013 for a Polish IT startupcalled BugFree software. (It could be that you have seen Helium before athttps://heliumhq.com.) We shut down the company at the end of 2019 and I felt itwould be a shame if Helium simply disappeared from the face of the earth. So Iinvested some time to modernize it and bring it into a state suitable for opensource.

Helium used to be available for both Java and Python. But because I now onlyuse it from Python, I didn't have time to bring the Java implementation up tospeed as well. Similarly for Internet Explorer: Helium used to support it, butsince I have no need for it, I removed the (probably broken) old implementation.

The name Helium was chosen because it is also a chemical element like Selenium,but it is lighter.