Skip to main content

Tor Browser automation with Selenium

Project description

tor-browser-selenium Build Status

A Python library to automate Tor Browser with Selenium WebDriver.

📦 Installation

[!WARNING] Windows and macOS are currently not supported.

pip install tbselenium

Download geckodriver v0.31.0 from the geckodriver releases page and add it to PATH.

🚀 Usage

Download and extract Tor Browser, and pass its folder's path when you initialize TorBrowserDriver. In the examples below, you should not pass "/path/to/tor-browser/", but the (Tor Browser) folder that contains the directory called Browser:

Using with system tor

tor needs to be installed (apt install tor) and running on port 9050.

from tbselenium.tbdriver import TorBrowserDriver
with TorBrowserDriver("/path/to/tor-browser/") as driver:
    driver.get('https://check.torproject.org')

Using with Stem

You can use Stem to start a new tor process programmatically, and connect to it from tor-browser-selenium. Make sure you have Stem installed: pip install stem:

import tbselenium.common as cm
from tbselenium.tbdriver import TorBrowserDriver
from tbselenium.utils import launch_tbb_tor_with_stem

tbb_dir = "/path/to/tor-browser/"
tor_process = launch_tbb_tor_with_stem(tbb_path=tbb_dir)
with TorBrowserDriver(tbb_dir, tor_cfg=cm.USE_STEM) as driver:
    driver.load_url("https://check.torproject.org")

tor_process.kill()

💡 Examples

Check the examples to discover different ways to use tor-browser-selenium

🛠️ Test and development

  • Browse the existing tests to find out about different ways you can use tor-browser-selenium.

  • For development and testing first install the necessary Python packages: pip install -r requirements-dev.txt

  • Install the xvfb package by running apt-get install xvfb or using your distro's package manager.

  • Run the following to launch the tests:

    ./run_tests.py /path/to/tor-browser/

  • By default, tests will be run using Xvfb, so the browser window will not be visible. You may disable Xvfb by setting the NO_XVFB environment variable:

    export NO_XVFB=1

Running individual tests

  • First, export the path to Tor Browser folder in the TBB_PATH environment variable.

export TBB_PATH=/path/to/tbb/tor-browser/

  • Then, use py.test to launch the tests you want, e.g.:

  • py.test tbselenium/test/test_tbdriver.py

  • py.test tbselenium/test/test_tbdriver.py::TBDriverTest::test_should_load_check_tpo

Using a custom geckodriver

A custom geckodriver binary can be set via the executable_path argument:

TorBrowserDriver(executable_path="/path/to/geckodriver")

Disabling console logs

You can redirect the logs to /dev/null by passing the tbb_logfile_path initialization parameter:

TorBrowserDriver(..., tbb_logfile_path='/dev/null')

⚙️ Compatibility

Warning: Windows and macOS are not supported.

Tested with the following Tor Browser versions on Ubuntu:

  • Stable: 14.0
  • Alpha: 14.0a9

If you need to use a different version of Tor Browser, view the past test runs to find out the compatible selenium and geckodriver versions.

🔧 Troubleshooting

Solutions to potential issues:

  • Make sure you have compatible dependencies. While older or newer versions may work, they may cause issues.

  • Running Firefox on the same system may help diagnose issues such as missing libraries and displays.

  • Process unexpectedly closed with status 1: If you encounter this on a remote machine you connect via SSH, you may need to enable the headless mode.

  • Port conflict with other (Tor) process: Pick a different SOCKS and controller port using the socks_port argument.

  • Use tbb_logfile_path argument of TorBrowserDriver to debug obscure errors. This can help with problems due to missing display, missing libraries (e.g. when the LD_LIBRARY_PATH is not set correctly) or other errors that Tor Browser logs to standard output/error.

  • driver.get_cookies() returns an empty list. This is due to Private Browsing Mode (PBM), which Selenium uses under the hood. See #79 for a possible solution.

  • WebGL is not supported in the headless mode started with headless=True due to a Firefox bug (#1375585). To enable WebGL in a headless setting, use pyvirtualdisplay following the headless.py example.

📚 Reference

Please use the following reference if you use tor-browser-selenium in your academic publications.

@misc{tor-browser-selenium,
  author = {Gunes Acar and Marc Juarez and individual contributors},
  title = {tor-browser-selenium - Tor Browser automation with Selenium},
  year = {2023},
  publisher = {GitHub},
  howpublished = {\url{https://github.com/webfp/tor-browser-selenium}}
}

🙌 Credits

We greatly benefited from the tor-browser-bundle-testsuite and tor-browser-selenium projects.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tbselenium-0.9.0.tar.gz (23.7 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page