diff --git a/README.md b/README.md index 0a46472d586..3ffc840a279 100755 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ 🎖️ GUI | 📰 TestPage | 🗂️ CasePlans | -🕵️ Inspector | +👤 UC Mode | 🧬 Hybrid | 💻 Farm
diff --git a/help_docs/uc_mode.md b/help_docs/uc_mode.md new file mode 100644 index 00000000000..84ad3f0bb80 --- /dev/null +++ b/help_docs/uc_mode.md @@ -0,0 +1,160 @@ + + +## [](https://github.com/seleniumbase/SeleniumBase/) UC Mode 👤 + +👤 SeleniumBase UC Mode (Undetected-Chromedriver Mode) allows bots to appear human, which lets them evade detection from anti-bot services that try to block them or trigger CAPTCHAs on various websites. + + +

(Watch the UC Mode tutorial on YouTube)

+ +👤 UC Mode is based on [undetected-chromedriver](https://github.com/ultrafunkamsterdam/undetected-chromedriver), but includes multiple updates, fixes, and improvements to support a wider range of features and edge cases: + +* Includes driver version-detection & management. +* Allows mismatched browser/driver versions. +* Automatically changes the user agent to prevent detection. (`HeadlessChrome` to `Chrome`) +* Automatically disconnects chromedriver from Chrome as needed. (And reconnects) +* Supports multithreaded tests in parallel via `pytest-xdist`. +* Adjusts configuration based on the environment. (Linux/Ubuntu vs Windows vs macOS) +* Has options for setting proxy and proxy-with-auth. +* Has ways of adjusting timings from default values. +* Includes multiple ways of structuring test scripts. + +👤 Here's an example with the `Driver` manager: + +```python +from seleniumbase import Driver + +driver = Driver(uc=True) +driver.uc_open_with_reconnect("https://nowsecure.nl/#relax", 5) +driver.quit() +``` + +👤 Here's an example with the `SB` manager: (Has more methods than the `Driver` format, and also quits the driver automatically after the `with` block ends.) + +```python +from seleniumbase import SB + +with SB(uc=True) as sb: + sb.driver.uc_open_with_reconnect("https://nowsecure.nl/#relax", 5) +``` + +👤 Here's a longer example, which includes retries and a captcha-click failsafe for bypassing detection: + +```python +from seleniumbase import SB + +with SB(uc=True, test=True) as sb: + sb.driver.uc_open_with_tab("https://nowsecure.nl/#relax") + sb.sleep(1.2) + if not sb.is_text_visible("OH YEAH, you passed!", "h1"): + sb.get_new_driver(undetectable=True) + sb.driver.uc_open_with_reconnect( + "https://nowsecure.nl/#relax", reconnect_time=3 + ) + sb.sleep(1.2) + if not sb.is_text_visible("OH YEAH, you passed!", "h1"): + if sb.is_element_visible('iframe[src*="challenge"]'): + with sb.frame_switch('iframe[src*="challenge"]'): + sb.click("span.mark") + sb.sleep(2) + sb.activate_demo_mode() + sb.assert_text("OH YEAH, you passed!", "h1", timeout=3) +``` + +👤 Here's an example where clicking the checkbox is required, even for humans: (Commonly seen with forms that are CAPTCHA-protected.) + +```python +from seleniumbase import SB + +def open_the_turnstile_page(sb): + sb.driver.uc_open_with_reconnect( + "https://seleniumbase.io/apps/turnstile", reconnect_time=2.5, + ) + +def click_turnstile_and_verify(sb): + sb.driver.uc_switch_to_frame("iframe") + sb.driver.uc_click("span.mark") + sb.assert_element("img#captcha-success", timeout=3.33) + +with SB(uc=True, test=True) as sb: + open_the_turnstile_page(sb) + try: + click_turnstile_and_verify(sb) + except Exception: + open_the_turnstile_page(sb) + click_turnstile_and_verify(sb) + sb.set_messenger_theme(location="top_left") + sb.post_message("Selenium wasn't detected!", duration=3) +``` + +### 👤 Here are some examples that use UC Mode: +* [SeleniumBase/examples/verify_undetected.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/verify_undetected.py) +* [SeleniumBase/examples/uc_cdp_events.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/uc_cdp_events.py) +* [SeleniumBase/examples/raw_uc_mode.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/raw_uc_mode.py) + +### 👤 Here are some UC Mode examples where clicking is required: +* [SeleniumBase/examples/raw_turnstile.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/raw_turnstile.py) +* [SeleniumBase/examples/raw_form_turnstile.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/raw_form_turnstile.py) + +### 👤 Here are `driver`-specific methods added by SeleniumBase for UC Mode: `--uc` / `uc=True` + +```python +driver.uc_open(url) + +driver.uc_open_with_tab(url) + +driver.uc_open_with_reconnect(url, reconnect_time=None) + +driver.reconnect(timeout) + +driver.uc_click( + selector, by="css selector", + timeout=settings.SMALL_TIMEOUT, reconnect_time=None) + +driver.uc_switch_to_frame(frame) +``` + +(Note that the `reconnect_time` is used to specify how long the driver should be disconnected from Chrome to prevent detection before reconnecting again.) + +👤 Since `driver.get(url)` is slower in UC Mode for bypassing detection, use `driver.default_get(url)` for a standard page load instead: + +```python +driver.default_get(url) # Faster, but Selenium can be detected +``` + +👤 Here are some examples of using those special UC Mode methods: (Use `self.driver` for `BaseCase` formats. Use `sb.driver` for `SB()` formats): + +```python +driver.uc_open_with_reconnect("https://nowsecure.nl/#relax", reconnect_time=5) +driver.uc_open_with_reconnect("https://nowsecure.nl/#relax", 5) + +driver.reconnect(5) +driver.reconnect(timeout=5) +``` + +👤 You can also set the `reconnect_time` / `timeout` to `"breakpoint"` as a valid option. This allows the user to perform manual actions (until typing `c` and pressing ENTER to continue from the breakpoint): + +```python +driver.uc_open_with_reconnect("https://nowsecure.nl/#relax", reconnect_time="breakpoint") +driver.uc_open_with_reconnect("https://nowsecure.nl/#relax", "breakpoint") + +driver.reconnect(timeout="breakpoint") +driver.reconnect("breakpoint") +``` + +(Note that while the special UC Mode breakpoint is active, you can't issue Selenium commands to the browser, and the browser can't detect Selenium.) + +👤 The two main causes of getting detected in UC Mode (which are both easily handled) are: +* Timing. (UC Mode methods let you customize default values that aren't good enough for your environment.) +* Not using `driver.uc_click(selector)` when you need to remain undetected while clicking something. + +👤 To find out if UC Mode will work at all on a specific site (before adjusting for timing), load your site with the following script: + +```python +from seleniumbase import SB + +with SB(uc=True) as sb: + sb.driver.uc_open_with_reconnect(URL, reconnect_time="breakpoint") +``` + +(If you remain undetected while loading the page and performing manual actions, then you know you can create a working script once you swap the breakpoint with a time, and add special methods like `uc_click` as needed.) diff --git a/mkdocs.yml b/mkdocs.yml index 76f615cd6ed..6a87aaefed4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,7 +10,7 @@ edit_uri: "" site_dir: "site" docs_dir: "mkdocs_build" # Copyright -copyright: Copyright © 2014 - 2023 Michael Mintz +copyright: Copyright © 2014 - 2024 Michael Mintz # Extensions markdown_extensions: - admonition @@ -113,13 +113,14 @@ nav: - 📶 Chart Maker: examples/chart_maker/ReadMe.md - 🎞️ Presentation Maker: examples/presenter/ReadMe.md - Integrations: - - 📱 Mobile Testing: help_docs/mobile_testing.md + - 👤 UC Mode: help_docs/uc_mode.md - 🤖 GitHub CI: integrations/github/workflows/ReadMe.md + - 🛂 MasterQA: seleniumbase/masterqa/ReadMe.md - 🗂️ Case Plans: help_docs/case_plans.md + - 📱 Mobile Mode: help_docs/mobile_testing.md + - 🌐 Selenium Grid: seleniumbase/utilities/selenium_grid/ReadMe.md - 🖼️ Visual Testing: examples/visual_testing/ReadMe.md - 🕵️ The HTML Inspector: help_docs/html_inspector.md - - 🌐 Selenium Grid: seleniumbase/utilities/selenium_grid/ReadMe.md - - 🛂 MasterQA: seleniumbase/masterqa/ReadMe.md - 🤖 Azure Pipelines: integrations/azure/azure_pipelines/ReadMe.md - 🤖 Jenkins on Azure: integrations/azure/jenkins/ReadMe.md - 🤖 Jenkins on Google Cloud: integrations/google_cloud/ReadMe.md