/plumadriver

A Selenium WebDriver for jsdom

Primary LanguageTypeScriptMIT LicenseMIT

PlumaDriver

PlumaDriver is a Node.js implementation of the W3C WebDriver Recommendation for the jsdom library. The goal of this project is to provide an automation tool for jsdom in order to test web applications without the overhead of modern web browsers.

Getting Started

PlumaDriver can be used with the Java language binding for Selenium WebDriver (additional language bindings will be developed in the future). Alternatively, as a RESTful API, PlumaDriver can be used with any HTTP request client (see Using PlumaDriver Without Selenium).

Using PlumaDriver With Selenium Java

  1. Download or build the PlumaDriver executable.
  2. Add the pluma.jar file to your project libraries in addition to the Selenium Java bindings.

Sample Test

// Set PlumaDriver executable path
System.setProperty("webdriver.pluma.driver","<path_to_executable>");

// Create a driver Instance
Webdriver driver = new PlumaDriver();

driver.get("http://www.example.com"); // navigate to
WebElement e = driver.findElement(By.tagName("p"));
String text = e.getText();
System.out.println(text);
driver.quit();

WebDriver Options

PlumaOptions options = new PlumaOptions();

options.setAcceptInsecureCerts(false);
options.setRunScripts(true);
options.rejectPublicSuffixes(false);

PlumaDriver plumaDriver = new PlumaDriver(options);

The following options are available when creating a PlumaDriver instance:

  • AcceptInsecureCerts: Determines whether or not invalid SSL certificates are accepted.
  • RunScripts: Enables executing scripts inside the page. In most cases, you'll likely want to set this to true.
  • RejectPublicSuffixes: Determines whether or not cookies with domains like com and co.uk are rejected. See http://publicsuffix.org/ for more information.

PlumaDriver Lifetime

The PlumaDriver class will create a server instance at creation and destroy it when the quit() method is called. This means that for every instance of this class a separate server will be created resulting in a significant amount of resource usage. To reduce the resource consumption, the following options are available:

PlumaDriverService:

PlumaDriverService service = new PlumaDriverService() {
 .usingDriverExecuteable(new File("path/to/plumadriver/"))
 .usingAnyFreePort()
 .build();

service.start();

 WebDriver pluma = new RemoteWebDriver(service.getUrl(), new PlumaOptions());

Starting the PlumaDriver server directly from the terminal and connecting it to the Remote WebDriver:

Terminal:

./plumadriver --port=4040

Java:

WebDriver pluma = new RemoteWebDriver("http://127.0.0.1:4040", new PlumaOptions());
pluma.get("http://www.example.com");

Using PlumaDriver Without Selenium

You may also use PlumaDriver with any HTTP request software (e.g. Postman, fetch, cURL, etc.):

  1. Download or build PlumaDriver executable appropriate for your operating system.
  2. Run the executable. This will start the server by default on port 3000 (alternatively, set the port instead with --port <number>).
  3. Use your preferred HTTP Client to make requests to the endpoints.

Sample Test

POST the following example JSON to http://localhost:3000/session to create a new session:

{
  "capabilities": {
    "alwaysMatch": {
      "plm:plumaOptions": {
        "runScripts": true
      }
    }
  }
}

PlumaDriver should respond with a unique sessionId along with the session information:

{
    "value": {
        "sessionId": "<unique-id>",
        "capabilities": {...}
    }
}

You may use the above sessionId value provided by the web driver to make further requests. For instance, to navigate to a page, POST the following to http://localhost:3000/session/<sessionId>/url:

{
  "url": "http://example.com"
}

See the W3C endpoint specification or this simplified guide to learn more about how to work with WebDriver endpoints.

Building PlumaDriver

Requirements:

  • Ensure Node.js v12.19.0 is installed, or run nvm use.

From the command line:

  1. Clone this repository
  2. cd plumadriver
  3. npm install
  4. For Linux:
    npm run build:linux
    For Windows:
    npm run build:win
    For Mac:
    npm run build:macos

These scripts will transpile all the typescript code found within src directory and output the result to the build directory. From here pkg will create an executable which should appear in the project's root directory.

Completed Endpoints

It is important to keep in mind that jsdom is not intended to be a full rendering browser but rather emulate enough of a browser to be useful for testing and web scraping applications. As a result, W3C WebDriver endpoints which require browser rendering capabilities will not be implemented at this time.