This page very quickly teaches you the most important parts of Helium's API.
All of Helium's public functions lie directly in the module
You can for instance import them as follows:
from helium import *
Starting a browser
Helium currently supports Chrome and Firefox. You can start them with the following functions:
You can optionally pass a URL to open (eg.
When you type the above commands, you will actually see a browser window open.
This is useful for developing your scripts. However, once you run them, you may
not want this window to appear. You can achieve this by adding
start_chrome(headless=True) start_chrome('google.com', headless=True)
start_firefox(...) of course.)
Interacting with a web site
The following example shows the most typical statements in a Helium script:
from helium import * start_chrome('google.com') write('helium selenium github') press(ENTER) click('mherrmann/helium') go_to('github.com/login') write('username', into='Username') write('password', into='Password') click('Sign in') kill_browser()
Most of your own code will (hopefully) be as simple as the above.
The above example used pure strings such as
Sign in to identify elements on
the web page. But Helium also lets you target elements more specifically.
You can pass them into other functions such as
But you can also use them to read data from the web site. For instance:
A common use case is to use
.exists() to check for the existence of an
element. For example:
if Text('Accept cookies?').exists(): click('I accept')
I also often find
Text(...).value useful for reading out data:
name = Text(to_right_of='Name:', below=Image(alt='Profile picture')).value
For a full list of element types and their properties, please see the source code.
Finding elements relative to others
You already saw in the previous section how
let you find elements relative to other elements. You can similarly use
to_left_of. Here are some more examples.
Text(above='Balance', below='Transactions').value Link(to_right_of='Invoice:') Image(to_right_of=Link('Sign in', below=Text('Navigation')))
Waiting for elements to appear (or other conditions)
to wait for a condition to become true. For example:
But you can also use this to wait for an arbitrary condition:
wait_until(lambda: TextField('Balance').value == '$2M')
Sometimes, you do need to fall back to using HTML IDs, CSS Selectors or XPaths
to identify an element on the web page. Helium's
predicate lets you do this. The parameter you pass to it is interpreted as
- If it starts with an
@, then it identifies elements by HTML
S("@btnName")identifies an element with
- If it starts with
//, then Helium interprets it as an XPath.
- Otherwise, Helium interprets it as a CSS selector. This in particular
lets you write
S("#myId")to identify an element with
S(".myClass")to identify elements with
As before, you can combine
S(...) with other functions such as
click(S(...)), or use it to extract data. For an example of this, see
Combining Helium and Selenium's APIs
All Helium does is translate your high-level commands into low-level Selenium function calls. Because of this, you can freely mix Selenium and Helium. For example:
# A Helium function: driver = start_chrome() # A Selenium API: driver.execute_script("alert('Hi!');")
With the WebDriver instance, you can execute any Selenium commands you want.
To use Helium's API's to obtain Selenium
WebElements, use the
property of Helium's various GUI elements. For instance:
# Get the CSS class of the "Helium" link: Link('Helium').web_element.get_attribute('class')
.get_attribute(...) is a Selenium API.
Finding all elements
.web_element property and the
S(...) predicate are particularly useful
for extracting multiple pieces of data from a web page. To do this, you can use
As its name implies, it lets you find all occurrences of an element on a page.
email_cells = find_all(S("table > tr > td", below="Email")) emails = [cell.web_element.text for cell in email_cells]
When you issue a command such as
click('Download'), Helium by default waits
up to 10 seconds for the respective element to appear. This feature is called
"implicit waiting". You can change the 10 second default to a different value
Config.implicit_wait_secs = 30
However, before you do this, it may be better to add explicit waits to your
code, such as
Alert().dismiss() to click "Ok" or "Cancel",
Alert().text to read the
message shown, or
write(..., into=Alert()) to enter a value.
File uploads, drag and drop, combo boxes, popups
Clicking at x, y coordinates
Sometimes, you may want to click at a specific
(x, y) coordinate, or at an
offset of an element. See the
Taking a screenshot
Use Selenium's API:
Note the leading
r. This is required because the string contains a backslash