Merge pull request #369 from autoscrape-labs/fix/go-to-navigation-robustness

Remove humanize True as default and fix tests

Author: thalissonvs

docs/en/features/automation/human-interactions.md

@@ -5,9 +5,9 @@ One of the key differentiators between successful automation and easily-detected
 !!! info "Feature Status"
     **Already Implemented:**
 
-    - **Humanized Keyboard**: Variable typing speed, realistic typos with auto-correction (`humanize=True`)
-    - **Humanized Scroll**: Physics-based scrolling with momentum, friction, jitter, and overshoot (`humanize=True`)
-    - **Humanized Mouse**: Bezier curve paths, Fitts's Law timing, minimum-jerk velocity, tremor, and overshoot (`humanize=True`)
+    - **Humanized Keyboard**: Variable typing speed, realistic typos with auto-correction (pass `humanize=True`)
+    - **Humanized Scroll**: Physics-based scrolling with momentum, friction, jitter, and overshoot (pass `humanize=True`)
+    - **Humanized Mouse**: Bezier curve paths, Fitts's Law timing, minimum-jerk velocity, tremor, and overshoot (pass `humanize=True`)
 
     **Coming Soon:**
 
@@ -195,14 +195,14 @@ Pydoll's keyboard API provides two typing modes to balance speed and stealth.
 !!! info "Understanding Typing Modes"
     | Mode | Parameters | Behavior | Use Case |
     |------|------------|----------|----------|
-    | **Default (Humanized)** | `humanize=True` | Variable timing, ~2% typo rate with auto-correction | **Anti-bot evasion** (default) |
-    | **Fast** | `humanize=False` | Fixed 50ms intervals, no typos | Speed-critical, low-risk scenarios |
+    | **Default (Fast)** | `humanize=False` | Fixed 50ms intervals, no typos | Speed-critical, low-risk scenarios (default) |
+    | **Humanized** | `humanize=True` | Variable timing, ~2% typo rate with auto-correction | **Anti-bot evasion** |
 
-    The `interval` parameter is deprecated. Use the default `humanize=True` for realistic typing.
+    The `interval` parameter is deprecated. Pass `humanize=True` for realistic typing.
 
 ### Natural Typing with Humanization
 
-By default, `type_text()` uses humanized mode, simulating realistic human typing with variable speeds and occasional typos that are automatically corrected:
+When `humanize=True` is passed, `type_text()` uses humanized mode, simulating realistic human typing with variable speeds and occasional typos that are automatically corrected:
 
 ```python
 import asyncio
@@ -218,8 +218,8 @@ async def natural_typing():
 
         # Variable speed: 30-120ms between keystrokes
         # ~2% typo rate with realistic correction behavior
-        await username_field.type_text("john.doe@example.com")  # humanize=True by default
-        await password_field.type_text("MyC0mpl3xP@ssw0rd!")
+        await username_field.type_text("john.doe@example.com", humanize=True)
+        await password_field.type_text("MyC0mpl3xP@ssw0rd!", humanize=True)
 
 asyncio.run(natural_typing())
 ```
@@ -239,14 +239,14 @@ async def fast_vs_realistic_input():
 
         username = await tab.find(id="username")
         await username.click()
-        await username.type_text("john_doe")  # humanize=True by default
+        await username.type_text("john_doe", humanize=True)
 
         hidden_field = await tab.find(id="hidden-token")
         await hidden_field.insert_text("very-long-generated-token-12345678")
 
         comment = await tab.find(id="comment-box")
         await comment.click()
