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 grep tool to agent
Saurav Pandad5f38a5eebc4
diff --git a/browser_use/agent/system_prompts/system_prompt.md b/browser_use/agent/system_prompts/system_prompt.mdindex 81f65499b..f19b6ed32 100644--- a/browser_use/agent/system_prompts/system_prompt.md+++ b/browser_use/agent/system_prompts/system_prompt.md@@ -70,6 +70,9 @@ Strictly follow these rules while using the browser and navigating the web:- You can call extract on specific pages to gather structured semantic information from the entire page, including parts not currently visible.- Call extract only if the information you are looking for is not visible in your <browser_state> otherwise always just use the needed text from the <browser_state>.- Calling the extract tool is expensive! DO NOT query the same page with the same extract query multiple times. Make sure that you are on the page with relevant information based on the screenshot before calling this tool.+- Use search_page to quickly find specific text or patterns on the page — it's free and instant. Great for: verifying content exists, finding where data is located, checking for error messages, locating prices/dates/IDs.+- Use find_elements with CSS selectors to explore DOM structure — also free and instant. Great for: counting items (e.g. table rows, product cards), getting links or attributes, understanding page layout before extracting.+- Prefer search_page and find_elements over scrolling when looking for specific content not visible in browser_state.- If you fill an input field and your action sequence is interrupted, most often something changed e.g. suggestions popped up under the field.- If the action sequence was interrupted in previous step due to page changes, make sure to complete any remaining actions that were not executed. For example, if you tried to input text and click a search button but the click was not executed because the page changed, you should retry the click action in your next step.- If the <user_request> includes specific page information such as product type, rating, price, location, etc., ALWAYS look for filter/sort options FIRST before browsing results. Apply all relevant filters before scrolling through results.diff --git a/browser_use/tools/service.py b/browser_use/tools/service.pyindex 1f446d0be..3311fb1be 100644--- a/browser_use/tools/service.py+++ b/browser_use/tools/service.py@@ -40,6 +40,7 @@ from browser_use.tools.views import (CloseTabAction,DoneAction,ExtractAction,+ FindElementsAction,GetDropdownOptionsAction,InputTextAction,NavigateAction,@@ -47,6 +48,7 @@ from browser_use.tools.views import (ScreenshotAction,ScrollAction,SearchAction,+ SearchPageAction,SelectDropdownOptionAction,SendKeysAction,StructuredOutputAction,@@ -103,6 +105,224 @@ def handle_browser_error(e: BrowserError) -> ActionResult:raise e+# --- JS templates for search_page and find_elements ---++_SEARCH_PAGE_JS_BODY = """\+try {+ var scope = CSS_SCOPE ? document.querySelector(CSS_SCOPE) : document.body;+ if (!scope) {+ return {error: 'CSS scope selector not found: ' + CSS_SCOPE, matches: [], total: 0};+ }+ var walker = document.createTreeWalker(scope, NodeFilter.SHOW_TEXT);+ var fullText = '';+ var nodeOffsets = [];+ while (walker.nextNode()) {+ var node = walker.currentNode;+ var text = node.textContent;+ if (text && text.trim()) {+ nodeOffsets.push({offset: fullText.length, length: text.length, node: node});+ fullText += text;+ }+ }+ var re;+ try {+ var flags = CASE_SENSITIVE ? 'g' : 'gi';+ if (IS_REGEX) {+ re = new RegExp(PATTERN, flags);+ } else {+ re = new RegExp(PATTERN.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&'), flags);+ }+ } catch (e) {+ return {error: 'Invalid regex pattern: ' + e.message, matches: [], total: 0};+ }+ var matches = [];+ var match;+ var totalFound = 0;+ while ((match = re.exec(fullText)) !== null) {+ totalFound++;+ if (matches.length < MAX_RESULTS) {+ var start = Math.max(0, match.index - CONTEXT_CHARS);+ var end = Math.min(fullText.length, match.index + match[0].length + CONTEXT_CHARS);+ var context = fullText.slice(start, end);+ var elementPath = '';+ for (var i = 0; i < nodeOffsets.length; i++) {+ var no = nodeOffsets[i];+ if (no.offset <= match.index && no.offset + no.length > match.index) {+ elementPath = _getPath(no.node.parentElement);+ break;+ }+ }+ matches.push({+ match_text: match[0],+ context: (start > 0 ? '...' : '') + context + (end < fullText.length ? '...' : ''),+ element_path: elementPath,+ char_position: match.index+ });+ }+ if (match[0].length === 0) re.lastIndex++;+ }+ return {matches: matches, total: totalFound, has_more: totalFound > MAX_RESULTS};+} catch (e) {+ return {error: 'search_page error: ' + e.message, matches: [], total: 0};+}+function _getPath(el) {+ var parts = [];+ var current = el;+ while (current && current !== document.body && current !== document) {+ var desc = current.tagName ? current.tagName.toLowerCase() : '';+ if (!desc) break;+ if (current.id) desc += '#' + current.id;+ else if (current.className && typeof current.className === 'string') {+ var classes = current.className.trim().split(/\\s+/).slice(0, 2).join('.');+ if (classes) desc += '.' + classes;+ }+ parts.unshift(desc);+ current = current.parentElement;+ }+ return parts.join(' > ');+}+"""++_FIND_ELEMENTS_JS_BODY = """\+try {+ var elements;+ try {+ elements = document.querySelectorAll(SELECTOR);+ } catch (e) {+ return {error: 'Invalid CSS selector: ' + e.message, elements: [], total: 0};+ }+ var total = elements.length;+ var limit = Math.min(total, MAX_RESULTS);+ var results = [];+ for (var i = 0; i < limit; i++) {+ var el = elements[i];+ var item = {index: i, tag: el.tagName.toLowerCase()};+ if (INCLUDE_TEXT) {+ var text = (el.textContent || '').trim();+ item.text = text.length > 300 ? text.slice(0, 300) + '...' : text;+ }+ if (ATTRIBUTES && ATTRIBUTES.length > 0) {+ item.attrs = {};+ for (var j = 0; j < ATTRIBUTES.length; j++) {+ var val = el.getAttribute(ATTRIBUTES[j]);+ if (val !== null) {+ item.attrs[ATTRIBUTES[j]] = val.length > 500 ? val.slice(0, 500) + '...' : val;+ }+ }+ }+ item.children_count = el.children.length;+ results.push(item);+ }+ return {elements: results, total: total, showing: limit};+} catch (e) {+ return {error: 'find_elements error: ' + e.message, elements: [], total: 0};+}+"""+++def _build_search_page_js(+ pattern: str,+ regex: bool,+ case_sensitive: bool,+ context_chars: int,+ css_scope: str | None,+ max_results: int,+) -> str:+ """Build JS IIFE for search_page with safe parameter injection."""+ params_js = (+ f'var PATTERN = {json.dumps(pattern)};\n'+ f'var IS_REGEX = {json.dumps(regex)};\n'+ f'var CASE_SENSITIVE = {json.dumps(case_sensitive)};\n'+ f'var CONTEXT_CHARS = {json.dumps(context_chars)};\n'+ f'var CSS_SCOPE = {json.dumps(css_scope)};\n'+ f'var MAX_RESULTS = {json.dumps(max_results)};\n'+ )+ return '(function() {\n' + params_js + _SEARCH_PAGE_JS_BODY + '\n})()'+++def _build_find_elements_js(+ selector: str,+ attributes: list[str] | None,+ max_results: int,+ include_text: bool,+) -> str:+ """Build JS IIFE for find_elements with safe parameter injection."""+ params_js = (+ f'var SELECTOR = {json.dumps(selector)};\n'+ f'var ATTRIBUTES = {json.dumps(attributes)};\n'+ f'var MAX_RESULTS = {json.dumps(max_results)};\n'+ f'var INCLUDE_TEXT = {json.dumps(include_text)};\n'+ )+ return '(function() {\n' + params_js + _FIND_ELEMENTS_JS_BODY + '\n})()'+++def _format_search_results(data: dict, pattern: str) -> str:+ """Format search_page CDP result into human-readable text for the agent."""+ if not isinstance(data, dict):+ return f'search_page returned unexpected result: {data}'++ matches = data.get('matches', [])+ total = data.get('total', 0)+ has_more = data.get('has_more', False)++ if total == 0:+ return f'No matches found for "{pattern}" on page.'++ lines = [f'Found {total} match{"es" if total != 1 else ""} for "{pattern}" on page:']+ lines.append('')+ for i, m in enumerate(matches):+ context = m.get('context', '')+ path = m.get('element_path', '')+ loc = f' (in {path})' if path else ''+ lines.append(f'[{i + 1}] {context}{loc}')++ if has_more:+ lines.append(f'\n... showing {len(matches)} of {total} total matches. Increase max_results to see more.')++ return '\n'.join(lines)+++def _format_find_results(data: dict, selector: str) -> str:+ """Format find_elements CDP result into human-readable text for the agent."""+ if not isinstance(data, dict):+ return f'find_elements returned unexpected result: {data}'++ elements = data.get('elements', [])+ total = data.get('total', 0)+ showing = data.get('showing', 0)++ if total == 0:+ return f'No elements found matching "{selector}".'++ lines = [f'Found {total} element{"s" if total != 1 else ""} matching "{selector}":']+ lines.append('')+ for el in elements:+ idx = el.get('index', 0)+ tag = el.get('tag', '?')+ text = el.get('text', '')+ attrs = el.get('attrs', {})+ children = el.get('children_count', 0)++ # Build element description+ parts = [f'[{idx}] <{tag}>']+ if text:+ # Collapse whitespace for readability+ display_text = ' '.join(text.split())+ if len(display_text) > 120:+ display_text = display_text[:120] + '...'+ parts.append(f'"{display_text}"')+ if attrs:+ attr_strs = [f'{k}="{v}"' for k, v in attrs.items()]+ parts.append('{' + ', '.join(attr_strs) + '}')+ parts.append(f'({children} children)')+ lines.append(' '.join(parts))++ if showing < total:+ lines.append(f'\nShowing {showing} of {total} total elements. Increase max_results to see more.')++ return '\n'.join(lines)++def _is_autocomplete_field(node: EnhancedDOMTreeNode) -> bool:"""Detect if a node is an autocomplete/combobox field from its attributes."""attrs = node.attributes or {}@@ -815,6 +1035,80 @@ You will be given a query and the markdown of a webpage that has been filtered tlogger.debug(f'Error extracting content: {e}')raise RuntimeError(str(e))+ # --- Page search and exploration tools (zero LLM cost) ---++ @self.registry.action(+ """Search page text for a pattern (like grep). Zero LLM cost, instant. Returns matches with surrounding context. Use to find specific text, verify content exists, or locate data on the page. Set regex=True for regex patterns. Use css_scope to search within a specific section.""",+ param_model=SearchPageAction,+ )+ async def search_page(params: SearchPageAction, browser_session: BrowserSession):+ js_code = _build_search_page_js(+ pattern=params.pattern,+ regex=params.regex,+ case_sensitive=params.case_sensitive,+ context_chars=params.context_chars,+ css_scope=params.css_scope,+ max_results=params.max_results,+ )++ cdp_session = await browser_session.get_or_create_cdp_session()+ result = await cdp_session.cdp_client.send.Runtime.evaluate(+ params={'expression': js_code, 'returnByValue': True, 'awaitPromise': True},+ session_id=cdp_session.session_id,+ )++ if result.get('exceptionDetails'):+ error_text = result['exceptionDetails'].get('text', 'Unknown JS error')+ return ActionResult(error=f'search_page failed: {error_text}')++ data = result.get('result', {}).get('value')+ if data is None:+ return ActionResult(error='search_page returned no result')++ if isinstance(data, dict) and data.get('error'):+ return ActionResult(error=f'search_page: {data["error"]}')++ formatted = _format_search_results(data, params.pattern)+ total = data.get('total', 0)+ memory = f'Searched page for "{params.pattern}": {total} match{"es" if total != 1 else ""} found.'+ logger.info(f'🔎 {memory}')+ return ActionResult(extracted_content=formatted, long_term_memory=memory)++ @self.registry.action(+ """Query DOM elements by CSS selector (like find). Zero LLM cost, instant. Returns matching elements with tag, text, and attributes. Use to explore page structure, count items, get links/attributes. Use attributes=["href","src"] to extract specific attributes.""",+ param_model=FindElementsAction,+ )+ async def find_elements(params: FindElementsAction, browser_session: BrowserSession):+ js_code = _build_find_elements_js(+ selector=params.selector,+ attributes=params.attributes,+ max_results=params.max_results,+ include_text=params.include_text,+ )++ cdp_session = await browser_session.get_or_create_cdp_session()+ result = await cdp_session.cdp_client.send.Runtime.evaluate(+ params={'expression': js_code, 'returnByValue': True, 'awaitPromise': True},+ session_id=cdp_session.session_id,+ )++ if result.get('exceptionDetails'):+ error_text = result['exceptionDetails'].get('text', 'Unknown JS error')+ return ActionResult(error=f'find_elements failed: {error_text}')++ data = result.get('result', {}).get('value')+ if data is None:+ return ActionResult(error='find_elements returned no result')++ if isinstance(data, dict) and data.get('error'):+ return ActionResult(error=f'find_elements: {data["error"]}')++ formatted = _format_find_results(data, params.selector)+ total = data.get('total', 0)+ memory = f'Found {total} element{"s" if total != 1 else ""} matching "{params.selector}".'+ logger.info(f'🔍 {memory}')+ return ActionResult(extracted_content=formatted, long_term_memory=memory)+@self.registry.action("""Scroll by pages. REQUIRED: down=True/False (True=scroll down, False=scroll up, default=True). Optional: pages=0.5-10.0 (default 1.0). Use index for scroll elements (dropdowns/custom UI). High pages (10) reaches bottom. Multi-page scrolls sequentially. Viewport-based height, fallback 1000px/page.""",param_model=ScrollAction,diff --git a/browser_use/tools/views.py b/browser_use/tools/views.pyindex c241edb84..4eb7edb4f 100644--- a/browser_use/tools/views.py+++ b/browser_use/tools/views.py@@ -14,6 +14,25 @@ class ExtractAction(BaseModel):)+class SearchPageAction(BaseModel):+ pattern: str = Field(description='Text or regex pattern to search for in page content')+ regex: bool = Field(default=False, description='Treat pattern as regex (default: literal text match)')+ case_sensitive: bool = Field(default=False, description='Case-sensitive search (default: case-insensitive)')+ context_chars: int = Field(default=150, description='Characters of surrounding context per match')+ css_scope: str | None = Field(default=None, description='CSS selector to limit search scope (e.g. "div#main")')+ max_results: int = Field(default=25, description='Maximum matches to return')+++class FindElementsAction(BaseModel):+ selector: str = Field(description='CSS selector to query elements (e.g. "table tr", "a.link", "div.product")')+ attributes: list[str] | None = Field(+ default=None,+ description='Specific attributes to extract (e.g. ["href", "src", "class"]). If not set, returns tag and text only.',+ )+ max_results: int = Field(default=50, description='Maximum elements to return')+ include_text: bool = Field(default=True, description='Include text content of each element')++class SearchAction(BaseModel):query: strengine: str = Field(diff --git a/tests/ci/test_search_find.py b/tests/ci/test_search_find.pynew file mode 100644index 000000000..c4dfdf1fc--- /dev/null+++ b/tests/ci/test_search_find.py@@ -0,0 +1,431 @@+"""Tests for search_page and find_elements actions."""++import asyncio++import pytest+from pytest_httpserver import HTTPServer++from browser_use.agent.views import ActionResult+from browser_use.browser import BrowserProfile, BrowserSession+from browser_use.tools.service import Tools++# --- Fixtures ---++[email protected](scope='session')+def http_server():+ """Test HTTP server serving pages for search/find tests."""+ server = HTTPServer()+ server.start()++ server.expect_request('/products').respond_with_data(+ """+ <!DOCTYPE html>+ <html>+ <head><title>Products</title></head>+ <body>+ <h1>Product Catalog</h1>+ <div id="main">+ <table class="products">+ <thead>+ <tr><th>Name</th><th>Price</th><th>Rating</th></tr>+ </thead>+ <tbody>+ <tr class="product-row"><td>Widget A</td><td>$29.99</td><td>4.5 stars</td></tr>+ <tr class="product-row"><td>Widget B</td><td>$49.99</td><td>4.2 stars</td></tr>+ <tr class="product-row"><td>Gadget C</td><td>$19.50</td><td>3.8 stars</td></tr>+ <tr class="product-row"><td>Gadget D</td><td>$99.00</td><td>4.9 stars</td></tr>+ </tbody>+ </table>+ <div class="pagination">+ <a href="/products?page=1" class="page-link active">1</a>+ <a href="/products?page=2" class="page-link">2</a>+ <a href="/products?page=3" class="page-link">3</a>+ </div>+ </div>+ <footer id="footer">+ <p>Best price guarantee on all items.</p>+ <p>Contact us at [email protected]</p>+ </footer>+ </body>+ </html>+ """,+ content_type='text/html',+ )++ server.expect_request('/articles').respond_with_data(+ """+ <!DOCTYPE html>+ <html>+ <head><title>Articles</title></head>+ <body>+ <article id="post-1">+ <h2>Introduction to Python</h2>+ <p>Python is a versatile programming language used in web development, data science, and automation.</p>+ <a href="/articles/python" class="read-more">Read more</a>+ </article>+ <article id="post-2">+ <h2>JavaScript for Beginners</h2>+ <p>JavaScript powers the interactive web. Learn about DOM manipulation and event handling.</p>+ <a href="/articles/javascript" class="read-more">Read more</a>+ </article>+ <article id="post-3">+ <h2>Advanced CSS Techniques</h2>+ <p>Master CSS Grid, Flexbox, and custom properties for modern web layouts.</p>+ <a href="/articles/css" class="read-more">Read more</a>+ </article>+ </body>+ </html>+ """,+ content_type='text/html',+ )++ server.expect_request('/empty').respond_with_data(+ """+ <!DOCTYPE html>+ <html>+ <head><title>Empty</title></head>+ <body>+ <div id="content"></div>+ </body>+ </html>+ """,+ content_type='text/html',+ )++ server.expect_request('/case-test').respond_with_data(+ """+ <!DOCTYPE html>+ <html>+ <head><title>Case Test</title></head>+ <body>+ <p>The Quick Brown Fox jumps over the lazy dog.</p>+ <p>QUICK BROWN FOX is an uppercase variant.</p>+ <p>quick brown fox is a lowercase variant.</p>+ </body>+ </html>+ """,+ content_type='text/html',+ )++ yield server+ server.stop()++[email protected](scope='session')+def base_url(http_server):+ return f'http://{http_server.host}:{http_server.port}'++[email protected](scope='module')+async def browser_session():+ session = BrowserSession(+ browser_profile=BrowserProfile(+ headless=True,+ user_data_dir=None,+ keep_alive=True,+ )+ )+ await session.start()+ yield session+ await session.kill()++[email protected](scope='function')+def tools():+ return Tools()+++# --- Helper ---+++async def _navigate_and_wait(tools, browser_session, url):+ """Navigate to URL and wait for page load."""+ await tools.navigate(url=url, new_tab=False, browser_session=browser_session)+ await asyncio.sleep(0.5)+++# --- search_page tests ---+++class TestSearchPage:+ """Tests for the search_page action."""++ async def test_literal_text_search(self, tools, browser_session, base_url):+ """Literal text search finds matches with context."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ result = await tools.search_page(pattern='Widget A', browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ assert 'Widget A' in result.extracted_content+ assert '1 match' in result.extracted_content++ async def test_regex_search_prices(self, tools, browser_session, base_url):+ """Regex search finds all price patterns on the page."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ result = await tools.search_page(pattern=r'\$\d+\.\d{2}', regex=True, browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ # Should find $29.99, $49.99, $19.50, $99.00+ assert '4 matches' in result.extracted_content+ assert '$29.99' in result.extracted_content+ assert '$49.99' in result.extracted_content++ async def test_css_scope_limits_search(self, tools, browser_session, base_url):+ """css_scope limits search to elements within the selector."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ # Search only in footer+ result = await tools.search_page(pattern='price', css_scope='#footer', browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ # "Best price guarantee" is in footer+ assert '1 match' in result.extracted_content+ assert 'guarantee' in result.extracted_content++ async def test_case_insensitive_default(self, tools, browser_session, base_url):+ """Search is case-insensitive by default."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/case-test')++ result = await tools.search_page(pattern='quick brown fox', browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ # Should match all three variants (Quick, QUICK, quick)+ assert '3 matches' in result.extracted_content++ async def test_case_sensitive(self, tools, browser_session, base_url):+ """case_sensitive=True restricts to exact case."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/case-test')++ result = await tools.search_page(pattern='QUICK BROWN FOX', case_sensitive=True, browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ assert '1 match' in result.extracted_content++ async def test_max_results(self, tools, browser_session, base_url):+ """max_results limits the number of returned matches."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ result = await tools.search_page(pattern=r'\$\d+\.\d{2}', regex=True, max_results=2, browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ # Total should still show 4, but only 2 are displayed+ assert '4 matches' in result.extracted_content+ assert 'Increase max_results' in result.extracted_content++ async def test_no_matches(self, tools, browser_session, base_url):+ """No matches returns a clean message, not an error."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ result = await tools.search_page(pattern='xyznonexistent', browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ assert 'No matches found' in result.extracted_content++ async def test_element_path_in_results(self, tools, browser_session, base_url):+ """Matches include the element path for context."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ result = await tools.search_page(pattern='guarantee', browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ # Should show element path containing footer+ assert '(in' in result.extracted_content++ async def test_invalid_css_scope(self, tools, browser_session, base_url):+ """Invalid css_scope returns a clear error."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ result = await tools.search_page(pattern='test', css_scope='#nonexistent-scope', browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is not None+ assert 'scope' in result.error.lower() or 'not found' in result.error.lower()++ async def test_memory_set(self, tools, browser_session, base_url):+ """long_term_memory is set with match count summary."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ result = await tools.search_page(pattern='Widget', browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.long_term_memory is not None+ assert 'Widget' in result.long_term_memory+ assert 'match' in result.long_term_memory+++# --- find_elements tests ---+++class TestFindElements:+ """Tests for the find_elements action."""++ async def test_basic_selector(self, tools, browser_session, base_url):+ """Basic CSS selector returns correct elements."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ result = await tools.find_elements(selector='tr.product-row', browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ assert '4 elements' in result.extracted_content+ assert 'Widget A' in result.extracted_content+ assert 'Gadget D' in result.extracted_content++ async def test_attribute_extraction(self, tools, browser_session, base_url):+ """attributes parameter extracts specific attributes from elements."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ result = await tools.find_elements(+ selector='a.page-link',+ attributes=['href', 'class'],+ browser_session=browser_session,+ )++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ assert '3 elements' in result.extracted_content+ assert 'href=' in result.extracted_content+ assert '/products?page=' in result.extracted_content++ async def test_max_results_limiting(self, tools, browser_session, base_url):+ """max_results limits displayed elements while showing total count."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ result = await tools.find_elements(selector='tr.product-row', max_results=2, browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ assert '4 elements' in result.extracted_content+ assert 'Showing 2 of 4' in result.extracted_content++ async def test_no_matching_elements(self, tools, browser_session, base_url):+ """No matches returns a clean message, not an error."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ result = await tools.find_elements(selector='div.nonexistent', browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ assert 'No elements found' in result.extracted_content++ async def test_invalid_selector(self, tools, browser_session, base_url):+ """Invalid CSS selector returns a clear error, not a crash."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ result = await tools.find_elements(selector='[[[invalid', browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is not None+ assert 'selector' in result.error.lower() or 'invalid' in result.error.lower()++ async def test_include_text_false(self, tools, browser_session, base_url):+ """include_text=False omits text content from results."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/articles')++ result = await tools.find_elements(selector='article', include_text=False, browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ assert '3 elements' in result.extracted_content+ # Text content should not appear (no article body text)+ # But the tag and children count should still be present+ assert '<article>' in result.extracted_content++ async def test_nested_selectors(self, tools, browser_session, base_url):+ """Nested CSS selectors (child combinator) work correctly."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/articles')++ result = await tools.find_elements(+ selector='article a.read-more',+ attributes=['href'],+ browser_session=browser_session,+ )++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ assert '3 elements' in result.extracted_content+ assert '/articles/python' in result.extracted_content+ assert '/articles/javascript' in result.extracted_content+ assert '/articles/css' in result.extracted_content++ async def test_children_count(self, tools, browser_session, base_url):+ """Elements show children count."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ result = await tools.find_elements(selector='table.products thead tr', browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ assert '1 element' in result.extracted_content+ # The header row has 3 <th> children+ assert '3 children' in result.extracted_content++ async def test_memory_set(self, tools, browser_session, base_url):+ """long_term_memory is set with element count summary."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/products')++ result = await tools.find_elements(selector='tr.product-row', browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.long_term_memory is not None+ assert '4 element' in result.long_term_memory++ async def test_empty_page(self, tools, browser_session, base_url):+ """Works on a nearly empty page without errors."""+ await _navigate_and_wait(tools, browser_session, f'{base_url}/empty')++ result = await tools.find_elements(selector='p', browser_session=browser_session)++ assert isinstance(result, ActionResult)+ assert result.error is None+ assert result.extracted_content is not None+ assert 'No elements found' in result.extracted_content+++# --- Registration tests ---+++class TestRegistration:+ """Test that new actions are properly registered."""++ async def test_search_page_registered(self, tools):+ """search_page is in the default action registry."""+ assert 'search_page' in tools.registry.registry.actions++ async def test_find_elements_registered(self, tools):+ """find_elements is in the default action registry."""+ assert 'find_elements' in tools.registry.registry.actions++ async def test_excluded_actions(self):+ """New actions can be excluded via exclude_actions."""+ excluded_tools = Tools(exclude_actions=['search_page', 'find_elements'])+ assert 'search_page' not in excluded_tools.registry.registry.actions+ assert 'find_elements' not in excluded_tools.registry.registry.actions+ # Other actions still present+ assert 'navigate' in excluded_tools.registry.registry.actions