browser-hybrid 0.2.3__tar.gz

browser_hybrid-0.2.3/.github/workflows/ci.yaml

@@ -0,0 +1,142 @@
+# CI/CD Pipeline for browser-hybrid
+
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+    tags: [v*]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Run ruff
+        run: ruff check src/ tests/
+
+      - name: Run ruff format check
+        run: ruff format --check src/ tests/
+
+      - name: Run mypy
+        run: mypy src/browser_hybrid/
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Run unit tests
+        run: pytest tests/ -v --cov=browser_hybrid --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+
+  integration:
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Install Chrome
+        uses: browser-actions/setup-chrome@v1
+        with:
+          chrome-version: stable
+
+      - name: Start Chrome debug mode
+        run: |
+          chrome --remote-debugging-port=9222 --headless --disable-gpu &
+          sleep 5
+
+      - name: Run integration tests
+        run: pytest tests/ -v -m integration --tb=short
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [test]
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: twine check dist/*
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

browser_hybrid-0.2.3/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+.pytype/
+
+# Build
+*.manifest
+*.spec
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Project specific
+*.log
+.env
+# Antigravity working state
+ANTIGRAVITY_PROMPTS.md

browser_hybrid-0.2.3/CHANGELOG.md

@@ -0,0 +1,156 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.3] - 2026-03-23
+
+### Added
+
+**Automatic Reconnection**
+- WebSocket reconnection: browser automatically recovers from connection drops
+- Configurable retry strategy: `reconnect_max_retries` and `reconnect_backoff` parameters
+- Reconnection monitoring: `reconnect_callback` for status updates
+- State preservation: operations are queued during reconnection and replayed after recovery
+
+### Fixed
+
+- Resource safety: background reconnection tasks are cancelled and awaited in `Browser.close()`
+- Pending task warnings: eliminated `Task was destroyed but it is pending` in tests
+
+## [0.2.2] - 2026-03-23
+
+### Added
+
+**Keyboard Input**
+- `press_key(key, modifiers=)` — Press a key with optional modifiers (Ctrl, Shift, Alt, Meta)
+- `type_slowly(ref, text, delay=)` — Type text character by character with configurable delay
+
+**Mouse Actions**
+- `hover(ref)` — Hover over element by accessibility ref
+- `click(ref, double=True)` — Double-click support
+- `click(ref, button="right")` — Right-click (context menu) support
+
+### Fixed
+
+- CI/CD: All lint (ruff), type (mypy), and test checks passing
+- Tests: Added `mock_check_connection` fixture for CI (Chrome not running)
+- Tests: `real_connection_check` marker for tests that need real connection behavior
+
+## [0.2.1] - 2026-03-23
+
+### Fixed
+
+**Cookie Operations**
+- `set_cookies()`: Now auto-derives URL from current tab when neither `url` nor `domain` provided
+- `delete_cookies()`: Derives URL from current tab when only `name` specified (CDP requires url/domain)
+- `close_tab()`: Now accepts both `Tab` object and tab ID string
+
+### Improved
+
+- Simplified cookie handling - no need to specify URL/domain when setting cookies for current page
+- Better test coverage for cookie derivation logic
+
+## [0.2.0] - 2026-03-23
+
+### Added
+
+**Wait Conditions API**
+- `wait_for_url(url=, pattern=)` — Wait for exact URL or regex pattern match
+- `wait_for_selector_visible(selector)` — Wait for element to be visible
+- `wait_for_selector_hidden(selector)` — Wait for element to be hidden/removed
+- `wait_for_function(js_function)` — Wait for custom JavaScript predicate
+- `wait_for_navigation(timeout, wait_until)` — Convenience for page loads
+
+**Cookie Management API**
+- `get_cookies(urls=)` — Get all cookies, optionally filtered by URLs
+- `set_cookies(cookies)` — Set cookies with validation (name/value required)
+- `delete_cookies(name=, url=, domain=, path=)` — Delete specific or all cookies
+
+**Network Interception API**
+- `on_request(callback)` — Monitor outgoing requests
+- `on_response(callback)` — Monitor incoming responses
+- `on_request_failed(callback)` — Handle failed requests
+- `clear_interceptors()` — Remove all registered handlers
+
+**Connection Event System**
+- `Connection.on_event(method, callback)` — Register CDP event listener
+- `Connection.off_event(method, callback)` — Unregister listener
+- Event dispatch in `_receive_loop()` for async event handling
+
+### Fixed
+
+- Timeout boundary: changed `<` to `<=` in all wait methods for full timeout window
+- Regex compilation: `wait_for_url()` compiles pattern once outside loop
+- Event listeners: cleared on connection disconnect to prevent stale callbacks
+- Thread safety: `_network_handlers` uses `setdefault` for atomic dict access
+- Cookie validation: `set_cookies()` validates `name` and `value` keys
+
+### Tests
+
+- 25 new tests added (106 total, 20 skipped)
+- Wait conditions: 13 tests
+- Cookie management: 9 tests (including validation)
+- Network interception: 7 tests
+
+## [0.1.1] - 2026-03-23
+
+### Fixed
+
+**Critical Fixes**
+- `type_text()` KeyError on `objectId` — DOM.resolveNode returns `{"object": {"objectId": ...}}`, not `{"node": {"nodeId": ...}}` (Round 3)
+- `click()` silently no-op — Chrome accessibility tree has no `[data-ax-id]` attributes; fixed with proper CDP object targeting (Round 3)
+
+**Medium Fixes**
+- Connection pool limits with LRU eviction — added `max_connections=32` default with `ConnectionPool._evict_oldest()` (Round 2)
+- Rate limiting for CDP calls — configurable `rate_limit` parameter prevents message flooding (Round 2)
+- Rate limit race condition — moved `_last_send_time` assignment before sleep (Round 3)
+- `wait_for_chrome_async` timeout boundary — changed `<` to `<=` for full timeout window (Round 4)
+- `wait_for` raises on transient errors — wrapped `evaluate()` in try/except for resilience (Round 4)
+- Accessibility tree caching — `cache_accessibility=True` with `refresh=True` to invalidate (Round 2)
+- Multiple windows documentation — documented single-window limitation with workaround (Round 2)
+- `to_dict()`/`to_json()` output methods — added to `AXNode` for structured output (Round 2)
+- Python 3.9 compatibility — `from __future__ import annotations` + proper typing imports (Round 3)
+
+**Low Fixes**
+- Logging in `_http_put` — added debug logging for HTTP operations (Round 2)
+- `__repr__` on `BrowserError` — added string representation for debugging (Round 2)
+- CLI argparse + standard exit codes — `EXIT_SUCCESS=0`, `EXIT_ERROR=1`, `EXIT_USAGE=2`, `EXIT_INTERRUPT=130` (Round 2)
+- `format` parameter shadows built-in — renamed to `fmt` in `AXNode.to_tree_str()` (Round 3)
+- Eviction disconnect fire-and-forget — documented acceptable behavior (Round 3)
+
+**Test Coverage**
+- Improved test coverage to 84% (Round 2)
+
+### Dependencies
+- Python >= 3.9 (compatibility fix)
+
+## [0.1.0] - 2024-03-22
+
+### Added
+- Initial release
+- Browser class for Chrome DevTools Protocol integration
+- Tab management (list, new, activate, close)
+- Accessibility tree parsing (`Accessibility.getFullAXTree`)
+- Element targeting by role and name
+- Click by text functionality
+- Form filling
+- Screenshot capture
+- JavaScript execution
+- CLI interface
+- Comprehensive type hints
+- Documentation and examples
+
+### Features
+- **Your authenticated sessions**: Use Gmail, banking, SSO without re-auth
+- **Accessibility tree**: Target elements like agent-browser (`[ref=e1]`)
+- **Simple API**: Python class + CLI
+- **Zero dependencies**: Only websockets package required
+
+### Breaking Changes
+- None (initial release)
+
+### Dependencies
+- Python

browser_hybrid-0.2.3/CODE_REVIEW.md

@@ -0,0 +1,289 @@
+# browser-hybrid — Code Review Round 5 (v0.2.0 Features)
+
+**Date:** 2026-03-23  
+**Branch:** feature/wait-conditions  
+**Commits:** 4  
+**Files Changed:** 4  
+**Lines Added:** ~950
+
+---
+
+## Commits Under Review
+
+```
+892780e feat: add wait conditions API
+1647bc2 feat: add cookie management API
+180454b feat: add network interception API
+0215e0e fix: Round 5 code review issues
+```
+
+---
+
+## Section-by-Section Review
+
+### 1. Wait Conditions API (browser.py lines 668-824)
+
+#### `wait_for_url()`
+
+| Check | Result |
+|-------|--------|
+| Input validation | ✅ Raises ValueError for both/neither params |
+| Transient error handling | ✅ Try/except with retry |
+| Timeout boundary | ✅ Uses `<=` |
+| Regex compilation | ✅ Compiled once, outside loop |
+| Code quality | ✅ Clear, documented |
+
+**Verdict:** ✅ PASS
+
+#### `wait_for_selector_visible()`
+
+| Check | Result |
+|-------|--------|
+| JS correctness | ✅ Checks offsetParent for visibility |
+| Transient error handling | ✅ Try/except |
+| Timeout boundary | ✅ Uses `<=` |
+| Selector escaping | ✅ Uses escape_js_string |
+
+**Verdict:** ✅ PASS
+
+#### `wait_for_selector_hidden()`
+
+| Check | Result |
+|-------|--------|
+| JS correctness | ✅ Returns true if element missing OR hidden |
+| Transient error handling | ✅ Try/except |
+| Timeout boundary | ✅ Uses `<=` |
+
+**Verdict:** ✅ PASS
+
+#### `wait_for_function()`
+
+| Check | Result |
+|-------|--------|
+| Flexible input | ✅ Accepts any JS expression |
+| Polling interval | ✅ Configurable |
+| Transient error handling | ✅ Try/except |
+
+**Verdict:** ✅ PASS
+
+#### `wait_for_navigation()`
+
+| Check | Result |
+|-------|--------|
+| Delegation | ✅ Calls wait_for_load_state correctly |
+| Parameters | ✅ Passes through timeout and wait_until |
+
+**Verdict:** ✅ PASS
+
+---
+
+### 2. Cookie Management API (browser.py lines 1413-1588)
+
+#### `get_cookies()`
+
+| Check | Result |
+|-------|--------|
+| CDP usage | ✅ Network.enable → Network.getCookies |
+| URL filtering | ✅ Optional urls param |
+| Return type | ✅ list[dict] |
+| Error handling | ⚠️ No explicit error handling |
+
+**Concern:** If Network.enable fails, error propagates. But this matches existing pattern in the codebase.
+
+**Verdict:** ✅ PASS (consistent with codebase style)
+
+#### `set_cookies()`
+
+| Check | Result |
+|-------|--------|
+| CDP usage | ✅ Network.enable → Network.setCookie (per cookie) |
+| Input validation | ⚠️ No validation of cookie dict |
+| Error handling | ⚠️ No explicit error handling |
+
+**Concern:** No validation that cookie dict has required `name` and `value`. CDP will return error, but error message won't be helpful.
+
+**Recommendation (optional):** Add validation:
+```python
+required = {"name", "value"}
+for i, cookie in enumerate(cookies):
+    if not required.issubset(cookie):
+        raise ValueError(f"Cookie {i} missing required keys: {required - set(cookie)}")
+```
+
+**Verdict:** ⚠️ PASS (but consider validation)
+
+#### `delete_cookies()`
+
+| Check | Result |
+|-------|--------|
+| CDP usage | ✅ Network.deleteCookies |
+| Clear all logic | ✅ Gets cookies then deletes each |
+| Edge case | ✅ Handles domain extraction from cookie dict |
+
+**Verdict:** ✅ PASS
+
+---
+
+### 3. Network Interception API (browser.py lines 1590-1745)
+
+#### `_on_network_event()`
+
+| Check | Result |
+|-------|--------|
+| Thread safety | ✅ Uses setdefault |
+| CDP enable | ✅ Network.enable before registering |
+| Blocking | ✅ _run_async returns result (blocks) |
+| Handler tracking | ✅ Stored in _network_handlers |
+
+**Verdict:** ✅ PASS
+
+#### `on_request()`, `on_response()`, `on_request_failed()`
+
+| Check | Result |
+|-------|--------|
+| Event names | ✅ Correct CDP event names |
+| Documentation | ✅ Clear docstrings with examples |
+
+**Verdict:** ✅ PASS
+
+#### `clear_interceptors()`
+
+| Check | Result |
+|-------|--------|
+| In-memory sync clear | ✅ _network_handlers cleared first |
+| Connection clear | ✅ _event_listeners cleared async |
+| Blocking | ✅ _run_async blocks |
+
+**Verdict:** ✅ PASS
+
+---
+
+### 4. Connection Event System (connection.py lines 55-58, 218-220, 255-260)
+
+#### Event listener storage
+
+| Check | Result |
+|-------|--------|
+| Type | ✅ dict[str, list[Callable]] |
+| Initialization | ✅ In __init__ |
+
+**Verdict:** ✅ PASS
+
+#### Event dispatch in `_receive_loop()`
+
+| Check | Result |
+|-------|--------|
+| Event detection | ✅ Checks "method" key |
+| Dispatch | ✅ _dispatch_event called |
+| Error handling | ✅ Exception caught, doesn't break loop |
+
+**Verdict:** ✅ PASS
+
+#### `_dispatch_event()`
+
+| Check | Result |
+|-------|--------|
+| Lookup | ✅ Checks method in _event_listeners |
+| Callback invocation | ✅ Iterates and calls |
+| Exception handling | ✅ Caught, silently ignored |
+
+**Verdict:** ✅ PASS
+
+#### `on_event()`, `off_event()`
+
+| Check | Result |
+|-------|--------|
+| Registration | ✅ Appends to list |
+| Removal | ✅ Removes specific or all |
+| Thread safety | ⚠️ Not thread-safe for concurrent registration |
+
+**Concern:** If two callers register listeners for same event simultaneously from different threads, list append is not atomic under dict lookup.
+
+**Analysis:** Under Python's GIL, `list.append()` is atomic. `setdefault` is also atomic. The pattern `conn.on_event(method, callback)` is fine for single-threaded use. Multi-threaded registration is a edge case.
+
+**Verdict:** ✅ PASS (acceptable for v0.2.0)
+
+#### Cleanup on disconnect
+
+| Check | Result |
+|-------|--------|
+| _event_listeners cleared | ✅ In finally block of _receive_loop |
+
+**Verdict:** ✅ PASS
+
+---
+
+### 5. Tests (test_browser.py +339 lines)
+
+#### TestWaitConditions (13 tests)
+
+| Check | Result |
+|-------|--------|
+| Coverage | ✅ All methods tested |
+| Edge cases | ✅ timeout, transient errors, invalid params |
+| Mock usage | ✅ Correct use of patch.object |
+
+**Verdict:** ✅ PASS
+
+#### TestCookies (5 tests)
+
+| Check | Result |
+|-------|--------|
+| Coverage | ✅ get, set, delete tested |
+| CDP verification | ✅ Checks correct methods called |
+| Edge cases | ⚠️ No test for missing name/value |
+
+**Recommendation:** Add test for invalid cookie dict.
+
+**Verdict:** ✅ PASS (with minor recommendation)
+
+#### TestNetworkInterception (7 tests)
+
+| Check | Result |
+|-------|--------|
+| Registration | ✅ on_event called with correct event |
+| Dispatch | ✅ _dispatch_event calls callbacks |
+| Removal | ✅ off_event removes correctly |
+| Clear | ✅ clear_interceptors empties dicts |
+
+**Verdict:** ✅ PASS
+
+---
+
+## Summary
+
+| Category | Issues | Severity |
+|----------|--------|----------|
+| Critical | 0 | — |
+| Medium | 0 | — |
+| Low | 2 | Optional improvements |
+
+### Low-Priority Recommendations
+
+| # | Issue | Status |
+|---|-------|--------|
+| 1 | Add cookie validation for `set_cookies()` | ✅ FIXED |
+| 2 | Add test for invalid cookie dict | ✅ FIXED |
+
+### Deferred (v0.3.0)
+
+- `off_request()` / `off_response()` methods for selective handler removal
+
+---
+
+## Final Verdict
+
+**✅ APPROVED FOR MERGE**
+
+All critical and medium issues from earlier review have been fixed. Code is consistent with existing patterns. Tests pass. Ready to merge to `main` and tag `v0.2.0`.
+
+---
+
+## Merge Checklist
+
+- [ ] Merge `feature/wait-conditions` to `main`
+- [ ] Update `__version__` to `"0.2.0"`
+- [ ] Update `CHANGELOG.md`
+- [ ] Run full test suite
+- [ ] Tag `v0.2.0`
+- [ ] Push

browser_hybrid-0.2.3/Makefile

@@ -0,0 +1,45 @@
+.PHONY: install dev test lint format clean build publish
+
+install:
+	pip install -e .
+
+dev:
+	pip install -e ".[dev]"
+
+test:
+	pytest tests/ -v --cov=browser_hybrid --cov-report=term-missing
+
+test-integration:
+	pytest tests/ -v -m integration
+
+lint:
+	ruff check src/
+	mypy src/browser_hybrid
+
+format:
+	ruff format src/
+
+clean:
+	rm -rf dist/ build/ *.egg-info
+	rm -rf src/browser_hybrid/__pycache__ tests/__pycache__
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+
+build: clean
+	python -m build
+
+publish: build
+	twine upload dist/*
+
+check: build
+	twine check dist/*
+
+# Run with Chrome debug mode
+debug-chrome:
+	/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+		--remote-debugging-port=9222 \
+		--user-data-dir=/tmp/chrome-debug &
+
+# Quick test
+quick:
+	python -c "from browser_hybrid import Browser; b = Browser(); print(b.get_version().browser)"