Implementation:SeleniumHQ Selenium UnpinnedScriptKey

Knowledge Sources	SeleniumHQ_Selenium Selenium Documentation
Domains	WebDriver, Browser_Automation
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for managing the lifecycle of pinned JavaScript scripts within a WebDriver session, provided by the Selenium WebDriver library.

Description

UnpinnedScriptKey is a Java class in the org.openqa.selenium package that extends ScriptKey to provide full lifecycle management for "pinned" JavaScript scripts. Pinned scripts are JavaScript functions that are registered with a WebDriver session so they can be called repeatedly without re-transmitting the script source each time.

The class manages:

• Script storage -- a static WeakHashMap keyed by JavascriptExecutor instances tracks all pinned scripts per executor. The weak reference ensures that scripts are automatically cleaned up when the executor is garbage collected.
• Script handle -- a UUID-based handle (with hyphens removed) that serves as the unique function name in the browser's JavaScript namespace.
• Script wrapping -- methods to generate the creation, execution, and removal JavaScript code for the pinned function.
• Script ID -- an optional mutable identifier (nullable) that can be set after pinning, typically for BiDi script identifiers.

Key static methods (package-private):

• pin(JavascriptExecutor, String) -- creates and registers a new pinned script.
• unpin(JavascriptExecutor, UnpinnedScriptKey) -- removes a pinned script from the registry.
• getPinnedScripts(JavascriptExecutor) -- returns an unmodifiable set of all pinned scripts for a given executor.

Usage

Use UnpinnedScriptKey through the JavascriptExecutor pinning API to pre-register JavaScript code that will be executed multiple times:

• Pin a script when you have a JavaScript function that needs to be called repeatedly across navigations or commands.
• The creation script installs the function in the browser's global scope.
• The execution script invokes the installed function.
• The removal script cleans up the function from the global scope.

Code Reference

Source Location

• Repository: SeleniumHQ_Selenium
• File: java/src/org/openqa/selenium/UnpinnedScriptKey.java

Signature

public class UnpinnedScriptKey extends ScriptKey {

    // Package-private static methods
    static UnpinnedScriptKey pin(JavascriptExecutor executor, String script)
    static void unpin(JavascriptExecutor executor, UnpinnedScriptKey key)
    static Set<UnpinnedScriptKey> getPinnedScripts(JavascriptExecutor executor)

    // Public constructor
    public UnpinnedScriptKey(String script)

    // Public instance methods
    public void setScriptId(String id)
    public String getScriptId()
    public String getScript()
    public String getScriptHandle()
    public String creationScript()
    public String executionScript()
    public String removalScript()
    public boolean equals(Object o)
    public int hashCode()
}

Import

import org.openqa.selenium.UnpinnedScriptKey;

I/O Contract

Constructor

Parameter	Type	Constraints	Description
script	String	Non-null (enforced by parent)	The JavaScript source code to be pinned

Public Instance Methods

Method	Input	Output	Description
getScript()	none	String	Returns the original JavaScript source code
getScriptHandle()	none	String	Returns the UUID-based handle (32 hex characters, no hyphens)
getScriptId()	none	String (nullable)	Returns the optional script ID (e.g., BiDi script ID)
setScriptId(String id)	String (nullable)	void	Sets the optional script ID
creationScript()	none	String	Returns JS code: function __webdriver_{handle}(arguments) { {script} }
executionScript()	none	String	Returns JS code: return __webdriver_{handle}(arguments)
removalScript()	none	String	Returns JS code: __webdriver_{handle} = undefined

Static Methods (Package-Private)

Method	Input	Output	Description
pin(executor, script)	JavascriptExecutor, String	UnpinnedScriptKey	Creates a new key and registers it with the executor
unpin(executor, key)	JavascriptExecutor, UnpinnedScriptKey	void	Removes the key from the executor's registry
getPinnedScripts(executor)	JavascriptExecutor	Set<UnpinnedScriptKey> (unmodifiable)	Returns all pinned scripts for the given executor

Usage Examples

// Pin a script to a WebDriver session (via JavascriptExecutor API)
JavascriptExecutor executor = (JavascriptExecutor) driver;
ScriptKey key = executor.pin("return document.title");

// The pinned script can be executed multiple times efficiently
Object title1 = executor.executeScript(key);
driver.get("https://example.com/other");
Object title2 = executor.executeScript(key);

// Unpin when no longer needed
executor.unpin(key);

// Direct UnpinnedScriptKey usage (internal)
UnpinnedScriptKey scriptKey = new UnpinnedScriptKey("return arguments[0] + arguments[1]");
String creation = scriptKey.creationScript();
// "function __webdriver_<handle>(arguments) { return arguments[0] + arguments[1] }"
String execution = scriptKey.executionScript();
// "return __webdriver_<handle>(arguments)"
String removal = scriptKey.removalScript();
// "__webdriver_<handle> = undefined"

Related Pages

• Implementation:SeleniumHQ_Selenium_ScriptKey -- parent class providing the base identifier contract
• Implementation:SeleniumHQ_Selenium_WebDriverException -- base exception for WebDriver errors
• Concept:JavaScript_Execution -- the JavaScript execution and pinning model