-        await comment.type_text("This looks like human input!")  # humanize=True by default
+        await comment.type_text("This looks like human input!", humanize=True)
 
 asyncio.run(fast_vs_realistic_input())
 ```
@@ -263,11 +263,11 @@ Pydoll provides a dedicated scroll API that waits for scroll completion before p
 
     | Mode | Parameters | Behavior | Use Case |
     |------|------------|----------|----------|
-    | **Humanized (Default)** | `humanize=True` | Physics engine with momentum, jitter, overshoot | **Anti-bot evasion** (default) |
-    | **Smooth** | `humanize=False, smooth=True` | CSS-based animation, predictable | General browsing simulation |
-    | **Instant** | `humanize=False, smooth=False` | Teleports to position immediately | Speed-critical operations |
+    | **Smooth (Default)** | `smooth=True` | CSS-based animation, predictable | General browsing simulation (default) |
+    | **Humanized** | `humanize=True` | Physics engine with momentum, jitter, overshoot | **Anti-bot evasion** |
+    | **Instant** | `smooth=False` | Teleports to position immediately | Speed-critical operations |
 
-    Humanized scrolling is now the default. Pass `humanize=False` to use CSS-based or instant scrolling.
+    Pass `humanize=True` for physics-based humanized scrolling to evade bot detection.
 
 ### Basic Directional Scrolling
 
@@ -283,10 +283,10 @@ async def basic_scrolling():
         tab = await browser.start()
         await tab.go_to('https://example.com/long-page')
 
-        # Humanized (default) - physics engine with Bezier curves
+        # Humanized - physics engine with Bezier curves
         # Includes: momentum, friction, jitter, micro-pauses, overshoot
-        await tab.scroll.by(ScrollPosition.DOWN, 500)
-        await tab.scroll.by(ScrollPosition.UP, 300)
+        await tab.scroll.by(ScrollPosition.DOWN, 500, humanize=True)
+        await tab.scroll.by(ScrollPosition.UP, 300, humanize=True)
 
         # CSS-based animation - looks nice but predictable timing
         await tab.scroll.by(ScrollPosition.DOWN, 500, humanize=False, smooth=True)
@@ -313,10 +313,10 @@ async def scroll_to_positions():
         # Read the beginning of the article
         await asyncio.sleep(2.0)
 
-        # Humanized scroll (default, physics engine, anti-bot evasion)
-        await tab.scroll.to_bottom()
+        # Humanized scroll (physics engine, anti-bot evasion)
+        await tab.scroll.to_bottom(humanize=True)
         await asyncio.sleep(1.5)
-        await tab.scroll.to_top()
+        await tab.scroll.to_top(humanize=True)
 
         # CSS smooth scroll (predictable animation)
         await tab.scroll.to_bottom(humanize=False, smooth=True)
@@ -327,9 +327,9 @@ asyncio.run(scroll_to_positions())
 ```
 
 !!! tip "Choosing the Right Mode"
-    - **Default** (`humanize=True`): Best for anti-bot evasion, used automatically
-    - **`humanize=False, smooth=True`**: Good for demos, screenshots, and general automation
-    - **`humanize=False, smooth=False`**: Maximum speed when stealth is not a concern
+    - **`humanize=True`**: Best for anti-bot evasion
+    - **Default** (`smooth=True`): Good for demos, screenshots, and general automation
+    - **`smooth=False`**: Maximum speed when stealth is not a concern
 
 ### Human-Like Scrolling Patterns
 

docs/en/features/automation/mouse-control.md

@@ -1,6 +1,6 @@
 # Mouse Control
 
-The Mouse API provides complete control over mouse input at the page level, enabling you to simulate realistic cursor movement, clicks, double-clicks, and drag operations. By default, all mouse operations use humanized simulation: paths follow natural Bezier curves with Fitts's Law timing, minimum-jerk velocity profiles, physiological tremor, and overshoot correction, making automation virtually indistinguishable from human behavior.
+The Mouse API provides complete control over mouse input at the page level, enabling you to simulate realistic cursor movement, clicks, double-clicks, and drag operations. When `humanize=True` is passed, mouse operations use humanized simulation: paths follow natural Bezier curves with Fitts's Law timing, minimum-jerk velocity profiles, physiological tremor, and overshoot correction, making automation virtually indistinguishable from human behavior.
 
 !!! info "Centralized Mouse Interface"
     All mouse operations are accessible via `tab.mouse`, providing a clean, unified API for all mouse interactions.
@@ -15,10 +15,10 @@ async with Chrome() as browser:
     tab = await browser.start()
     await tab.go_to('https://example.com')
 
-    # Move cursor to position (humanized by default)
+    # Move cursor to position
     await tab.mouse.move(500, 300)
 
