selenium-turnstile 0.1.0__tar.gz

selenium_turnstile-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

selenium_turnstile-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: selenium-turnstile
+Version: 0.1.0
+Summary: Solve Cloudflare Turnstile in Selenium via the Peak API, for when SeleniumBase UC-mode or undetected-chromedriver stall headless.
+Project-URL: Homepage, https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile
+Project-URL: Documentation, https://peak.fo/docs/turnstile?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile
+Project-URL: Pricing, https://peak.fo/pricing?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile
+Project-URL: Source, https://github.com/CircuitSavage/selenium-turnstile
+Author: Peak
+License: MIT
+License-File: LICENSE
+Keywords: bypass,captcha,cloudflare,selenium,seleniumbase,solver,turnstile,undetected-chromedriver
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.8
+Provides-Extra: selenium
+Requires-Dist: selenium>=4.0; extra == 'selenium'
+Description-Content-Type: text/markdown
+
+<a href="https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile">
+  <img src="https://raw.githubusercontent.com/CircuitSavage/selenium-turnstile/main/assets/peak-banner.png" alt="Peak — solve Cloudflare Turnstile & the 5s challenge in ~1s" width="100%">
+</a>
+
+# selenium-turnstile
+
+**selenium-turnstile** is a Selenium helper that solves Cloudflare Turnstile by injecting a Peak-solved token, so a protected form or navigation proceeds without a real mouse click.
+
+## Why
+
+SeleniumBase's UC-mode click-solve (`uc_gui_click_captcha`) drives a physical click on the widget, which needs a real display and fails headless on datacenter IPs. That failure mode fills Cloudflare-related SeleniumBase issues (200+ open). undetected-chromedriver has no click-solve at all and gets stuck in the "Just a moment" loop, reloading the interstitial even after the browser has otherwise passed.
+
+This helper skips the click entirely. It reads the sitekey from the DOM, gets a token from Peak, and injects that token as the `cf-turnstile-response` value plus the widget's success callback. When your setup gets blocked, drop in a Peak API key and it just works.
+
+## Powered by Peak
+
+This package uses [Peak](https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile) to solve Turnstile.
+- Solve Cloudflare Turnstile & the 5s challenge in about a second
+- Pay only for successful solves, from $1 / 1,000
+- 1,000 free solves to start, no card.
+→ [Get your free API key](https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile) · [Docs](https://peak.fo/docs/turnstile?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile) · [Pricing](https://peak.fo/pricing?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile)
+
+## Install
+
+```bash
+pip install selenium-turnstile selenium
+```
+
+## Quickstart
+
+```python
+import os
+from selenium import webdriver
+from selenium_turnstile import solve_turnstile
+
+os.environ["PEAK_API_KEY"] = "pk_your_api_key"
+
+driver = webdriver.Chrome()
+driver.get("https://protected.example/login")
+
+# Reads the sitekey from the page, solves via Peak, injects the token.
+token = solve_turnstile(driver)
+
+driver.find_element("css selector", "form").submit()
+```
+
+Works unchanged with a plain Selenium driver, a SeleniumBase `Driver`, or an undetected-chromedriver `Chrome` — all three expose the `current_url` / `find_element` / `execute_script` interface the helper uses.
+
+## How it works
+
+1. **Read the sitekey.** `find_element` looks for the `data-sitekey` attribute on the `.cf-turnstile` widget; if the sitekey is only set through a JS `render()` call, an `execute_script` DOM scan finds it.
+2. **Solve via Peak.** `POST https://api.peak.fo/solve` with `task_type: "turnstiletask"`, the sitekey, and `url=driver.current_url`. Pass `proxy=` to mint the token from your browser's egress IP.
+3. **Inject the token.** `execute_script` sets every `cf-turnstile-response` field, fires `input`/`change` events, and calls the widget's `data-callback` success handler so the form or navigation continues.
+
+## API
+
+```python
+solve_turnstile(
+    driver,               # any Selenium-like WebDriver
+    api_key=None,         # defaults to env PEAK_API_KEY
+    proxy=None,           # optional http://user:pass@ip:port, forwarded to Peak
+    sitekey=None,         # override auto-detection (e.g. widget in a frame)
+    url=None,             # defaults to driver.current_url
+    task_type="turnstiletask",
+    timeout=180.0,
+) -> str                  # the injected token
+```
+
+Helpers `read_sitekey(driver)` and `inject_token(driver, token)` are exposed for finer control. Peak also supports `task_type="cloudflare5stask"` for the 5s interstitial challenge.
+
+The API key is read from the `PEAK_API_KEY` environment variable by default; you can also pass it explicitly. Never hardcode a real key.
+
+## Legitimate use
+
+For automation, QA, and scraping public data you are allowed to access. Respect each target's Terms of Service and robots directives, and do not use this for credential-stuffing or other abuse.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

selenium_turnstile-0.1.0/README.md

@@ -0,0 +1,79 @@
+<a href="https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile">
+  <img src="https://raw.githubusercontent.com/CircuitSavage/selenium-turnstile/main/assets/peak-banner.png" alt="Peak — solve Cloudflare Turnstile & the 5s challenge in ~1s" width="100%">
+</a>
+
+# selenium-turnstile
+
+**selenium-turnstile** is a Selenium helper that solves Cloudflare Turnstile by injecting a Peak-solved token, so a protected form or navigation proceeds without a real mouse click.
+
+## Why
+
+SeleniumBase's UC-mode click-solve (`uc_gui_click_captcha`) drives a physical click on the widget, which needs a real display and fails headless on datacenter IPs. That failure mode fills Cloudflare-related SeleniumBase issues (200+ open). undetected-chromedriver has no click-solve at all and gets stuck in the "Just a moment" loop, reloading the interstitial even after the browser has otherwise passed.
+
+This helper skips the click entirely. It reads the sitekey from the DOM, gets a token from Peak, and injects that token as the `cf-turnstile-response` value plus the widget's success callback. When your setup gets blocked, drop in a Peak API key and it just works.
+
+## Powered by Peak
+
+This package uses [Peak](https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile) to solve Turnstile.
+- Solve Cloudflare Turnstile & the 5s challenge in about a second
+- Pay only for successful solves, from $1 / 1,000
+- 1,000 free solves to start, no card.
+→ [Get your free API key](https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile) · [Docs](https://peak.fo/docs/turnstile?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile) · [Pricing](https://peak.fo/pricing?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile)
+
+## Install
+
+```bash
+pip install selenium-turnstile selenium
+```
+
+## Quickstart
+
+```python
+import os
+from selenium import webdriver
+from selenium_turnstile import solve_turnstile
+
+os.environ["PEAK_API_KEY"] = "pk_your_api_key"
+
+driver = webdriver.Chrome()
+driver.get("https://protected.example/login")
+
+# Reads the sitekey from the page, solves via Peak, injects the token.
+token = solve_turnstile(driver)
+
+driver.find_element("css selector", "form").submit()
+```
+
+Works unchanged with a plain Selenium driver, a SeleniumBase `Driver`, or an undetected-chromedriver `Chrome` — all three expose the `current_url` / `find_element` / `execute_script` interface the helper uses.
+
+## How it works
+
+1. **Read the sitekey.** `find_element` looks for the `data-sitekey` attribute on the `.cf-turnstile` widget; if the sitekey is only set through a JS `render()` call, an `execute_script` DOM scan finds it.
+2. **Solve via Peak.** `POST https://api.peak.fo/solve` with `task_type: "turnstiletask"`, the sitekey, and `url=driver.current_url`. Pass `proxy=` to mint the token from your browser's egress IP.
+3. **Inject the token.** `execute_script` sets every `cf-turnstile-response` field, fires `input`/`change` events, and calls the widget's `data-callback` success handler so the form or navigation continues.
+
+## API
+
+```python
+solve_turnstile(
+    driver,               # any Selenium-like WebDriver
+    api_key=None,         # defaults to env PEAK_API_KEY
+    proxy=None,           # optional http://user:pass@ip:port, forwarded to Peak
+    sitekey=None,         # override auto-detection (e.g. widget in a frame)
+    url=None,             # defaults to driver.current_url
+    task_type="turnstiletask",
+    timeout=180.0,
+) -> str                  # the injected token
+```
+
+Helpers `read_sitekey(driver)` and `inject_token(driver, token)` are exposed for finer control. Peak also supports `task_type="cloudflare5stask"` for the 5s interstitial challenge.
+
+The API key is read from the `PEAK_API_KEY` environment variable by default; you can also pass it explicitly. Never hardcode a real key.
+
+## Legitimate use
+
+For automation, QA, and scraping public data you are allowed to access. Respect each target's Terms of Service and robots directives, and do not use this for credential-stuffing or other abuse.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

selenium_turnstile-0.1.0/TEST.md

@@ -0,0 +1,56 @@
+# Testing
+
+The suite mocks Peak's `/solve` HTTP response and uses a fake WebDriver, so it
+needs neither a live Peak API key nor a real browser. Selenium is an optional
+import, so the tests also run with Selenium not installed.
+
+## What is covered
+
+`tests/test_solver.py` drives `solve_turnstile()` against a `FakeDriver` that
+exposes `current_url`, `find_element` (returns an element with a sample
+`data-sitekey`), and `execute_script` (records every call). `PeakClient._post`
+is patched to return `{"success": true, "data": {"token": "XXXX.TEST"}}`.
+
+Assertions:
+- Sitekey is read from the DOM (`find_element` is called).
+- Peak is called exactly once with the correct body: `task_type=turnstiletask`,
+  the sample `sitekey`, and `url` equal to `driver.current_url`; `proxy` is
+  omitted when not supplied.
+- The token is injected via `execute_script`, passed as the script argument,
+  and the injection script sets `cf-turnstile-response`.
+- `proxy=` is forwarded into the Peak body when provided.
+- `api_key` falls back to the `PEAK_API_KEY` environment variable.
+- Sitekey detection falls back to the `execute_script` DOM scan when
+  `find_element` finds nothing.
+- Missing sitekey, a Peak `success:false` response, and a missing API key each
+  raise `PeakError`.
+
+## Run
+
+```bash
+cd selenium-turnstile
+python -m unittest discover -s tests -v
+```
+
+Python 3.12 = `python`. No third-party packages required.
+
+## Observed output
+
+```
+$ python --version
+Python 3.12.0
+
+$ python -m unittest discover -s tests -v
+test_api_key_from_env (test_solver.SolveTurnstileTests.test_api_key_from_env) ... ok
+test_missing_sitekey_raises (test_solver.SolveTurnstileTests.test_missing_sitekey_raises) ... ok
+test_no_api_key_raises (test_solver.SolveTurnstileTests.test_no_api_key_raises) ... ok
+test_peak_failure_raises (test_solver.SolveTurnstileTests.test_peak_failure_raises) ... ok
+test_proxy_forwarded_to_peak (test_solver.SolveTurnstileTests.test_proxy_forwarded_to_peak) ... ok
+test_reads_sitekey_calls_peak_and_injects (test_solver.SolveTurnstileTests.test_reads_sitekey_calls_peak_and_injects) ... ok
+test_sitekey_fallback_via_execute_script (test_solver.SolveTurnstileTests.test_sitekey_fallback_via_execute_script) ... ok
+
+----------------------------------------------------------------------
+Ran 7 tests in 0.008s
+
+OK
+```

selenium_turnstile-0.1.0/examples/solve_login.py

@@ -0,0 +1,45 @@
+"""Solve a Turnstile-protected page with Selenium + Peak.
+
+Run:
+    pip install selenium selenium-turnstile
+    export PEAK_API_KEY=pk_your_api_key
+    python examples/solve_login.py
+
+Works the same with a plain Selenium Chrome/Firefox driver, a
+SeleniumBase ``Driver``, or an undetected-chromedriver ``Chrome`` -- they
+all expose the ``current_url`` / ``find_element`` / ``execute_script``
+interface that solve_turnstile needs.
+"""
+
+import os
+
+from selenium import webdriver
+
+from selenium_turnstile import solve_turnstile
+
+TARGET = "https://protected.example/login"
+
+
+def main():
+    api_key = os.environ.get("PEAK_API_KEY", "pk_your_api_key")
+
+    driver = webdriver.Chrome()
+    try:
+        driver.get(TARGET)
+
+        # Optional: route the solve through the same proxy as the browser so
+        # the token is minted from your egress IP.
+        # proxy = "http://user:pass@ip:port"
+        token = solve_turnstile(driver, api_key=api_key, proxy=None)
+        print("Injected Turnstile token:", token[:24], "...")
+
+        # The hidden cf-turnstile-response field is now set and the widget's
+        # success callback has fired. Submit the form / continue navigation.
+        driver.find_element("css selector", "form").submit()
+        print("Now on:", driver.current_url)
+    finally:
+        driver.quit()
+
+
+if __name__ == "__main__":
+    main()

selenium_turnstile-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "selenium-turnstile"
+version = "0.1.0"
+description = "Solve Cloudflare Turnstile in Selenium via the Peak API, for when SeleniumBase UC-mode or undetected-chromedriver stall headless."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [{ name = "Peak" }]
+keywords = [
+    "selenium",
+    "seleniumbase",
+    "undetected-chromedriver",
+    "cloudflare",
+    "turnstile",
+    "captcha",
+    "solver",
+    "bypass",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = []
+
+[project.optional-dependencies]
+selenium = ["selenium>=4.0"]
+
+[project.urls]
+Homepage = "https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile"
+Documentation = "https://peak.fo/docs/turnstile?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile"
+Pricing = "https://peak.fo/pricing?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=selenium-turnstile"
+Source = "https://github.com/CircuitSavage/selenium-turnstile"
+
+[tool.hatch.build.targets.wheel]
+packages = ["selenium_turnstile"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "selenium_turnstile",
+  "examples",
+  "tests",
+  "assets",
+  "README.md",
+  "LICENSE",
+  "TEST.md",
+]

selenium_turnstile-0.1.0/selenium_turnstile/__init__.py

@@ -0,0 +1,34 @@
+"""selenium-turnstile: solve Cloudflare Turnstile in Selenium via Peak.
+
+Public API::
+
+    from selenium_turnstile import solve_turnstile
+    token = solve_turnstile(driver, api_key="pk_...")
+"""
+
+from __future__ import annotations
+
+from .peak import (
+    DEFAULT_API_URL,
+    TASK_CLOUDFLARE_5S,
+    TASK_TURNSTILE,
+    PeakClient,
+    PeakError,
+    build_solve_payload,
+)
+from .solver import inject_token, read_sitekey, solve_turnstile
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "solve_turnstile",
+    "read_sitekey",
+    "inject_token",
+    "PeakClient",
+    "PeakError",
+    "build_solve_payload",
+    "DEFAULT_API_URL",
+    "TASK_TURNSTILE",
+    "TASK_CLOUDFLARE_5S",
+    "__version__",
+]

selenium_turnstile-0.1.0/selenium_turnstile/peak.py

@@ -0,0 +1,114 @@
+"""Peak API client for solving Cloudflare Turnstile.
+
+Kept free of any Selenium dependency so it can be unit tested and reused
+on its own. The HTTP call uses the standard library only.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Optional
+
+DEFAULT_API_URL = "https://api.peak.fo/solve"
+
+# task_type sent to Peak for the Turnstile widget challenge.
+TASK_TURNSTILE = "turnstiletask"
+# Peak also supports the 5s interstitial via this task_type.
+TASK_CLOUDFLARE_5S = "cloudflare5stask"
+
+
+class PeakError(RuntimeError):
+    """Raised when Peak cannot solve the challenge or the call fails."""
+
+
+def build_solve_payload(
+    sitekey: str,
+    url: str,
+    proxy: Optional[str] = None,
+    task_type: str = TASK_TURNSTILE,
+) -> dict:
+    """Build the JSON body for POST https://api.peak.fo/solve.
+
+    ``proxy`` is omitted entirely when not provided, per the Peak contract.
+    """
+    payload = {
+        "task_type": task_type,
+        "sitekey": sitekey,
+        "url": url,
+    }
+    if proxy:
+        payload["proxy"] = proxy
+    return payload
+
+
+class PeakClient:
+    """Thin client around the Peak solve endpoint."""
+
+    def __init__(
+        self,
+        api_key: str,
+        api_url: str = DEFAULT_API_URL,
+        proxy: Optional[str] = None,
+        timeout: float = 180.0,
+    ) -> None:
+        if not api_key:
+            raise PeakError(
+                "No Peak API key. Set PEAK_API_KEY (get a free key at "
+                "https://peak.fo)."
+            )
+        self.api_key = api_key
+        self.api_url = api_url
+        self.proxy = proxy
+        self.timeout = timeout
+
+    def _post(self, payload: dict) -> dict:
+        """Send the payload to Peak and return the parsed JSON response.
+
+        Isolated so tests can monkeypatch a single method instead of the
+        network. Uses only the standard library.
+        """
+        data = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(
+            self.api_url,
+            data=data,
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "X-API-Key": self.api_key,
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                body = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:  # pragma: no cover - network path
+            body = exc.read().decode("utf-8", "replace")
+        except urllib.error.URLError as exc:  # pragma: no cover - network path
+            raise PeakError(f"Peak request failed: {exc}") from exc
+        try:
+            return json.loads(body)
+        except ValueError as exc:  # pragma: no cover - defensive
+            raise PeakError(f"Peak returned non-JSON response: {body!r}") from exc
+
+    def solve(
+        self,
+        sitekey: str,
+        url: str,
+        proxy: Optional[str] = None,
+        task_type: str = TASK_TURNSTILE,
+    ) -> str:
+        """Solve a Turnstile challenge and return the token string.
+
+        Raises :class:`PeakError` on failure.
+        """
+        payload = build_solve_payload(
+            sitekey, url, proxy=proxy or self.proxy, task_type=task_type
+        )
+        result = self._post(payload)
+        if not result.get("success"):
+            raise PeakError(result.get("error") or "Peak solve failed")
+        token = (result.get("data") or {}).get("token")
+        if not token:
+            raise PeakError("Peak response missing data.token")
+        return token

selenium_turnstile-0.1.0/selenium_turnstile/solver.py

@@ -0,0 +1,150 @@
+"""Solve Cloudflare Turnstile on a live Selenium page via the Peak API.
+
+The flow is: read the Turnstile sitekey out of the DOM, ask Peak for a
+token, then inject that token back into the page (hidden input + widget
+success callback) so the form or navigation proceeds.
+
+Selenium itself is an optional import. The functions accept any object
+that quacks like a Selenium ``WebDriver`` (``current_url``,
+``find_element``, ``execute_script``), which keeps them unit testable
+without a real browser.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from .peak import DEFAULT_API_URL, TASK_TURNSTILE, PeakClient, PeakError
+
+# CSS selectors that carry the Turnstile sitekey as a data attribute.
+_SITEKEY_SELECTORS = (
+    ".cf-turnstile[data-sitekey]",
+    "[data-sitekey]",
+    "div.cf-turnstile",
+)
+
+# JS that scans the DOM for a Turnstile sitekey. Used as a fallback when
+# find_element does not turn one up (for example, sitekey configured only
+# through the JS render() call).
+_READ_SITEKEY_JS = r"""
+var el = document.querySelector('[data-sitekey]');
+if (el) { return el.getAttribute('data-sitekey'); }
+var m = (document.documentElement.outerHTML || '').match(
+    /(?:sitekey|render)\s*[:=]\s*["']((?:0x|1x)[^"']+)["']/i);
+return m ? m[1] : null;
+"""
+
+# JS that injects a solved token. Sets every cf-turnstile-response field,
+# fires input/change events so listeners react, and calls the widget's
+# success callback (data-callback global, or window.turnstile internals).
+_INJECT_TOKEN_JS = r"""
+var token = arguments[0];
+var fields = document.querySelectorAll(
+    'input[name="cf-turnstile-response"], textarea[name="cf-turnstile-response"], ' +
+    'input#cf-turnstile-response, [name="cf-turnstile-response"]');
+if (!fields.length) {
+    var holder = document.querySelector('.cf-turnstile') || document.body;
+    var inp = document.createElement('input');
+    inp.type = 'hidden';
+    inp.name = 'cf-turnstile-response';
+    holder.appendChild(inp);
+    fields = [inp];
+}
+fields.forEach(function (f) {
+    f.value = token;
+    f.dispatchEvent(new Event('input', { bubbles: true }));
+    f.dispatchEvent(new Event('change', { bubbles: true }));
+});
+var called = false;
+document.querySelectorAll('[data-callback]').forEach(function (w) {
+    var name = w.getAttribute('data-callback');
+    if (name && typeof window[name] === 'function') {
+        window[name](token);
+        called = true;
+    }
+});
+return called;
+"""
+
+
+def read_sitekey(driver) -> Optional[str]:
+    """Return the Turnstile sitekey rendered on the current page, or None.
+
+    Tries ``find_element`` against the widget's ``data-sitekey`` attribute
+    first, then falls back to an ``execute_script`` DOM scan.
+    """
+    try:
+        from selenium.webdriver.common.by import By
+
+        css = By.CSS_SELECTOR
+    except Exception:  # selenium not installed; use the raw locator string
+        css = "css selector"
+
+    for selector in _SITEKEY_SELECTORS:
+        try:
+            element = driver.find_element(css, selector)
+        except Exception:
+            continue
+        if element is None:
+            continue
+        sitekey = element.get_attribute("data-sitekey")
+        if sitekey:
+            return sitekey.strip()
+
+    sitekey = driver.execute_script(_READ_SITEKEY_JS)
+    if sitekey:
+        return str(sitekey).strip()
+    return None
+
+
+def inject_token(driver, token: str) -> None:
+    """Inject a solved token into the page's Turnstile widget."""
+    driver.execute_script(_INJECT_TOKEN_JS, token)
+
+
+def solve_turnstile(
+    driver,
+    api_key: Optional[str] = None,
+    proxy: Optional[str] = None,
+    sitekey: Optional[str] = None,
+    url: Optional[str] = None,
+    task_type: str = TASK_TURNSTILE,
+    api_url: Optional[str] = None,
+    timeout: float = 180.0,
+) -> str:
+    """Solve the Turnstile challenge on ``driver``'s current page.
+
+    Reads the sitekey from the DOM (unless ``sitekey`` is given), asks Peak
+    for a token, injects it, and returns the token.
+
+    ``api_key`` defaults to the ``PEAK_API_KEY`` environment variable.
+    ``url`` defaults to ``driver.current_url``. ``proxy`` is forwarded to
+    Peak so the token is minted from the same egress IP as the browser;
+    omit it and Peak solves without one.
+
+    Raises :class:`~selenium_turnstile.peak.PeakError` if no sitekey is
+    found or Peak cannot solve the challenge.
+    """
+    api_key = api_key or os.environ.get("PEAK_API_KEY")
+
+    if sitekey is None:
+        sitekey = read_sitekey(driver)
+    if not sitekey:
+        raise PeakError(
+            "No Turnstile sitekey found on the page. Pass sitekey= "
+            "explicitly if the widget renders in a frame or after load."
+        )
+
+    if url is None:
+        url = driver.current_url
+
+    client = PeakClient(
+        api_key,
+        api_url=api_url or DEFAULT_API_URL,
+        proxy=proxy,
+        timeout=timeout,
+    )
+    token = client.solve(sitekey, url, proxy=proxy, task_type=task_type)
+    inject_token(driver, token)
+    return token

selenium_turnstile-0.1.0/tests/test_solver.py

@@ -0,0 +1,152 @@
+"""Unit tests for selenium-turnstile.
+
+These mock Peak's HTTP response and use a fake WebDriver, so they need
+neither a live Peak key nor a real browser. Run with::
+
+    python -m unittest discover -s tests -v
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import unittest
+from unittest import mock
+
+# Make the package importable when run from the repo root or tests/ dir.
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from selenium_turnstile import PeakError, solve_turnstile  # noqa: E402
+from selenium_turnstile.peak import PeakClient  # noqa: E402
+
+SAMPLE_SITEKEY = "0x4AAAAAAADnPIDROzbs0Aaj"
+SAMPLE_URL = "https://protected.example/login"
+TEST_TOKEN = "XXXX.TEST"
+
+
+class FakeElement:
+    """Stands in for a Selenium WebElement carrying data-sitekey."""
+
+    def __init__(self, sitekey):
+        self._sitekey = sitekey
+
+    def get_attribute(self, name):
+        if name == "data-sitekey":
+            return self._sitekey
+        return None
+
+
+class FakeDriver:
+    """Minimal WebDriver double.
+
+    Records every execute_script call so tests can assert the injection,
+    and returns a sitekey-bearing element from find_element.
+    """
+
+    def __init__(self, sitekey=SAMPLE_SITEKEY, url=SAMPLE_URL):
+        self.current_url = url
+        self._sitekey = sitekey
+        self.find_element_calls = []
+        self.execute_script_calls = []
+
+    def find_element(self, by, value):
+        self.find_element_calls.append((by, value))
+        if self._sitekey is None:
+            raise RuntimeError("no such element")
+        return FakeElement(self._sitekey)
+
+    def execute_script(self, script, *args):
+        self.execute_script_calls.append((script, args))
+        # The sitekey-scan fallback expects a return value; injection ignores it.
+        if "querySelector('[data-sitekey]')" in script:
+            return self._sitekey
+        return True
+
+
+def _peak_success(*_args, **_kwargs):
+    return {"success": True, "data": {"token": TEST_TOKEN}, "cost": 0.001}
+
+
+class SolveTurnstileTests(unittest.TestCase):
+    def test_reads_sitekey_calls_peak_and_injects(self):
+        driver = FakeDriver()
+        with mock.patch.object(PeakClient, "_post", side_effect=_peak_success) as post:
+            token = solve_turnstile(driver, api_key="pk_test_key")
+
+        # Token returned unchanged from the mocked Peak response.
+        self.assertEqual(token, TEST_TOKEN)
+
+        # Sitekey was read from the DOM via find_element.
+        self.assertTrue(driver.find_element_calls)
+
+        # Peak was called exactly once with the correct body.
+        self.assertEqual(post.call_count, 1)
+        payload = post.call_args.args[0]
+        self.assertEqual(payload["task_type"], "turnstiletask")
+        self.assertEqual(payload["sitekey"], SAMPLE_SITEKEY)
+        self.assertEqual(payload["url"], SAMPLE_URL)
+        self.assertNotIn("proxy", payload)  # omitted when not provided
+
+        # Token was injected via execute_script, passed as the script arg.
+        inject_calls = [
+            c for c in driver.execute_script_calls if TEST_TOKEN in c[1]
+        ]
+        self.assertEqual(len(inject_calls), 1)
+        script, args = inject_calls[0]
+        self.assertIn("cf-turnstile-response", script)
+        self.assertEqual(args, (TEST_TOKEN,))
+
+    def test_proxy_forwarded_to_peak(self):
+        driver = FakeDriver()
+        proxy = "http://user:pass@1.2.3.4:8080"
+        with mock.patch.object(PeakClient, "_post", side_effect=_peak_success) as post:
+            solve_turnstile(driver, api_key="pk_test_key", proxy=proxy)
+        payload = post.call_args.args[0]
+        self.assertEqual(payload["proxy"], proxy)
+
+    def test_api_key_from_env(self):
+        driver = FakeDriver()
+        with mock.patch.dict(os.environ, {"PEAK_API_KEY": "pk_env_key"}):
+            with mock.patch.object(PeakClient, "_post", side_effect=_peak_success):
+                token = solve_turnstile(driver)
+        self.assertEqual(token, TEST_TOKEN)
+
+    def test_sitekey_fallback_via_execute_script(self):
+        # find_element finds nothing; the JS DOM scan supplies the sitekey.
+        driver = FakeDriver(sitekey=None)
+        driver._sitekey = None
+
+        def exec_script(script, *args):
+            driver.execute_script_calls.append((script, args))
+            if "querySelector('[data-sitekey]')" in script:
+                return SAMPLE_SITEKEY
+            return True
+
+        driver.execute_script = exec_script
+        with mock.patch.object(PeakClient, "_post", side_effect=_peak_success) as post:
+            token = solve_turnstile(driver, api_key="pk_test_key")
+        self.assertEqual(token, TEST_TOKEN)
+        self.assertEqual(post.call_args.args[0]["sitekey"], SAMPLE_SITEKEY)
+
+    def test_missing_sitekey_raises(self):
+        driver = FakeDriver(sitekey=None)
+        driver.execute_script = lambda script, *args: None
+        with self.assertRaises(PeakError):
+            solve_turnstile(driver, api_key="pk_test_key")
+
+    def test_peak_failure_raises(self):
+        driver = FakeDriver()
+        fail = {"success": False, "error": "insufficient balance"}
+        with mock.patch.object(PeakClient, "_post", return_value=fail):
+            with self.assertRaises(PeakError):
+                solve_turnstile(driver, api_key="pk_test_key")
+
+    def test_no_api_key_raises(self):
+        driver = FakeDriver()
+        with mock.patch.dict(os.environ, {}, clear=True):
+            with self.assertRaises(PeakError):
+                solve_turnstile(driver)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)