[fix]: locator.fill() not setting values

[seanmcguire12]

why

• locator().fill() was silently failing on <input> elements that require direct value setting.
• this is because:
  • inside the fill() function (in locator.ts) the javascript code passed to Runtime.callFunctionOn only contained the fillElementValue() function body. (see dom/locatorScripts/scripts.ts for the function definition of fillElementValue())
  • critically, fillElementValue() relies on other helpers defined outside of the function body, and therefore outside of the code that was passed to Runtime.callFunctionOn
  • this caused an uncaught exception inside the browser-side javascript which went unnoticed because we were not unpacking exceptionDetails from the response of Runtime.callFunctionOn

what changed

• updated the call to Runtime.callFunctionOn to include the bundled locator globals which were previously missing
  • this fixes the actual issue, ie, makes sure that .fill() actually works on elements that require direct value setting instead of typing
• added logic to correctly unpack the response from Runtime.callFunctionOn, so that we check if there was an exception
  • if there was an exception, we parse the error details and throw a StagehandLocatorError
  • this makes sure we correctly surface future exceptions instead of silently failing

test plan

• added tests in locator-fill.spec.ts to:
  • test that .fill() correctly sets values
  • test that exceptions are correctly surfaced as a StagehandLocatorError

---

Summary by cubic

Fixes locator.fill so it correctly sets values on inputs that require direct value assignment, and surfaces runtime errors instead of failing silently.

• Bug Fixes
  • Include bundled locator globals when invoking fillElementValue via Runtime.callFunctionOn.
  • Check exceptionDetails and throw StagehandLocatorError with action, selector, and message.
  • Add tests for date inputs and error propagation for both XPath and CSS selectors.

^{Written for commit 218a4ec. Summary will update on new commits. Review in cubic}

[changeset-bot]

🦋 Changeset detected

Latest commit: 218a4ec

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

No issues found across 4 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant User
    participant Locator as SDK: Locator
    participant CDP as Browser: CDP Session
    participant JS as Browser: JS Execution Context

    Note over User,JS: locator.fill(value) Flow

    User->>Locator: fill("2026-01-01")
    Locator->>Locator: resolveNode() to get objectId
    
    Note over Locator: CHANGED: Bundle script with<br/>bootstrap & global refs
    
    Locator->>CDP: Runtime.callFunctionOn(objectId, bundledScript)
    
    CDP->>JS: Execute bundled JS on element
    
    alt JS Success
        JS->>JS: fillElementValue() executes using globals
        JS-->>CDP: { result: { value: ... } }
        CDP-->>Locator: Response (no exception)
        Locator-->>User: void
    else NEW: JS Exception (e.g., element disconnected)
        JS-->>CDP: { exceptionDetails: { text, exception: { description } } }
        CDP-->>Locator: Response with exceptionDetails
        
        Note over Locator: NEW: Unpack exception details
        
        Locator->>Locator: Throw StagehandLocatorError(message, selector)
        Locator-->>User: Error: "Error Filling Element..."
    end

    Note over User,JS: Logic ensures browser-side helpers are available<br/>and runtime errors are surfaced to the SDK user.

Loading

[greptile-apps]

Greptile Overview

Greptile Summary

This PR fixes a critical bug where locator.fill() was silently failing on <input> elements requiring direct value setting (date, time, range, etc.). The root cause was that fillElementValue() function body passed to Runtime.callFunctionOn couldn't access helper functions like prepareElementForTyping() and module-level constants that were defined outside its scope.

Key Changes:

• Wrapped fillElementValue call with locatorScriptBootstrap and locatorScriptGlobalRefs to bundle all required dependencies
• Added proper exception handling by checking exceptionDetails from Runtime.callFunctionOn response
• Created new StagehandLocatorError to surface runtime exceptions with detailed context
• Added comprehensive tests covering both the fix (date input with blocked beforeinput) and exception handling (for both xpath and CSS selectors)

The fix follows existing patterns in the codebase for bundling scripts and handling exceptions, making it a clean and well-integrated solution.

Confidence Score: 5/5

• This PR is safe to merge - it fixes a critical bug with proper error handling and comprehensive test coverage
• The fix addresses a real bug where fillElementValue() couldn't access helper functions, the solution correctly bundles dependencies via locatorScriptBootstrap, exception handling is properly added, and comprehensive tests verify both the fix and error surfacing
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/lib/v3/understudy/locator.ts	Fixed locator.fill() by bundling helper functions via locatorScriptBootstrap and added exception handling
packages/core/lib/v3/types/public/sdkErrors.ts	Added new StagehandLocatorError class for locator-specific errors
packages/core/lib/v3/tests/locator-fill.spec.ts	Added comprehensive tests for value setter behavior and exception handling

Sequence Diagram

sequenceDiagram
    participant Client as Locator.fill()
    participant CDP as Chrome DevTools Protocol
    participant Browser as Browser Runtime
    participant Element as DOM Element

    Client->>Client: Create fillDeclaration with bootstrap
    Note over Client: Bundles locatorScriptBootstrap +<br/>fillElementValue via globalRefs
    
    Client->>CDP: Runtime.callFunctionOn(fillDeclaration)
    CDP->>Browser: Execute function on element objectId
    
    Browser->>Browser: Load locatorScriptBootstrap
    Note over Browser: Initializes __stagehandLocatorScripts<br/>with all helper functions
    
    Browser->>Element: Call fillElementValue(value)
    
    alt Date/Time/Range input type
        Element->>Element: prepareElementForTyping()
        Element->>Element: Use native value setter
        Element->>Element: dispatchInputAndChange()
        Element-->>Browser: Return {status: "done"}
    else Text/Email/etc input type
        Element->>Element: prepareElementForTyping()
        Element-->>Browser: Return {status: "needsinput"}
    else Exception occurs
        Element-->>Browser: Throw exception
    end
    
    Browser-->>CDP: Return result with exceptionDetails (if any)
    CDP-->>Client: CallFunctionOnResponse
    
    alt exceptionDetails present
        Client->>Client: Extract exception message
        Client-->>Client: Throw StagehandLocatorError
    else status === "done"
        Client-->>Client: Return (complete)
    else status === "needsinput"
        Client->>CDP: Type text via Input.dispatchKeyEvent
        CDP->>Element: Simulate keyboard input
        Element-->>CDP: Events dispatched
        CDP-->>Client: Success
    end

Loading

[greptile-apps]

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}