chickadee » webdriver

Webdriver API

This egg implements the WebDriver API as specified by the W3C.

Table of Contents

Dependencies

srfi-34
Exception handling
srfi-35
Exception types
base64
Decoding screenshot data
http-client
API interaction
intarweb
Supporting HTTP functionality
uri-common
Supporting HTTP functionality
coops
Object system
alist-lib
Handling alists from JSON objects
medea
JSON handling

Error Conditions

Every API error code (key "error" in the returned JSON data) gets its own condition type, prefixed by &. They all inherit from &wd-exception. E.g. the error code "invalid argument" becomes &invalid-argument.

Using WebDriver

The main "entry point" of the library is the <WebDriver> class. Using it directly is not possible, since you need a specialized subclass for a WebDriver server. This library ships with <Gecko>, as the name suggests this is an implementation for Geckodriver and thus Firefox; but it is easily possible to extend it for other drivers.

If you want to implement a new driver, you will want to subclass <WebDriver> and override launch, construct-capabilities, and maybe postprocess-results.

<WebDriver>class

The main abstract implementation of the WebDriver API as a class. This needs to be subclassed for individual drivers.

<Gecko>class

A specialization of <WebDriver> for Mozilla's geckodriver.

make-WebDriver

make-WebDriver browser #!optional optionsprocedure

Create a new instance of a WebDriver. browser must be the class of the driver you want to use (e.g. <Gecko>), and options will be handed to the driver.

terminate

terminate instanceprocedure

Terminates the WebDriver instance.

Using the API

Communication

Data is sent to the API via a central class method. For convenience, there is a send-with-session variant that automatically adds the session id.

send instance data uri methodprocedure

Sends data (an alist) to the endpoint uri using method. instance may be either a <WebDriver> or <WDElement> class/subclass.

send-with-session instance data uri methodprocedure

Sends data (an alist) to the endpoint uri using method. instance may be either a <WebDriver> or <WDElement> class/subclass. Automatically adds the session id to the URL.

Session Management

initialize-session instanceprocedure

Creates a new session for the given WebDriver instance. Will fail if a session already exists.

terminate-session instanceprocedure

Terminates a session for the given WebDriver instance. This is also called automatically when using terminate.

API Access Methods

set-url instance urlprocedure
url instanceprocedure
back instanceprocedure
forward instanceprocedure
refresh instanceprocedure
title instanceprocedure
status instanceprocedure
source instanceprocedure
screenshot instanceprocedure
print-page instanceprocedure
execute-async instance script argsprocedure
execute-sync instance script argsprocedure

These call the respective WebDriver API endpoints.

Timeouts

The following timeouts are defined:
<WDTimeouts>class

Class with the slots script, pageLoad, implicit for you to set.

set-timeouts instance wdtimeoutsprocedure

Sets wdtimeouts for webdriver instance.

timeouts instanceprocedure

Returns an instance of <WDTimeouts> with the timeouts of webdriver instance.

Elements

<WDElement>class

A class representing a WebDriver page element.

The WebDriver API specifies a few strategies for you to choose from when extracting elements. This library provides constants for them so you don't have to write strings: css-selector, link-text, partial-link-text, tag-name, and xpath.

find-element instance strategy selectorprocedure

Finds an element in instance (which can be either a <WebDriver> or a <WDElement>) with selector using strategy.

find-elements instance strategy selectorprocedure

Finds a list of elements in instance (which can be either a <WebDriver> or a <WDElement>) with selector using strategy.

attribute instance attributeprocedure
property instance propertyprocedure
clear instanceprocedure
click instanceprocedure
computed-label instanceprocedure
computed-role instanceprocedure
enabled? instanceprocedure
selected? instanceprocedure
name instanceprocedure
rect instanceprocedure
screenshot instanceprocedure
text instanceprocedure
set-value instanceprocedure

Sends the respective API call for the element.

About This Egg

Source

The source repository is available at https://fossil.lyrion.ch/chicken-webdriver.

Author

Daniel Ziltener

Version History

0.5
Initial release

License

Copyright (C) 2023 Daniel Ziltener

All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of the <organization> nor the
      names of its contributors may be used to endorse or promote products
      derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Contents »