Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
add upload command to CLI, extract find_file_input_near_element to BrowserSession
ShawnPana694a111fad99
diff --git a/browser_use/browser/session.py b/browser_use/browser/session.pyindex 6ceb2d253..0d948f312 100644--- a/browser_use/browser/session.py+++ b/browser_use/browser/session.py@@ -2470,6 +2470,62 @@ class BrowserSession(BaseModel):and element.attributes.get('type', '').lower() == 'file')+ def find_file_input_near_element(+ self,+ node: 'EnhancedDOMTreeNode',+ max_height: int = 3,+ max_descendant_depth: int = 3,+ ) -> 'EnhancedDOMTreeNode | None':+ """Find the closest file input to the given element.++ Walks up the DOM tree (up to max_height levels), checking the node itself,+ its descendants (up to max_descendant_depth deep), and siblings at each level.++ Args:+ node: Starting DOM element+ max_height: Maximum levels to walk up the parent chain+ max_descendant_depth: Maximum depth to search descendants++ Returns:+ The nearest file input element, or None if not found+ """+ from browser_use.dom.views import EnhancedDOMTreeNode++ def _find_in_descendants(n: EnhancedDOMTreeNode, depth: int) -> EnhancedDOMTreeNode | None:+ if depth < 0:+ return None+ if self.is_file_input(n):+ return n+ for child in n.children_nodes or []:+ result = _find_in_descendants(child, depth - 1)+ if result:+ return result+ return None++ current: EnhancedDOMTreeNode | None = node+ for _ in range(max_height + 1):+ if current is None:+ break+ # Check the current node itself+ if self.is_file_input(current):+ return current+ # Check all descendants of the current node+ result = _find_in_descendants(current, max_descendant_depth)+ if result:+ return result+ # Check all siblings and their descendants+ if current.parent_node:+ for sibling in current.parent_node.children_nodes or []:+ if sibling is current:+ continue+ if self.is_file_input(sibling):+ return sibling+ result = _find_in_descendants(sibling, max_descendant_depth)+ if result:+ return result+ current = current.parent_node+ return None+async def get_selector_map(self) -> dict[int, EnhancedDOMTreeNode]:"""Get the current selector map from cached state or DOM watchdog.diff --git a/browser_use/skill_cli/README.md b/browser_use/skill_cli/README.mdindex d3b48040f..e385d6fe2 100644--- a/browser_use/skill_cli/README.md+++ b/browser_use/skill_cli/README.md@@ -136,6 +136,7 @@ browser-use --cdp-url ws://localhost:9222/devtools/browser/... state| `keys "Enter"` | Send keyboard keys || `keys "Control+a"` | Send key combination || `select <index> "value"` | Select dropdown option |+| `upload <index> <path>` | Upload file to file input element || `hover <index>` | Hover over element || `dblclick <index>` | Double-click element || `rightclick <index>` | Right-click element |diff --git a/browser_use/skill_cli/commands/browser.py b/browser_use/skill_cli/commands/browser.pyindex 34a97d077..af3b82cb7 100644--- a/browser_use/skill_cli/commands/browser.py+++ b/browser_use/skill_cli/commands/browser.py@@ -23,6 +23,7 @@ COMMANDS = {'close-tab','keys','select',+ 'upload','eval','extract','cookies',@@ -236,6 +237,42 @@ async def handle(action: str, session: SessionInfo, params: dict[str, Any]) -> Aawait bs.event_bus.dispatch(SelectDropdownOptionEvent(node=node, text=value))return {'selected': value, 'element': index}+ elif action == 'upload':+ from browser_use.browser.events import UploadFileEvent++ index = params['index']+ file_path = params['path']++ # Validate file exists and is non-empty+ p = Path(file_path)+ if not p.exists():+ return {'error': f'File not found: {file_path}'}+ if not p.is_file():+ return {'error': f'Not a file: {file_path}'}+ if p.stat().st_size == 0:+ return {'error': f'File is empty (0 bytes): {file_path}'}++ # Look up node+ node = await bs.get_element_by_index(index)+ if node is None:+ return {'error': f'Element index {index} not found - page may have changed'}++ # Find file input near the element (reuses core library heuristic)+ file_input_node = bs.find_file_input_near_element(node)++ if file_input_node is None:+ # Scan selector map for file inputs and suggest them+ selector_map = await bs.get_selector_map()+ file_input_indices = [idx for idx, el in selector_map.items() if bs.is_file_input(el)]+ if file_input_indices:+ hint = f' File input(s) found at index: {", ".join(map(str, file_input_indices))}'+ else:+ hint = ' No file input found on the page.'+ return {'error': f'Element {index} is not a file input.{hint}'}++ await bs.event_bus.dispatch(UploadFileEvent(node=file_input_node, file_path=file_path))+ return {'uploaded': file_path, 'element': index}+elif action == 'eval':js = params['js']# Execute JavaScript via CDPdiff --git a/browser_use/skill_cli/main.py b/browser_use/skill_cli/main.pyindex b88881417..29dcaa310 100755--- a/browser_use/skill_cli/main.py+++ b/browser_use/skill_cli/main.py@@ -457,6 +457,11 @@ Setup:p.add_argument('index', type=int, help='Element index')p.add_argument('value', help='Value to select')+ # upload <index> <path>+ p = subparsers.add_parser('upload', help='Upload file to file input element')+ p.add_argument('index', type=int, help='Element index of file input')+ p.add_argument('path', help='Path to file to upload')+# eval <js>p = subparsers.add_parser('eval', help='Execute JavaScript')p.add_argument('js', help='JavaScript code to execute')@@ -1017,6 +1022,10 @@ def main() -> int:if key not in skip_keys and value is not None:params[key] = value+ # Resolve file paths to absolute before sending to daemon (daemon may have different CWD)+ if args.command == 'upload' and 'path' in params:+ params['path'] = str(Path(params['path']).expanduser().resolve())+# Add profile to params for commands that need itif args.profile:params['profile'] = args.profilediff --git a/browser_use/skill_cli/python_session.py b/browser_use/skill_cli/python_session.pyindex 883a11f82..ebe458b49 100644--- a/browser_use/skill_cli/python_session.py+++ b/browser_use/skill_cli/python_session.py@@ -189,6 +189,34 @@ class BrowserWrapper:await self._session.event_bus.dispatch(ClickElementEvent(node=node))await self._session.event_bus.dispatch(TypeTextEvent(node=node, text=text))+ def upload(self, index: int, path: str) -> None:+ """Upload a file to a file input element."""+ self._run(self._upload_async(index, path))++ async def _upload_async(self, index: int, path: str) -> None:+ from pathlib import Path as P++ from browser_use.browser.events import UploadFileEvent++ file_path = str(P(path).expanduser().resolve())+ p = P(file_path)+ if not p.exists():+ raise FileNotFoundError(f'File not found: {file_path}')+ if not p.is_file():+ raise ValueError(f'Not a file: {file_path}')+ if p.stat().st_size == 0:+ raise ValueError(f'File is empty (0 bytes): {file_path}')++ node = await self._session.get_element_by_index(index)+ if node is None:+ raise ValueError(f'Element index {index} not found')++ file_input_node = self._session.find_file_input_near_element(node)+ if file_input_node is None:+ raise ValueError(f'Element {index} is not a file input and no file input found nearby')++ await self._session.event_bus.dispatch(UploadFileEvent(node=file_input_node, file_path=file_path))+def scroll(self, direction: Literal['up', 'down', 'left', 'right'] = 'down', amount: int = 500) -> None:"""Scroll the page."""self._run(self._scroll_async(direction, amount))diff --git a/browser_use/tools/service.py b/browser_use/tools/service.pyindex b20a49af4..17f0913fc 100644--- a/browser_use/tools/service.py+++ b/browser_use/tools/service.py@@ -775,49 +775,8 @@ class Tools(Generic[Context]):node = selector_map[params.index]- # Helper function to find file input near the selected element- def find_file_input_near_element(- node: EnhancedDOMTreeNode, max_height: int = 3, max_descendant_depth: int = 3- ) -> EnhancedDOMTreeNode | None:- """Find the closest file input to the selected element."""-- def find_file_input_in_descendants(n: EnhancedDOMTreeNode, depth: int) -> EnhancedDOMTreeNode | None:- if depth < 0:- return None- if browser_session.is_file_input(n):- return n- for child in n.children_nodes or []:- result = find_file_input_in_descendants(child, depth - 1)- if result:- return result- return None-- current = node- for _ in range(max_height + 1):- # Check the current node itself- if browser_session.is_file_input(current):- return current- # Check all descendants of the current node- result = find_file_input_in_descendants(current, max_descendant_depth)- if result:- return result- # Check all siblings and their descendants- if current.parent_node:- for sibling in current.parent_node.children_nodes or []:- if sibling is current:- continue- if browser_session.is_file_input(sibling):- return sibling- result = find_file_input_in_descendants(sibling, max_descendant_depth)- if result:- return result- current = current.parent_node- if not current:- break- return None-# Try to find a file input element near the selected element- file_input_node = find_file_input_near_element(node)+ file_input_node = browser_session.find_file_input_near_element(node)# Highlight the file input element if found (truly non-blocking)if file_input_node:@@ -2592,49 +2551,8 @@ class CodeAgentTools(Tools[Context]):node = selector_map[params.index]- # Helper function to find file input near the selected element- def find_file_input_near_element(- node: EnhancedDOMTreeNode, max_height: int = 3, max_descendant_depth: int = 3- ) -> EnhancedDOMTreeNode | None:- """Find the closest file input to the selected element."""-- def find_file_input_in_descendants(n: EnhancedDOMTreeNode, depth: int) -> EnhancedDOMTreeNode | None:- if depth < 0:- return None- if browser_session.is_file_input(n):- return n- for child in n.children_nodes or []:- result = find_file_input_in_descendants(child, depth - 1)- if result:- return result- return None-- current = node- for _ in range(max_height + 1):- # Check the current node itself- if browser_session.is_file_input(current):- return current- # Check all descendants of the current node- result = find_file_input_in_descendants(current, max_descendant_depth)- if result:- return result- # Check all siblings and their descendants- if current.parent_node:- for sibling in current.parent_node.children_nodes or []:- if sibling is current:- continue- if browser_session.is_file_input(sibling):- return sibling- result = find_file_input_in_descendants(sibling, max_descendant_depth)- if result:- return result- current = current.parent_node- if not current:- break- return None-# Try to find a file input element near the selected element- file_input_node = find_file_input_near_element(node)+ file_input_node = browser_session.find_file_input_near_element(node)# Highlight the file input element if found (truly non-blocking)if file_input_node:diff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.mdindex c1f49299f..02d9a225e 100644--- a/skills/browser-use/SKILL.md+++ b/skills/browser-use/SKILL.md@@ -62,6 +62,7 @@ browser-use type "text" # Type into focused elementbrowser-use input <index> "text" # Click element, then typebrowser-use keys "Enter" # Send keyboard keysbrowser-use select <index> "option" # Select dropdown option+browser-use upload <index> <path> # Upload file to file input# Data Extractionbrowser-use eval "document.title" # Execute JavaScript@@ -106,6 +107,7 @@ browser-use input <index> "text" # Click element, then type textbrowser-use keys "Enter" # Send keyboard keysbrowser-use keys "Control+a" # Send key combinationbrowser-use select <index> "option" # Select dropdown option+browser-use upload <index> <path> # Upload file to file input elementbrowser-use hover <index> # Hover over element (triggers CSS :hover)browser-use dblclick <index> # Double-click elementbrowser-use rightclick <index> # Right-click element (context menu)@@ -162,7 +164,7 @@ browser-use python --file script.py # Execute Python fileThe Python session maintains state across commands. The `browser` object provides:- `browser.url`, `browser.title`, `browser.html` — page info- `browser.goto(url)`, `browser.back()` — navigation-- `browser.click(index)`, `browser.type(text)`, `browser.input(index, text)`, `browser.keys(keys)` — interactions+- `browser.click(index)`, `browser.type(text)`, `browser.input(index, text)`, `browser.keys(keys)`, `browser.upload(index, path)` — interactions- `browser.screenshot(path)`, `browser.scroll(direction, amount)` — visual- `browser.wait(seconds)`, `browser.extract(query)` — utilitiesdiff --git a/skills/remote-browser/SKILL.md b/skills/remote-browser/SKILL.mdindex dcbdaa2c1..7cbf86751 100644--- a/skills/remote-browser/SKILL.md+++ b/skills/remote-browser/SKILL.md@@ -70,6 +70,7 @@ browser-use type "text" # Type into focused elementbrowser-use input <index> "text" # Click element, then typebrowser-use keys "Enter" # Send keyboard keysbrowser-use select <index> "option" # Select dropdown option+browser-use upload <index> <path> # Upload file to file input# Data Extractionbrowser-use eval "document.title" # Execute JavaScript@@ -114,6 +115,7 @@ browser-use input <index> "text" # Click element, then typebrowser-use keys "Enter" # Send keyboard keysbrowser-use keys "Control+a" # Key combinationbrowser-use select <index> "option" # Select dropdown option+browser-use upload <index> <path> # Upload file to file inputbrowser-use hover <index> # Hover over elementbrowser-use dblclick <index> # Double-clickbrowser-use rightclick <index> # Right-click@@ -168,7 +170,7 @@ browser-use python --file script.py # Run Python fileThe Python session maintains state across commands. The `browser` object provides:- `browser.url`, `browser.title`, `browser.html` — page info- `browser.goto(url)`, `browser.back()` — navigation-- `browser.click(index)`, `browser.type(text)`, `browser.input(index, text)`, `browser.keys(keys)` — interactions+- `browser.click(index)`, `browser.type(text)`, `browser.input(index, text)`, `browser.keys(keys)`, `browser.upload(index, path)` — interactions- `browser.screenshot(path)`, `browser.scroll(direction, amount)` — visual- `browser.wait(seconds)`, `browser.extract(query)` — utilitiesdiff --git a/tests/ci/test_cli_upload.py b/tests/ci/test_cli_upload.pynew file mode 100644index 000000000..11e8422e9--- /dev/null+++ b/tests/ci/test_cli_upload.py@@ -0,0 +1,315 @@+"""Tests for CLI file upload command.++Verifies argparse registration, file validation, file input discovery+(reusing BrowserSession.find_file_input_near_element), and event dispatch.+"""++from __future__ import annotations++import tempfile+from pathlib import Path++import pytest++from browser_use.skill_cli.main import build_parser+++class TestUploadArgParsing:+ """Test argparse handles the upload subcommand."""++ def test_upload_basic(self):+ """browser-use upload 5 /tmp/file.txt -> correct args."""+ parser = build_parser()+ args = parser.parse_args(['upload', '5', '/tmp/file.txt'])+ assert args.command == 'upload'+ assert args.index == 5+ assert args.path == '/tmp/file.txt'++ def test_upload_path_with_spaces(self):+ """Paths with spaces are handled."""+ parser = build_parser()+ args = parser.parse_args(['upload', '3', '/tmp/my file.pdf'])+ assert args.path == '/tmp/my file.pdf'++ def test_upload_missing_path_fails(self):+ """browser-use upload 5 (no path) should fail."""+ parser = build_parser()+ with pytest.raises(SystemExit):+ parser.parse_args(['upload', '5'])++ def test_upload_missing_index_fails(self):+ """browser-use upload (no args) should fail."""+ parser = build_parser()+ with pytest.raises(SystemExit):+ parser.parse_args(['upload'])++ def test_upload_non_int_index_fails(self):+ """browser-use upload abc /tmp/file.txt should fail."""+ parser = build_parser()+ with pytest.raises(SystemExit):+ parser.parse_args(['upload', 'abc', '/tmp/file.txt'])+++class TestUploadCommandHandler:+ """Test the browser command handler for upload."""++ async def test_upload_file_not_found(self):+ """Non-existent file returns error without touching the browser."""+ from browser_use.browser.session import BrowserSession+ from browser_use.skill_cli.commands.browser import handle+ from browser_use.skill_cli.sessions import SessionInfo++ session_info = SessionInfo(+ name='test',+ headed=False,+ profile=None,+ cdp_url=None,+ browser_session=BrowserSession(headless=True),+ )++ result = await handle('upload', session_info, {'index': 0, 'path': '/nonexistent/file.txt'})+ assert 'error' in result+ assert 'not found' in result['error'].lower()++ async def test_upload_empty_file(self):+ """Empty file returns error."""+ from browser_use.browser.session import BrowserSession+ from browser_use.skill_cli.commands.browser import handle+ from browser_use.skill_cli.sessions import SessionInfo++ session_info = SessionInfo(+ name='test',+ headed=False,+ profile=None,+ cdp_url=None,+ browser_session=BrowserSession(headless=True),+ )++ with tempfile.NamedTemporaryFile(suffix='.txt', delete=False) as f:+ empty_path = f.name++ try:+ result = await handle('upload', session_info, {'index': 0, 'path': empty_path})+ assert 'error' in result+ assert 'empty' in result['error'].lower()+ finally:+ Path(empty_path).unlink(missing_ok=True)++ async def test_upload_element_not_found(self, httpserver):+ """Invalid element index returns error."""+ from browser_use.browser.events import NavigateToUrlEvent+ from browser_use.browser.session import BrowserSession+ from browser_use.skill_cli.commands.browser import handle+ from browser_use.skill_cli.sessions import SessionInfo++ httpserver.expect_request('/').respond_with_data(+ '<html><body><input type="file" /></body></html>',+ content_type='text/html',+ )++ session = BrowserSession(headless=True)+ await session.start()+ try:+ await session.event_bus.dispatch(NavigateToUrlEvent(url=httpserver.url_for('/')))++ session_info = SessionInfo(+ name='test',+ headed=False,+ profile=None,+ cdp_url=None,+ browser_session=session,+ )++ with tempfile.NamedTemporaryFile(suffix='.txt', delete=False) as f:+ f.write(b'test content')+ test_file = f.name++ try:+ result = await handle('upload', session_info, {'index': 999, 'path': test_file})+ assert 'error' in result+ assert '999' in result['error']+ finally:+ Path(test_file).unlink(missing_ok=True)+ finally:+ await session.kill()++ async def test_upload_happy_path(self, httpserver):+ """Upload to a file input element succeeds."""+ from browser_use.browser.events import NavigateToUrlEvent+ from browser_use.browser.session import BrowserSession+ from browser_use.skill_cli.commands.browser import handle+ from browser_use.skill_cli.sessions import SessionInfo++ httpserver.expect_request('/').respond_with_data(+ '<html><body><input type="file" id="upload" /></body></html>',+ content_type='text/html',+ )++ session = BrowserSession(headless=True)+ await session.start()+ try:+ await session.event_bus.dispatch(NavigateToUrlEvent(url=httpserver.url_for('/')))++ session_info = SessionInfo(+ name='test',+ headed=False,+ profile=None,+ cdp_url=None,+ browser_session=session,+ )++ # Get state to populate selector map+ await session.get_browser_state_summary()++ # Find the file input index+ selector_map = await session.get_selector_map()+ file_input_index = None+ for idx, el in selector_map.items():+ if session.is_file_input(el):+ file_input_index = idx+ break+ assert file_input_index is not None, 'File input not found in selector map'++ with tempfile.NamedTemporaryFile(suffix='.txt', delete=False) as f:+ f.write(b'test content for upload')+ test_file = f.name++ try:+ result = await handle('upload', session_info, {'index': file_input_index, 'path': test_file})+ assert 'uploaded' in result+ assert result['element'] == file_input_index+ finally:+ Path(test_file).unlink(missing_ok=True)+ finally:+ await session.kill()++ async def test_upload_not_file_input_suggests_indices(self, httpserver):+ """Targeting a non-file-input element with no nearby file input returns error with suggestions."""+ from browser_use.browser.events import NavigateToUrlEvent+ from browser_use.browser.session import BrowserSession+ from browser_use.skill_cli.commands.browser import handle+ from browser_use.skill_cli.sessions import SessionInfo++ # Use deeply nested, separate DOM subtrees so the heuristic won't bridge them+ httpserver.expect_request('/').respond_with_data(+ """<html><body>+ <div><div><div><div><div><button id="btn">Click me</button></div></div></div></div></div>+ <div><div><div><div><div><input type="file" id="upload" /></div></div></div></div></div>+ </body></html>""",+ content_type='text/html',+ )++ session = BrowserSession(headless=True)+ await session.start()+ try:+ await session.event_bus.dispatch(NavigateToUrlEvent(url=httpserver.url_for('/')))++ session_info = SessionInfo(+ name='test',+ headed=False,+ profile=None,+ cdp_url=None,+ browser_session=session,+ )++ await session.get_browser_state_summary()++ # Find the button index (not a file input)+ selector_map = await session.get_selector_map()+ button_index = None+ for idx, el in selector_map.items():+ if el.node_name.upper() == 'BUTTON':+ button_index = idx+ break+ assert button_index is not None, 'Button not found in selector map'++ with tempfile.NamedTemporaryFile(suffix='.txt', delete=False) as f:+ f.write(b'test content')+ test_file = f.name++ try:+ result = await handle('upload', session_info, {'index': button_index, 'path': test_file})+ assert 'error' in result+ assert 'not a file input' in result['error'].lower()+ # Should suggest the file input index+ assert 'File input(s) found at index' in result['error']+ finally:+ Path(test_file).unlink(missing_ok=True)+ finally:+ await session.kill()++ async def test_upload_wrapped_file_input(self, httpserver):+ """File input wrapped in a label/div is found via find_file_input_near_element."""+ from browser_use.browser.events import NavigateToUrlEvent+ from browser_use.browser.session import BrowserSession+ from browser_use.skill_cli.commands.browser import handle+ from browser_use.skill_cli.sessions import SessionInfo++ httpserver.expect_request('/').respond_with_data(+ """<html><body>+ <label id="wrapper">+ Upload here+ <input type="file" id="hidden-upload" style="opacity: 0" />+ </label>+ </body></html>""",+ content_type='text/html',+ )++ session = BrowserSession(headless=True)+ await session.start()+ try:+ await session.event_bus.dispatch(NavigateToUrlEvent(url=httpserver.url_for('/')))++ session_info = SessionInfo(+ name='test',+ headed=False,+ profile=None,+ cdp_url=None,+ browser_session=session,+ )++ await session.get_browser_state_summary()++ # The file input should be found even if we target the label or a nearby element+ selector_map = await session.get_selector_map()++ # Find any non-file-input element that is near the file input+ file_input_index = None+ other_index = None+ for idx, el in selector_map.items():+ if session.is_file_input(el):+ file_input_index = idx+ else:+ other_index = idx++ # If both the file input and another element are in the selector map,+ # try uploading via the other element (the heuristic should find the file input)+ if other_index is not None:+ with tempfile.NamedTemporaryFile(suffix='.txt', delete=False) as f:+ f.write(b'test content for wrapped upload')+ test_file = f.name++ try:+ result = await handle('upload', session_info, {'index': other_index, 'path': test_file})+ # Should succeed if the heuristic found the nearby file input+ # or error if too far away - either way, the heuristic was exercised+ if 'uploaded' in result:+ assert result['element'] == other_index+ else:+ # If the elements are too far apart, the heuristic won't find it+ assert 'error' in result+ finally:+ Path(test_file).unlink(missing_ok=True)+ elif file_input_index is not None:+ # Only the file input is indexed, just test direct upload+ with tempfile.NamedTemporaryFile(suffix='.txt', delete=False) as f:+ f.write(b'test content')+ test_file = f.name++ try:+ result = await handle('upload', session_info, {'index': file_input_index, 'path': test_file})+ assert 'uploaded' in result+ finally:+ Path(test_file).unlink(missing_ok=True)+ finally:+ await session.kill()