Skip to content

browser.click#

Functions#

button(xpath, timeout=None) #

Click button.

Parameters:

Name Type Description Default
xpath str

XPath of the button element.

 required
timeout float | None

In seconds. Timeout to wait for element. If None, the global timeout setting is used (default 5 seconds).

 None
Example 
browser.click.button("//xpath/to/button")

button_if_contains_text(xpath, regex, ignore_case=True, timeout=None) #

Click button if it contains certain text.

Parameters:

Name Type Description Default
xpath str

XPath of the button element.

 required
regex str

Regular expression or text to search for. The condition works for both ordinary text (e.g. "Submit") or regular expression (e.g. r"colou?r"). Note it's a search for text, not a strict text match.

 required
ignore_case bool

Ignore case when searching for text.

 True
timeout float | None

In seconds. Timeout to wait for element. If None, the global timeout setting is used (default 5 seconds).

 None
Example

Without regular expression:

browser.click.button_if_contains_text("//xpath/to/button", "Save")

With regular expression:

browser.click.button_if_contains_text("//xpath/to/button", r"^Submit")

download(xpath, timeout=None, await_download=False, expected_file_name=None, idle_download_timeout=None) #

Click button and download file.

Parameters:

Name Type Description Default
xpath str

XPath of the download button element.

 required
timeout float | None

In seconds. Timeout to wait for button element. If None, the global timeout setting is used (default 5 seconds).

 None
await_download bool

Set to False to download the file in the background – this will also bypass the expected_file_name and idle_download_timeout parameters. Set to True to wait for the download to complete.

 False
expected_file_name str | None

Expected file name to determine when the download is complete. If None, this may be slower as Browserist will attempt to guess the file name by monitoring changes in the download directory.

 None
idle_download_timeout float | None

In seconds. Timeout to wait for file size to not increase, which is constantly renewed as long as the file size increases. If None, the global idle download timeout setting is used (default 3 seconds).

 None
Download Directory

The download directory is implicitly defined in the download_dir parameter of BrowserSettings.

Avoid that multiple browser instances have access to the same download directory. As Browserist monitors the download directory for file changes, it may cause unexpected behaviour if multiple files are downloaded to the same directory at the same time.

Example

Examples in context:

1
2
3
4
5
6
7
from browserist import Browser

with Browser() as browser:
    browser.open.url("https://example.com")
    browser.click.download("//xpath/to/button")
    browser.click.download("//xpath/to/button", await_download=True)
    browser.click.download("//xpath/to/button", await_download=True, expected_file_name="file.zip")

Download file in background without waiting. If the browser closes during a download, the download may be aborted or left incomplete:

5
    browser.click.download("//xpath/to/button")

Download file and wait for download to complete. This will attempt to guess the file name, which may be slower:

6
    browser.click.download("//xpath/to/button", await_download=True)

Download expected file name and wait for download to complete. It's faster if you know the file name:

7
    browser.click.download("//xpath/to/button", await_download=True, expected_file_name="file.zip")

download_and_get_file_path(xpath, timeout=None, idle_download_timeout=None) #

Click button to download file and get file path once download is complete. As downloads are automatically handled by the browser, this is useful if you don't know the file name beforehand.

Parameters:

Name Type Description Default
xpath str

XPath of the download button element.

 required
timeout float | None

In seconds. Timeout to wait for button element. If None, the global timeout setting is used (default 5 seconds).

 None
idle_download_timeout float | None

In seconds. Timeout to wait for file size to not increase, which is constantly renewed as long as the file size increases. If None, the global idle download timeout setting is used (default 3 seconds).

 None

Returns:

Type Description
Path

Path to the downloaded file. Return type is the standard library pathlib.Path.
Download Directory

The download directory is implicitly defined in the download_dir parameter of BrowserSettings.

Avoid that multiple browser instances have access to the same download directory. As Browserist monitors the download directory for file changes, it may cause unexpected behaviour if multiple files are downloaded to the same directory at the same time.

Example 
1
2
3
4
5
from browserist import Browser

with Browser() as browser:
    browser.open.url("https://example.com")
    file_path = browser.click.download_and_get_file_path("//xpath/to/button")

The return type is Path from the standard pathlib library, and so you can easily get the file name or absolute path.

For instance, this will output the file name file.zip in the terminal:

6
    print(file_path.name)

And this will output the absolute file path /home/user/downloads/file.zip in the terminal:

7
    print(file_path.absolute())