-    # Click at position (humanized by default)
+    # Click at position
     await tab.mouse.click(500, 300)
 
     # Right-click
@@ -38,18 +38,18 @@ async with Chrome() as browser:
 Move the mouse cursor to a specific position on the page:
 
 ```python
-# Humanized move (default, curved path with natural timing)
+# Default move (single CDP event, no simulation)
 await tab.mouse.move(500, 300)
 
-# Instant move (single CDP event, no simulation)
-await tab.mouse.move(500, 300, humanize=False)
+# Humanized move (curved path with natural timing)
+await tab.mouse.move(500, 300, humanize=True)
 ```
 
 **Parameters:**
 
 - `x`: Target X coordinate (CSS pixels)
 - `y`: Target Y coordinate (CSS pixels)
-- `humanize` (keyword-only): Simulate human-like curved movement (default: `True`)
+- `humanize` (keyword-only): Simulate human-like curved movement (default: `False`)
 
 ### click: Click at Position
 
@@ -58,7 +58,7 @@ Move to position and perform a mouse click:
 ```python
 from pydoll.protocol.input.types import MouseButton
 
-# Left click with humanized movement (default)
+# Left click (default, instant)
 await tab.mouse.click(500, 300)
 
 # Right click
@@ -67,8 +67,8 @@ await tab.mouse.click(500, 300, button=MouseButton.RIGHT)
 # Double click via click_count
 await tab.mouse.click(500, 300, click_count=2)
 
-# Instant click without humanization
-await tab.mouse.click(500, 300, humanize=False)
+# Humanized click with natural movement
+await tab.mouse.click(500, 300, humanize=True)
 ```
 
 **Parameters:**
@@ -77,7 +77,7 @@ await tab.mouse.click(500, 300, humanize=False)
 - `y`: Target Y coordinate
 - `button` (keyword-only): Mouse button, one of `LEFT`, `RIGHT`, `MIDDLE` (default: `LEFT`)
 - `click_count` (keyword-only): Number of clicks (default: `1`)
-- `humanize` (keyword-only): Simulate human-like behavior (default: `True`)
+- `humanize` (keyword-only): Simulate human-like behavior (default: `False`)
 
 ### double_click: Double-Click at Position
 
@@ -111,39 +111,39 @@ These are primitives that operate at the current cursor position and have no `hu
 Move from start to end while holding the mouse button:
 
 ```python
-# Humanized drag (default)
+# Default drag (instant)
 await tab.mouse.drag(100, 200, 500, 400)
 
-# Instant drag without humanization
-await tab.mouse.drag(100, 200, 500, 400, humanize=False)
+# Humanized drag with natural movement
+await tab.mouse.drag(100, 200, 500, 400, humanize=True)
 ```
 
 **Parameters:**
 
 - `start_x`, `start_y`: Start coordinates
 - `end_x`, `end_y`: End coordinates
-- `humanize` (keyword-only): Simulate human-like drag (default: `True`)
+- `humanize` (keyword-only): Simulate human-like drag (default: `False`)
 
-## Disabling Humanization
+## Enabling Humanization
 
-All mouse methods default to `humanize=True`. To perform instant, non-humanized operations, pass `humanize=False`:
+All mouse methods default to `humanize=False`. To enable humanized simulation with natural Bezier curve paths and realistic timing, pass `humanize=True`:
 
 ```python
-# Instant move, single CDP mouseMoved event
-await tab.mouse.move(500, 300, humanize=False)
+# Humanized move, natural curved path with Fitts's Law timing
+await tab.mouse.move(500, 300, humanize=True)
 
-# Instant click: move + press + release, no simulation
-await tab.mouse.click(500, 300, humanize=False)
+# Humanized click: curved movement + pre-click pause + press + release
+await tab.mouse.click(500, 300, humanize=True)
 
