A Python library to automate Tor Browser with Selenium.
Installation
pip install tbselenium
Install geckodriver
from the geckodriver releases page. Make sure you install version v0.23.0 version or newer; older versions may not be compatible with the current Tor Browser series.
Basic usage
- Using with system
tor
from tbselenium.tbdriver import TorBrowserDriver
with TorBrowserDriver("/path/to/TorBrowserBundle/") as driver:
driver.get('https://check.torproject.org')
- Using with
Stem
import tbselenium.common as cm
from tbselenium.tbdriver import TorBrowserDriver
from tbselenium.utils import launch_tbb_tor_with_stem
tbb_dir = "/path/to/TorBrowserBundle/"
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()
TorBrowserDriver does not download Tor Browser Bundle (TBB) for you. You should download, extract TBB and provide its path when you initialize TorBrowserDriver
.
Test and development
Install the Python packages that are needed for development and testing:
pip install -r requirements-dev.txt
Install 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/TorBrowserBundle/
By default, tests will be run using Xvfb
, so the browser will not be visible.
You may disable Xvfb
by exporting the following environment variable:
export NO_XVFB=1
Running individual tests
First, export a TBB_PATH
environment variable that points to the TBB version you want to use:
export TBB_PATH=/path/to/tbb/tor-browser_en-US/
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
Examples
Check the examples to discover different ways to use TorBrowserDriver
- check_tpo.py: Visit check.torproject.org website and print the network status message
- headless.py: Headless visit and screenshot of check.torproject.org using XVFB
- hidden_service.py: Search using DuckDuckGo's hidden service
- parallel.py: Visit check.torproject.org with 3 browsers running in parallel
- screenshot.py: Take a screenshot
- stem_simple.py: Using Stem to start the Tor process
- stem_adv.py: Using Stem with more advanced configuration
Compatibility
Tested with the following Tor Browser Bundle versions on Debian and Ubuntu:
- 8.0.8
- 8.5a11
Windows and macOS are not supported.
Troubleshooting
Solutions to potential issues:
- Make sure you can run Firefox on the same system. This may help discover various issues such as missing libraries, displays etc..
- Outdated (or incompatible) Python
selenium
package: This is the source of various obscure errors. Make sure you haveselenium
version 3.3 or above. - No display: When running on a cloud machine, follow the headless.py example to start a virtual display.
- Outdated Tor Browser Bundle: Download and use a more recent TBB version.
- Make sure you install geckodriver version v0.23.0 or newer.
- Port conflict with other (
Tor
) process: Pick a different SOCKS and controller port usingsocks_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. - When you use
LAUNCH_NEW_TBB_TOR
option and get the following error message during the initialization, it's likely that Tor failed to bootstrap (due to network etc.):
Can't load the profile. Profile Dir: /tmp/tmpO7i1lL/webdriver-py-profilecopy If you specified a log_file in the FirefoxBinary constructor, check it for details
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.
Credits
We greatly benefited from the following two projects:
- tor-browser-selenium by @isislovecruft.
- tor-browser-bundle-testsuite by @boklm.