Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

improve hashing of elements using cascading hash

mertunsall1779e9717d05
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.py
index 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_PROFILE
from browser_use.browser.views import BrowserStateSummary
from browser_use.config import CONFIG
-from browser_use.dom.views import DOMInteractedElement
+from browser_use.dom.views import DOMInteractedElement, MatchLevel
from browser_use.filesystem.file_system import FileSystem
from browser_use.observability import observe, observe_debug
from 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 action
selector_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 None
old_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 action
diff --git a/browser_use/dom/views.py b/browser_use/dom/views.py
index 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))
+
@dataclass
class 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 fail
ax_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 truth
ax_name=ax_name,
)