-# Instant drag, no curves, no pauses
-await tab.mouse.drag(100, 200, 500, 400, humanize=False)
+# Humanized drag, natural curves and pauses
+await tab.mouse.drag(100, 200, 500, 400, humanize=True)
 ```
 
-This is useful when speed is critical and detection evasion is not a concern, for example in testing environments or internal tools.
+This is recommended when detection evasion is important, for example when interacting with sites that employ bot detection.
 
 ## Humanized Mode
 
-When `humanize=True` (the default), the mouse module applies multiple layers of realism:
+When `humanize=True` is passed, the mouse module applies multiple layers of realism:
 
 ### Bezier Curve Paths
 
@@ -171,18 +171,18 @@ Humanized clicks include a pre-click pause (50–200ms) that simulates the natur
 
 ## Automatic Humanized Element Clicks
 
-When you use `element.click()`, the Mouse API is automatically used to produce a realistic Bezier curve movement from the current cursor position to the element center before clicking. This means every `element.click()` call generates natural mouse movement, making element clicks indistinguishable from human behavior.
+When you use `element.click(humanize=True)`, the Mouse API is used to produce a realistic Bezier curve movement from the current cursor position to the element center before clicking, making element clicks indistinguishable from human behavior.
 
 ```python
-# Humanized click (default): Bezier curve movement + click
+# Default click: raw CDP press/release
 button = await tab.find(id='submit')
 await button.click()
 
 # With offset from center
 await button.click(x_offset=10, y_offset=5)
 
-# Disable humanization: raw CDP press/release, no cursor movement
-await button.click(humanize=False)
+# Humanized click: Bezier curve movement + click
+await button.click(humanize=True)
 ```
 
 Position tracking is maintained across element clicks. Clicking element A, then element B, produces a natural curved path from A's position to B.

docs/pt/features/automation/human-interactions.md

@@ -5,9 +5,9 @@ Um dos principais diferenciais entre uma automação bem-sucedida e bots facilme
 !!! info "Status das Funcionalidades"
     **Já Implementado:**
 
-    - **Teclado Humanizado**: Velocidade de digitação variável, erros realistas com correção automática (`humanize=True`)
-    - **Scroll Humanizado**: Rolagem baseada em física com momentum, fricção, jitter e overshoot (`humanize=True`)
-    - **Mouse Humanizado**: Trajetórias com curvas de Bezier, temporização pela Lei de Fitts, velocidade minimum-jerk, tremor e overshoot (`humanize=True`)
+    - **Teclado Humanizado**: Velocidade de digitação variável, erros realistas com correção automática (passe `humanize=True`)
+    - **Scroll Humanizado**: Rolagem baseada em física com momentum, fricção, jitter e overshoot (passe `humanize=True`)
+    - **Mouse Humanizado**: Trajetórias com curvas de Bezier, temporização pela Lei de Fitts, velocidade minimum-jerk, tremor e overshoot (passe `humanize=True`)
 
     **Em Breve:**
 
@@ -195,14 +195,14 @@ A API de teclado do Pydoll fornece dois modos de digitação para equilibrar vel
 !!! info "Entendendo os Modos de Digitação"
     | Modo | Parâmetros | Comportamento | Caso de Uso |
     |------|------------|---------------|-------------|
-    | **Padrão (Humanizado)** | `humanize=True` | Timing variável, ~2% de taxa de erros com correção automática | **Evasão anti-bot** (padrão) |
-    | **Rápido** | `humanize=False` | Intervalos fixos de 50ms, sem erros | Cenários de velocidade, baixo risco |
+    | **Padrão (Rápido)** | `humanize=False` | Intervalos fixos de 50ms, sem erros | Cenários de velocidade, baixo risco (padrão) |
+    | **Humanizado** | `humanize=True` | Timing variável, ~2% de taxa de erros com correção automática | **Evasão anti-bot** |
 
-    O parâmetro `interval` está obsoleto. Use o padrão `humanize=True` para digitação realista.
+    O parâmetro `interval` está obsoleto. Passe `humanize=True` para digitação realista.
 
 ### Digitação Natural com Humanização
 
-Por padrão, `type_text()` usa modo humanizado, simulando digitação humana realista com velocidades variáveis e erros ocasionais que são corrigidos automaticamente:
+Quando `humanize=True` é passado, `type_text()` usa modo humanizado, simulando digitação humana realista com velocidades variáveis e erros ocasionais que são corrigidos automaticamente:
 
 ```python
 import asyncio
