Implementation:SeleniumHQ Selenium JavascriptExecutor

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

Overview

Concrete tool for executing JavaScript code within a browser context provided by the Selenium WebDriver library.

Description

The JavascriptExecutor interface indicates that a WebDriver instance can execute JavaScript in the context of the currently selected frame or window. It provides synchronous execution via executeScript(), asynchronous execution via executeAsyncScript() (where the script must invoke a callback to signal completion), and a script pinning mechanism (pin(), unpin(), executeScript(ScriptKey, ...)) that allows frequently used scripts to be stored by handle for efficient repeated invocation.

Usage

Import and cast your WebDriver instance to JavascriptExecutor when you need to run arbitrary JavaScript in the browser, such as scrolling the page, reading computed styles, interacting with asynchronous operations, or manipulating the DOM beyond what the standard WebDriver API provides.

Code Reference

Source Location

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

Signature

public interface JavascriptExecutor {
    @Nullable Object executeScript(String script, @Nullable Object... args);
    @Nullable Object executeAsyncScript(String script, @Nullable Object... args);
    default ScriptKey pin(String script);
    default void unpin(ScriptKey key);
    default Set<ScriptKey> getPinnedScripts();
    default @Nullable Object executeScript(ScriptKey key, @Nullable Object... args);
}

Import

import org.openqa.selenium.JavascriptExecutor;

I/O Contract

Inputs

Name	Type	Required	Description
script	String	Yes	The JavaScript code to execute in the browser. For synchronous scripts, it runs as the body of an anonymous function. For async scripts, a callback is injected as the last argument.
args	Object...	No	Arguments passed to the script, accessible via the arguments variable. Must be a number, boolean, String, WebElement, or List of these types.
key	ScriptKey	Yes (for pinned execution)	A handle returned by pin() identifying a previously pinned script.

Outputs

Name	Type	Description
executeScript result	Object	One of Boolean, Long, Double, String, List<Object>, Map<String, Object>, WebElement, or null, depending on the JavaScript return value.
executeAsyncScript result	Object	One of Boolean, Long, String, List<Object>, Map<String, Object>, WebElement, or null, depending on the value passed to the callback.
pin result	ScriptKey	A handle that can be used to efficiently re-execute the pinned script.
getPinnedScripts result	Set<ScriptKey>	The set of all currently pinned script keys.

Usage Examples

import org.openqa.selenium.JavascriptExecutor;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.By;

WebDriver driver = // ... obtain driver instance
JavascriptExecutor js = (JavascriptExecutor) driver;

// Synchronous: scroll to the bottom of the page
js.executeScript("window.scrollTo(0, document.body.scrollHeight);");

// Synchronous: return the title via JavaScript
String title = (String) js.executeScript("return document.title;");
System.out.println("Page title: " + title);

// Pass a WebElement as an argument
WebElement element = driver.findElement(By.id("myElement"));
js.executeScript("arguments[0].style.border = '3px solid red';", element);

// Asynchronous: wait for a timeout in the browser
js.executeAsyncScript(
    "var callback = arguments[arguments.length - 1];" +
    "window.setTimeout(callback, 2000);"
);

// Pin a frequently used script
ScriptKey key = js.pin("return document.readyState;");
String state = (String) js.executeScript(key);
System.out.println("Ready state: " + state);
js.unpin(key);

Related Pages

• Principle:SeleniumHQ_Selenium_Browser_Interaction