|
| 1 | +<!-- SeleniumBase Docs --> |
| 2 | + |
| 3 | +## [<img src="https://seleniumbase.github.io/img/logo6.png" title="SeleniumBase" width="32">](https://github.com/seleniumbase/SeleniumBase/) UC Mode 👤 |
| 4 | + |
| 5 | +👤 SeleniumBase <b>UC Mode</b> (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. |
| 6 | + |
| 7 | +<!-- YouTube View --><a href="https://www.youtube.com/watch?v=5dMFI3e85ig"><img src="http://img.youtube.com/vi/5dMFI3e85ig/0.jpg" title="SeleniumBase on YouTube" width="335" /></a> |
| 8 | +<!-- GitHub Only --><p>(<b><a href="https://www.youtube.com/watch?v=5dMFI3e85ig">Watch the UC Mode tutorial on YouTube</a></b>)</p> |
| 9 | + |
| 10 | +👤 <b>UC Mode</b> 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: |
| 11 | + |
| 12 | +* Includes driver version-detection & management. |
| 13 | +* Allows mismatched browser/driver versions. |
| 14 | +* Automatically changes the user agent to prevent detection. (`HeadlessChrome` to `Chrome`) |
| 15 | +* Automatically disconnects chromedriver from Chrome as needed. (And reconnects) |
| 16 | +* Supports multithreaded tests in parallel via `pytest-xdist`. |
| 17 | +* Adjusts configuration based on the environment. (Linux/Ubuntu vs Windows vs macOS) |
| 18 | +* Has options for setting proxy and proxy-with-auth. |
| 19 | +* Has ways of adjusting timings from default values. |
| 20 | +* Includes multiple ways of structuring test scripts. |
| 21 | + |
| 22 | +👤 Here's an example with the `Driver` manager: |
| 23 | + |
| 24 | +```python |
| 25 | +from seleniumbase import Driver |
| 26 | + |
| 27 | +driver = Driver(uc=True) |
| 28 | +driver.uc_open_with_reconnect("https://nowsecure.nl/#relax", 5) |
| 29 | +driver.quit() |
| 30 | +``` |
| 31 | + |
| 32 | +👤 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.) |
| 33 | + |
| 34 | +```python |
| 35 | +from seleniumbase import SB |
| 36 | + |
| 37 | +with SB(uc=True) as sb: |
| 38 | + sb.driver.uc_open_with_reconnect("https://nowsecure.nl/#relax", 5) |
| 39 | +``` |
| 40 | + |
| 41 | +👤 Here's a longer example, which includes retries and a captcha-click failsafe for bypassing detection: |
| 42 | + |
| 43 | +```python |
| 44 | +from seleniumbase import SB |
| 45 | + |
| 46 | +with SB(uc=True, test=True) as sb: |
| 47 | + sb.driver.uc_open_with_tab("https://nowsecure.nl/#relax") |
| 48 | + sb.sleep(1.2) |
| 49 | + if not sb.is_text_visible("OH YEAH, you passed!", "h1"): |
| 50 | + sb.get_new_driver(undetectable=True) |
| 51 | + sb.driver.uc_open_with_reconnect( |
| 52 | + "https://nowsecure.nl/#relax", reconnect_time=3 |
| 53 | + ) |
| 54 | + sb.sleep(1.2) |
| 55 | + if not sb.is_text_visible("OH YEAH, you passed!", "h1"): |
| 56 | + if sb.is_element_visible('iframe[src*="challenge"]'): |
| 57 | + with sb.frame_switch('iframe[src*="challenge"]'): |
| 58 | + sb.click("span.mark") |
| 59 | + sb.sleep(2) |
| 60 | + sb.activate_demo_mode() |
| 61 | + sb.assert_text("OH YEAH, you passed!", "h1", timeout=3) |
| 62 | +``` |
| 63 | + |
| 64 | +👤 Here's an example where clicking the checkbox is required, even for humans: (Commonly seen with forms that are CAPTCHA-protected.) |
| 65 | + |
| 66 | +```python |
| 67 | +from seleniumbase import SB |
| 68 | + |
| 69 | +def open_the_turnstile_page(sb): |
| 70 | + sb.driver.uc_open_with_reconnect( |
| 71 | + "https://seleniumbase.io/apps/turnstile", reconnect_time=2.5, |
| 72 | + ) |
| 73 | + |
| 74 | +def click_turnstile_and_verify(sb): |
| 75 | + sb.driver.uc_switch_to_frame("iframe") |
| 76 | + sb.driver.uc_click("span.mark") |
| 77 | + sb.assert_element("img#captcha-success", timeout=3.33) |
| 78 | + |
| 79 | +with SB(uc=True, test=True) as sb: |
| 80 | + open_the_turnstile_page(sb) |
| 81 | + try: |
| 82 | + click_turnstile_and_verify(sb) |
| 83 | + except Exception: |
| 84 | + open_the_turnstile_page(sb) |
| 85 | + click_turnstile_and_verify(sb) |
| 86 | + sb.set_messenger_theme(location="top_left") |
| 87 | + sb.post_message("Selenium wasn't detected!", duration=3) |
| 88 | +``` |
| 89 | + |
| 90 | +### 👤 Here are some examples that use UC Mode: |
| 91 | +* [SeleniumBase/examples/verify_undetected.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/verify_undetected.py) |
| 92 | +* [SeleniumBase/examples/uc_cdp_events.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/uc_cdp_events.py) |
| 93 | +* [SeleniumBase/examples/raw_uc_mode.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/raw_uc_mode.py) |
| 94 | + |
| 95 | +### 👤 Here are some UC Mode examples where clicking is required: |
| 96 | +* [SeleniumBase/examples/raw_turnstile.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/raw_turnstile.py) |
| 97 | +* [SeleniumBase/examples/raw_form_turnstile.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/raw_form_turnstile.py) |
| 98 | + |
| 99 | +### 👤 Here are `driver`-specific methods added by SeleniumBase for UC Mode: `--uc` / `uc=True` |
| 100 | + |
| 101 | +```python |
| 102 | +driver.uc_open(url) |
| 103 | + |
| 104 | +driver.uc_open_with_tab(url) |
| 105 | + |
| 106 | +driver.uc_open_with_reconnect(url, reconnect_time=None) |
| 107 | + |
| 108 | +driver.reconnect(timeout) |
| 109 | + |
| 110 | +driver.uc_click( |
| 111 | + selector, by="css selector", |
| 112 | + timeout=settings.SMALL_TIMEOUT, reconnect_time=None) |
| 113 | + |
| 114 | +driver.uc_switch_to_frame(frame) |
| 115 | +``` |
| 116 | + |
| 117 | +(Note that the `reconnect_time` is used to specify how long the driver should be disconnected from Chrome to prevent detection before reconnecting again.) |
| 118 | + |
| 119 | +👤 Since `driver.get(url)` is slower in UC Mode for bypassing detection, use `driver.default_get(url)` for a standard page load instead: |
| 120 | + |
| 121 | +```python |
| 122 | +driver.default_get(url) # Faster, but Selenium can be detected |
| 123 | +``` |
| 124 | + |
| 125 | +👤 Here are some examples of using those special UC Mode methods: (Use `self.driver` for `BaseCase` formats. Use `sb.driver` for `SB()` formats): |
| 126 | + |
| 127 | +```python |
| 128 | +driver.uc_open_with_reconnect("https://nowsecure.nl/#relax", reconnect_time=5) |
| 129 | +driver.uc_open_with_reconnect("https://nowsecure.nl/#relax", 5) |
| 130 | + |
| 131 | +driver.reconnect(5) |
| 132 | +driver.reconnect(timeout=5) |
| 133 | +``` |
| 134 | + |
| 135 | +👤 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): |
| 136 | + |
| 137 | +```python |
| 138 | +driver.uc_open_with_reconnect("https://nowsecure.nl/#relax", reconnect_time="breakpoint") |
| 139 | +driver.uc_open_with_reconnect("https://nowsecure.nl/#relax", "breakpoint") |
| 140 | + |
| 141 | +driver.reconnect(timeout="breakpoint") |
| 142 | +driver.reconnect("breakpoint") |
| 143 | +``` |
| 144 | + |
| 145 | +(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.) |
| 146 | + |
| 147 | +👤 The two main causes of getting detected in UC Mode (which are both easily handled) are: |
| 148 | +* Timing. (UC Mode methods let you customize default values that aren't good enough for your environment.) |
| 149 | +* Not using `driver.uc_click(selector)` when you need to remain undetected while clicking something. |
| 150 | + |
| 151 | +👤 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: |
| 152 | + |
| 153 | +```python |
| 154 | +from seleniumbase import SB |
| 155 | + |
| 156 | +with SB(uc=True) as sb: |
| 157 | + sb.driver.uc_open_with_reconnect(URL, reconnect_time="breakpoint") |
| 158 | +``` |
| 159 | + |
| 160 | +(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.) |
0 commit comments