# tor-browser-selenium [](https://app.travis-ci.com/webfp/tor-browser-selenium)
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](https://github.com/mozilla/geckodriver/releases/) and add it to PATH.
## 🚀 Usage
Download and extract [Tor Browser](https://www.torproject.org/projects/torbrowser.html.en), 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.
```python
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`:
```python
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](https://github.com/webfp/tor-browser-selenium/tree/master/examples) to discover different ways to use `tor-browser-selenium`
* [check_tpo.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/check_tpo.py): Visit the `check.torproject.org` website and print the network status message
* [headless.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/headless.py): Headless visit and screenshot of check.torproject.org using [PyVirtualDisplay](https://pypi.org/project/PyVirtualDisplay/)
* [onion_service.py](https://github.com/webfp/tor-browser-selenium/blob/main/examples/onion_service.py): Search using DuckDuckGo's Onion service
* [parallel.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/parallel.py): Visit `check.torproject.org`` with 3 browsers running in parallel
* [screenshot.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/screenshot.py): Take a screenshot
* [stem_simple.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/stem_simple.py): Use Stem to start a `tor` process
* [stem_adv.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/stem_adv.py): Use Stem to launch `tor` with more advanced configuration
## 🛠️ Test and development
* Browse the [existing tests](https://github.com/webfp/tor-browser-selenium/tree/main/tbselenium/test) 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:
```python
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:
```python
TorBrowserDriver(..., tbb_logfile_path='/dev/null')
```
## ⚙️ Compatibility
Warning: **Windows and macOS are not supported.**
[Tested](https://travis-ci.org/webfp/tor-browser-selenium) 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](https://travis-ci.org/webfp/tor-browser-selenium) 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.
- [Tor Browser](https://www.torproject.org/download/) needs to be downloaded and extracted.
- Python [`selenium`](https://www.selenium.dev/) (`pip install -U selenium`).
- `geckodriver` [version 0.31.0](https://github.com/mozilla/geckodriver/releases/tag/v0.31.0).
* 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](https://github.com/webfp/tor-browser-selenium/blob/master/examples/headless.py).
* 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](https://github.com/webfp/tor-browser-selenium/issues/79) for a possible solution.
* WebGL is not supported in the headless mode started with `headless=True` due to a Firefox bug ([#1375585](https://bugzilla.mozilla.org/show_bug.cgi?id=1375585)). To enable WebGL in a headless setting, use `pyvirtualdisplay` following the [headless.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/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](https://gitlab.torproject.org/tpo/applications/tor-browser-bundle-testsuite) and [tor-browser-selenium](https://github.com/isislovecruft/tor-browser-selenium) projects.
Raw data
{
"_id": null,
"home_page": "https://github.com/webfp/tor-browser-selenium",
"name": "tbselenium",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "tor, selenium, tor browser",
"author": "Gunes Acar",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/10/62/c5ae783cc1abf534b5dcbd0b04ce4c582cf90840eca9876e5fe914b257e3/tbselenium-0.9.0.tar.gz",
"platform": null,
"description": "# tor-browser-selenium [](https://app.travis-ci.com/webfp/tor-browser-selenium)\n\n\nA Python library to automate Tor Browser with Selenium WebDriver.\n\n## \ud83d\udce6 Installation\n\n> [!WARNING]\n> Windows and macOS are currently not supported.\n\n```\npip install tbselenium\n```\n\nDownload `geckodriver` v0.31.0 from the [geckodriver releases page](https://github.com/mozilla/geckodriver/releases/) and add it to PATH.\n\n## \ud83d\ude80 Usage\n\nDownload and extract [Tor Browser](https://www.torproject.org/projects/torbrowser.html.en), 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`:\n\n\n### Using with system `tor`\n\n`tor` needs to be installed (`apt install tor`) and running on port 9050.\n\n```python\nfrom tbselenium.tbdriver import TorBrowserDriver\nwith TorBrowserDriver(\"/path/to/tor-browser/\") as driver:\n driver.get('https://check.torproject.org')\n```\n\n### Using with `Stem`\nYou 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`:\n\n\n```python\nimport tbselenium.common as cm\nfrom tbselenium.tbdriver import TorBrowserDriver\nfrom tbselenium.utils import launch_tbb_tor_with_stem\n\ntbb_dir = \"/path/to/tor-browser/\"\ntor_process = launch_tbb_tor_with_stem(tbb_path=tbb_dir)\nwith TorBrowserDriver(tbb_dir, tor_cfg=cm.USE_STEM) as driver:\n driver.load_url(\"https://check.torproject.org\")\n\ntor_process.kill()\n```\n\n\n## \ud83d\udca1 Examples\nCheck the [examples](https://github.com/webfp/tor-browser-selenium/tree/master/examples) to discover different ways to use `tor-browser-selenium`\n* [check_tpo.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/check_tpo.py): Visit the `check.torproject.org` website and print the network status message\n* [headless.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/headless.py): Headless visit and screenshot of check.torproject.org using [PyVirtualDisplay](https://pypi.org/project/PyVirtualDisplay/)\n* [onion_service.py](https://github.com/webfp/tor-browser-selenium/blob/main/examples/onion_service.py): Search using DuckDuckGo's Onion service\n* [parallel.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/parallel.py): Visit `check.torproject.org`` with 3 browsers running in parallel\n* [screenshot.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/screenshot.py): Take a screenshot\n* [stem_simple.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/stem_simple.py): Use Stem to start a `tor` process\n* [stem_adv.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/stem_adv.py): Use Stem to launch `tor` with more advanced configuration\n\n\n\n## \ud83d\udee0\ufe0f Test and development\n\n* Browse the [existing tests](https://github.com/webfp/tor-browser-selenium/tree/main/tbselenium/test) to find out about different ways you can use `tor-browser-selenium`.\n\n* For development and testing first install the necessary Python packages:\n `pip install -r requirements-dev.txt`\n\n* Install the `xvfb` package by running `apt-get install xvfb` or using your distro's package manager.\n\n* Run the following to launch the tests:\n\n `./run_tests.py /path/to/tor-browser/`\n\n* By default, tests will be run using `Xvfb`, so the browser window will not be visible.\nYou may disable `Xvfb` by setting the `NO_XVFB` environment variable:\n\n `export NO_XVFB=1`\n\n\n### Running individual tests\n* First, export the path to Tor Browser folder in the `TBB_PATH` environment variable.\n\n`export TBB_PATH=/path/to/tbb/tor-browser/`\n\n* Then, use `py.test` to launch the tests you want, e.g.:\n\n* `py.test tbselenium/test/test_tbdriver.py`\n* `py.test tbselenium/test/test_tbdriver.py::TBDriverTest::test_should_load_check_tpo`\n\n\n### Using a custom `geckodriver`\nA custom `geckodriver` binary can be set via the `executable_path` argument:\n\n```python\nTorBrowserDriver(executable_path=\"/path/to/geckodriver\")\n```\n\n### Disabling console logs\nYou can redirect the logs to `/dev/null` by passing the `tbb_logfile_path` initialization parameter:\n```python\nTorBrowserDriver(..., tbb_logfile_path='/dev/null')\n```\n\n## \u2699\ufe0f Compatibility\n\nWarning: **Windows and macOS are not supported.**\n\n[Tested](https://travis-ci.org/webfp/tor-browser-selenium) with the following Tor Browser versions on Ubuntu:\n\n* **Stable**: 14.0\n* **Alpha**: 14.0a9\n\nIf you need to use a different version of Tor Browser, [view the past test runs](https://travis-ci.org/webfp/tor-browser-selenium) to find out the compatible `selenium` and `geckodriver` versions.\n\n## \ud83d\udd27 Troubleshooting\n\nSolutions to potential issues:\n\n* Make sure you have compatible dependencies. While older or newer versions may work, they may cause issues.\n - [Tor Browser](https://www.torproject.org/download/) needs to be downloaded and extracted.\n - Python [`selenium`](https://www.selenium.dev/) (`pip install -U selenium`).\n - `geckodriver` [version 0.31.0](https://github.com/mozilla/geckodriver/releases/tag/v0.31.0).\n\n* Running Firefox on the same system may help diagnose issues such as missing libraries and displays.\n* `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](https://github.com/webfp/tor-browser-selenium/blob/master/examples/headless.py).\n* Port conflict with other (`Tor`) process: Pick a different SOCKS and controller port using the `socks_port` argument.\n* 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.\n* `driver.get_cookies()` returns an empty list. This is due to Private Browsing Mode (PBM), which Selenium uses under the hood. See [#79](https://github.com/webfp/tor-browser-selenium/issues/79) for a possible solution.\n* WebGL is not supported in the headless mode started with `headless=True` due to a Firefox bug ([#1375585](https://bugzilla.mozilla.org/show_bug.cgi?id=1375585)). To enable WebGL in a headless setting, use `pyvirtualdisplay` following the [headless.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/headless.py) example.\n\n## \ud83d\udcda Reference\nPlease use the following reference if you use `tor-browser-selenium` in your academic publications.\n\n```\n@misc{tor-browser-selenium,\n author = {Gunes Acar and Marc Juarez and individual contributors},\n title = {tor-browser-selenium - Tor Browser automation with Selenium},\n year = {2023},\n publisher = {GitHub},\n howpublished = {\\url{https://github.com/webfp/tor-browser-selenium}}\n}\n```\n\n## \ud83d\ude4c Credits\nWe greatly benefited from the [tor-browser-bundle-testsuite](https://gitlab.torproject.org/tpo/applications/tor-browser-bundle-testsuite) and [tor-browser-selenium](https://github.com/isislovecruft/tor-browser-selenium) projects.\n",
"bugtrack_url": null,
"license": null,
"summary": "Tor Browser automation with Selenium",
"version": "0.9.0",
"project_urls": {
"Homepage": "https://github.com/webfp/tor-browser-selenium"
},
"split_keywords": [
"tor",
" selenium",
" tor browser"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1062c5ae783cc1abf534b5dcbd0b04ce4c582cf90840eca9876e5fe914b257e3",
"md5": "03f3f0af9136295a1684f3ec46bad7d2",
"sha256": "18ad648abd240c6493a00370044f2bcacdbf1e13e870da75e69d4ce225ec087a"
},
"downloads": -1,
"filename": "tbselenium-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "03f3f0af9136295a1684f3ec46bad7d2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23671,
"upload_time": "2024-10-23T14:59:04",
"upload_time_iso_8601": "2024-10-23T14:59:04.344660Z",
"url": "https://files.pythonhosted.org/packages/10/62/c5ae783cc1abf534b5dcbd0b04ce4c582cf90840eca9876e5fe914b257e3/tbselenium-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-23 14:59:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "webfp",
"github_project": "tor-browser-selenium",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "tbselenium"
}
JSON