@@ -218,8 +218,8 @@ async def natural_typing():
 
         # Velocidade variável: 30-120ms entre teclas
         # ~2% de taxa de erros com comportamento de correção realista
-        await username_field.type_text("john.doe@example.com")  # humanize=True por padrão
-        await password_field.type_text("MyC0mpl3xP@ssw0rd!")
+        await username_field.type_text("john.doe@example.com", humanize=True)
+        await password_field.type_text("MyC0mpl3xP@ssw0rd!", humanize=True)
 
 asyncio.run(natural_typing())
 ```
@@ -266,11 +266,11 @@ O Pydoll fornece uma API dedicada de scroll que aguarda a conclusão da rolagem
 
     | Modo | Parâmetros | Comportamento | Caso de Uso |
     |------|------------|---------------|-------------|
-    | **Humanizado (Padrão)** | `humanize=True` | Motor de física com momentum, jitter, overshoot | **Evasão anti-bot** (padrão) |
-    | **Suave** | `humanize=False, smooth=True` | Animação CSS, previsível | Simulação de navegação geral |
-    | **Instantâneo** | `humanize=False, smooth=False` | Teletransporta para a posição imediatamente | Operações focadas em velocidade |
+    | **Suave (Padrão)** | `smooth=True` | Animação CSS, previsível | Simulação de navegação geral (padrão) |
+    | **Humanizado** | `humanize=True` | Motor de física com momentum, jitter, overshoot | **Evasão anti-bot** |
+    | **Instantâneo** | `smooth=False` | Teletransporta para a posição imediatamente | Operações focadas em velocidade |
 
-    A rolagem humanizada é agora o padrão. Passe `humanize=False` para usar rolagem CSS ou instantânea.
+    Passe `humanize=True` para rolagem humanizada baseada em física para evasão anti-bot.
 
 ### Rolagem Básica por Direção
 
@@ -286,10 +286,10 @@ async def basic_scrolling():
         tab = await browser.start()
         await tab.go_to('https://example.com/long-page')
 
-        # Humanizado (padrão) - motor de física com curvas de Bezier
+        # Humanizado - motor de física com curvas de Bezier
         # Inclui: momentum, fricção, jitter, micro-pausas, overshoot
-        await tab.scroll.by(ScrollPosition.DOWN, 500)
-        await tab.scroll.by(ScrollPosition.UP, 300)
+        await tab.scroll.by(ScrollPosition.DOWN, 500, humanize=True)
+        await tab.scroll.by(ScrollPosition.UP, 300, humanize=True)
 
         # Animação CSS - visual agradável mas timing previsível
         await tab.scroll.by(ScrollPosition.DOWN, 500, humanize=False, smooth=True)
@@ -316,10 +316,10 @@ async def scroll_to_positions():
         # Ler o início do artigo
         await asyncio.sleep(2.0)
 
-        # Scroll humanizado (padrão, motor de física, evasão anti-bot)
-        await tab.scroll.to_bottom()
+        # Scroll humanizado (motor de física, evasão anti-bot)
+        await tab.scroll.to_bottom(humanize=True)
         await asyncio.sleep(1.5)
-        await tab.scroll.to_top()
+        await tab.scroll.to_top(humanize=True)
 
         # Scroll suave CSS (animação previsível)
         await tab.scroll.to_bottom(humanize=False, smooth=True)
@@ -330,9 +330,9 @@ asyncio.run(scroll_to_positions())
 ```
 
 !!! tip "Escolhendo o Modo Certo"
-    - **Padrão** (`humanize=True`): Melhor para evasão anti-bot, usado automaticamente
-    - **`humanize=False, smooth=True`**: Bom para demos, screenshots e automação geral
-    - **`humanize=False, smooth=False`**: Velocidade máxima quando a furtividade não é uma preocupação
+    - **`humanize=True`**: Melhor para evasão anti-bot
+    - **Padrão** (`smooth=True`): Bom para demos, screenshots e automação geral
+    - **`smooth=False`**: Velocidade máxima quando a furtividade não é uma preocupação
 
 ### Padrões de Rolagem Semelhantes a Humanos