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
improve hashing of elements using cascading hash
mertunsall1779e9717d05
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.pyindex 367f26ac4..f7cd4f74a 100644--- a/browser_use/agent/service.py+++ b/browser_use/agent/service.py@@ -62,7 +62,7 @@ from browser_use.agent.views import (from browser_use.browser.session import DEFAULT_BROWSER_PROFILEfrom browser_use.browser.views import BrowserStateSummaryfrom browser_use.config import CONFIG-from browser_use.dom.views import DOMInteractedElement+from browser_use.dom.views import DOMInteractedElement, MatchLevelfrom browser_use.filesystem.file_system import FileSystemfrom browser_use.observability import observe, observe_debugfrom browser_use.telemetry.service import ProductTelemetry@@ -2914,36 +2914,52 @@ class Agent(Generic[Context, AgentStructuredOutput]):Update action indices based on current page state.Returns updated action or None if element cannot be found.- Matching strategy:- 1. Try element_hash match (includes ax_name for uniqueness)- 2. Fall back to XPath matching (for backwards compatibility with old history files)+ Cascading matching strategy (tries each level in order):+ 1. EXACT: Full element_hash match (includes all attributes + ax_name)+ 2. STABLE: Hash with dynamic CSS classes filtered out (focus, hover, animation, etc.)+ 3. XPATH: XPath string match (structural position in DOM)"""if not historical_element or not browser_state_summary.dom_state.selector_map:return actionselector_map = browser_state_summary.dom_state.selector_map+ highlight_index: int | None = None+ match_level: MatchLevel | None = None++ # Level 1: EXACT hash match+ for idx, elem in selector_map.items():+ if elem.element_hash == historical_element.element_hash:+ highlight_index = idx+ match_level = MatchLevel.EXACT+ break++ # Level 2: STABLE hash match (dynamic classes filtered)+ # Use stored stable_hash (computed at save time from EnhancedDOMTreeNode - single source of truth)+ if highlight_index is None and historical_element.stable_hash is not None:+ for idx, elem in selector_map.items():+ if elem.compute_stable_hash() == historical_element.stable_hash:+ highlight_index = idx+ match_level = MatchLevel.STABLE+ self.logger.info('Element matched at STABLE level (dynamic classes filtered)')+ break- # Strategy 1: Hash match (hash now includes ax_name for uniqueness)- highlight_index, current_element = next(- ((idx, elem) for idx, elem in selector_map.items() if elem.element_hash == historical_element.element_hash),- (None, None),- )-- # Strategy 2: XPath fallback (for backwards compatibility with old history files)- if current_element is None and historical_element.x_path:+ # Level 3: XPATH match+ if highlight_index is None and historical_element.x_path:for idx, elem in selector_map.items():if elem.xpath == historical_element.x_path:- highlight_index, current_element = idx, elem- self.logger.debug(f'Found element via XPath fallback: {historical_element.x_path}')+ highlight_index = idx+ match_level = MatchLevel.XPATH+ self.logger.info(f'Element matched at XPATH level: {historical_element.x_path}')break- if not current_element or highlight_index is None:+ if highlight_index is None:return Noneold_index = action.get_index()if old_index != highlight_index:action.set_index(highlight_index)- self.logger.info(f'Element moved in DOM, updated index from {old_index} to {highlight_index}')+ level_name = match_level.name if match_level else 'UNKNOWN'+ self.logger.info(f'Element index updated {old_index} → {highlight_index} (matched at {level_name} level)')return actiondiff --git a/browser_use/dom/views.py b/browser_use/dom/views.pyindex 132e48b28..911cdd0e4 100644--- a/browser_use/dom/views.py+++ b/browser_use/dom/views.py@@ -131,6 +131,52 @@ STATIC_ATTRIBUTES = {'aria-placeholder',}+# Class patterns that indicate dynamic/transient UI state - excluded from stable hash+DYNAMIC_CLASS_PATTERNS = frozenset(+ {+ 'focus',+ 'hover',+ 'active',+ 'selected',+ 'disabled',+ 'animation',+ 'transition',+ 'loading',+ 'open',+ 'closed',+ 'expanded',+ 'collapsed',+ 'visible',+ 'hidden',+ 'pressed',+ 'checked',+ 'highlighted',+ 'current',+ 'entering',+ 'leaving',+ }+)+++class MatchLevel(Enum):+ """Element matching strictness levels for history replay."""++ EXACT = 1 # Full hash with all attributes (current behavior)+ STABLE = 2 # Hash with dynamic classes filtered out+ XPATH = 3 # XPath string comparison+++def filter_dynamic_classes(class_str: str | None) -> str:+ """+ Remove dynamic state classes, keep semantic/identifying ones.+ Returns sorted classes for deterministic hashing.+ """+ if not class_str:+ return ''+ classes = class_str.split()+ stable = [c for c in classes if not any(pattern in c.lower() for pattern in DYNAMIC_CLASS_PATTERNS)]+ return ' '.join(sorted(stable))+@dataclassclass CurrentPageTargets:@@ -753,6 +799,36 @@ class EnhancedDOMTreeNode:def element_hash(self) -> int:return hash(self)+ def compute_stable_hash(self) -> int:+ """+ Compute hash with dynamic classes filtered out.+ More stable across sessions than element_hash since it excludes+ transient CSS state classes like focus, hover, animation, etc.+ """+ parent_branch_path = self._get_parent_branch_path()+ parent_branch_path_string = '/'.join(parent_branch_path)++ # Filter dynamic classes before building attributes string+ filtered_attrs: dict[str, str] = {}+ for k, v in self.attributes.items():+ if k not in STATIC_ATTRIBUTES:+ continue+ if k == 'class':+ v = filter_dynamic_classes(v)+ if not v: # Skip empty class after filtering+ continue+ filtered_attrs[k] = v++ attributes_string = ''.join(f'{k}={v}' for k, v in sorted(filtered_attrs.items()))++ ax_name = ''+ if self.ax_node and self.ax_node.name:+ ax_name = f'|ax_name={self.ax_node.name}'++ combined_string = f'{parent_branch_path_string}|{attributes_string}{ax_name}'+ hash_hex = hashlib.sha256(combined_string.encode()).hexdigest()+ return int(hash_hex[:16], 16)+def __str__(self) -> str:return f'[<{self.tag_name}>#{self.frame_id[-4:] if self.frame_id else "?"}:{self.backend_node_id}]'@@ -881,6 +957,9 @@ class DOMInteractedElement:element_hash: int+ # Stable hash with dynamic classes filtered - computed at save time for consistent matching+ stable_hash: int | None = None+# Accessibility name (visible text) - used for fallback matching when hash/xpath failax_name: str | None = None@@ -895,6 +974,7 @@ class DOMInteractedElement:'attributes': self.attributes,'x_path': self.x_path,'element_hash': self.element_hash,+ 'stable_hash': self.stable_hash,'bounds': self.bounds.to_dict() if self.bounds else None,'ax_name': self.ax_name,}@@ -917,5 +997,6 @@ class DOMInteractedElement:bounds=enhanced_dom_tree.snapshot_node.bounds if enhanced_dom_tree.snapshot_node else None,x_path=enhanced_dom_tree.xpath,element_hash=hash(enhanced_dom_tree),+ stable_hash=enhanced_dom_tree.compute_stable_hash(), # Compute from source for single source of truthax_name=ax_name,)