SeleniumServer (Selenium RC Server (Coreless) 1.0.1 API)
Date: 2009-06-09

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.openqa.selenium.server
Class SeleniumServer

    java.lang.Object
      org.openqa.selenium.server.SeleniumServer

    public class SeleniumServer

extends java.lang.Object

Provides a server that can launch/terminate browsers and can receive remote Selenium commands over HTTP and send them on to the browser.

To run Selenium Server, run:

> `java -jar selenium-server-1.0-SNAPSHOT.jar [-port 4444] [-interactive] [-timeout 1800]`

Where `-port` specifies the port you wish to run the Server on (default is 4444).

Where `-timeout` specifies the number of seconds that you allow data to wait all in the communications queues before an exception is thrown.

Using the `-interactive` flag will start the server in Interactive mode. In this mode you can type remote Selenium commands on the command line (e.g. cmd=open&1=http://www.yahoo.com). You may also interactively specify commands to run on a particular "browser session" (see below) like this:

> `cmd=open&1=http://www.yahoo.com&sessionId=1234`

The server accepts three types of HTTP requests on its port:

1. Client-Configured Proxy Requests: By configuring your browser to use the Selenium Server as an HTTP proxy, you can use the Selenium Server as a web proxy. This allows the server to create a virtual "/selenium-server" directory on every website that you visit using the proxy.
2. Remote Browser Commands: If the browser goes to "/selenium-server/RemoteRunner.html?sessionId=1234" on any website via the Client-Configured Proxy, it will ask the Selenium Server for work to do, like this:

   > `http://www.yahoo.com/selenium-server/driver/?seleniumStart=true&sessionId=1234`

   The driver will then reply with a command to run in the body of the HTTP response, e.g. "|open|http://www.yahoo.com||". Once the browser is done with this request, the browser will issue a new request for more work, this time reporting the results of the previous command:

   > `http://www.yahoo.com/selenium-server/driver/?commandResult=OK&sessionId=1234`

   The action list is listed in selenium-api.js. Normal actions like "doClick" will return "OK" if clicking was successful, or some other error string if there was an error. Assertions like assertTextPresent or verifyTextPresent will return "PASSED" if the assertion was true, or some other error string if the assertion was false. Getters like "getEval" will return the result of the get command. "getAllLinks" will return a comma-delimited list of links.
3. Driver Commands: Clients may send commands to the Selenium Server over HTTP. Command requests should look like this:

   > `http://localhost:4444/selenium-server/driver/?commandRequest=|open|http://www.yahoo.com||&sessionId=1234`

   The Selenium Server will not respond to the HTTP request until the browser has finished performing the requested command; when it does, it will reply with the result of the command (e.g. "OK" or "PASSED") in the body of the HTTP response. (Note that `-interactive` mode also works by sending these HTTP requests, so tests using `-interactive` mode will behave exactly like an external client driver.)

There are some special commands that only work in the Selenium Server. These commands are:

- getNewBrowserSession( browserString, startURL )

  Creates a new "sessionId" number (based on the current time in milliseconds) and launches the browser specified in browserString. We will then browse directly to startURL + "/selenium-server/RemoteRunner.html?sessionId=###" where "###" is the sessionId number. Only commands that are associated with the specified sessionId will be run by this browser.

  browserString may be any one of the following:

  - `*firefox [absolute path]` - Automatically launch a new Firefox process using a custom Firefox profile. This profile will be automatically configured to use the Selenium Server as a proxy and to have all annoying prompts ("save your password?" "forms are insecure" "make Firefox your default browser?" disabled. You may optionally specify an absolute path to your firefox executable, or just say "*firefox". If no absolute path is specified, we'll look for firefox.exe in a default location (normally c:\program files\mozilla firefox\firefox.exe), which you can override by setting the Java system property `firefoxDefaultPath` to the correct path to Firefox.
  - `*iexplore [absolute path]` - Automatically launch a new Internet Explorer process using custom Windows registry settings. This process will be automatically configured to use the Selenium Server as a proxy and to have all annoying prompts ("save your password?" "forms are insecure" "make Firefox your default browser?" disabled. You may optionally specify an absolute path to your iexplore executable, or just say "*iexplore". If no absolute path is specified, we'll look for iexplore.exe in a default location (normally c:\program files\internet explorer\iexplore.exe), which you can override by setting the Java system property `iexploreDefaultPath` to the correct path to Internet Explorer.
  - `/path/to/my/browser [other arguments]` - You may also simply specify the absolute path to your browser executable, or use a relative path to your executable (which we'll try to find on your path). Warning: If you specify your own custom browser, it's up to you to configure it correctly. At a minimum, you'll need to configure your browser to use the Selenium Server as a proxy, and disable all browser-specific prompting.

- testComplete( )

  Kills the currently running browser and erases the old browser session. If the current browser session was not launched using `getNewBrowserSession`, or if that session number doesn't exist in the server, this command will return an error.

- shutDown( )

  Causes the server to shut itself down, killing itself and all running browsers along with it.

Example:

> `cmd=getNewBrowserSession&1=*firefox&2=http://www.google.com
> Got result: 1140738083345
> cmd=open&1=http://www.google.com&sessionId=1140738083345
> Got result: OK
> cmd=type&1=q&2=hello world&sessionId=1140738083345
> Got result: OK
> cmd=testComplete&sessionId=1140738083345
> Got result: OK`

#### The "null" session

If you open a browser manually and do not specify a session ID, it will look for commands using the "null" session. You may then similarly send commands to this browser by not specifying a sessionId when issuing commands.

Author:
  plightbo

Field Summary
`static int` | `DEFAULT_JETTY_THREADS`

Constructor Summary
`SeleniumServer()`
`SeleniumServer(boolean slowResources)`
`SeleniumServer(boolean slowResources, RemoteControlConfiguration configuration)` Prepares a Jetty server with its HTTP handlers.
`SeleniumServer(RemoteControlConfiguration configuration)`

Method Summary
`void` | `addNewStaticContent(java.io.File directory)`
`void` | `boot()`
`protected static void` | `checkArgsSanity(RemoteControlConfiguration configuration)`
`protected void` | `createJettyServer(boolean slowResources)`
`protected org.mortbay.http.HttpContext` | `createRootContextWithProxyHandler(RemoteControlConfiguration configuration)`
`void` | `deregisterBrowserSession(BrowserSessionFactory.BrowserSessionInfo sessionInfo)` De-registers a previously registered running browser session
`void` | `generateSSLCertsForLoggingHosts()` pre-compute the 1-16 SSL relays+certs for the logging hosts.
`RemoteControlConfiguration` | `getConfiguration()`
`int` | `getJettyThreads()` Get the number of threads that the server will use to configure the embedded Jetty instance.
`int` | `getPort()`
`java.io.InputStream` | `getResourceAsStream(java.lang.String path)`
`org.mortbay.jetty.Server` | `getServer()` Exposes the internal Jetty server used by Selenium.
`void` | `handleHTMLRunnerResults(HTMLResultsListener listener)`
`static void` | `main(java.lang.String[] args)` Starts up the server on the specified port (or default if no port was specified) and then starts interactive mode if specified.
`protected ProxyHandler` | `makeProxyHandler(RemoteControlConfiguration configuration)`
`protected void` | `readUserCommands()`
`void` | `registerBrowserSession(BrowserSessionFactory.BrowserSessionInfo sessionInfo)` Registers a running browser session
`protected void` | `runHtmlSuite()`
`protected boolean` | `runSelfTests()`
`static void` | `setCustomProxyHandler(ProxyHandler customProxyHandler)` Used for implementations that invoke SeleniumServer programmatically and require additional logic when proxying data.
`void` | `start()` Starts the Jetty server
`void` | `stop()` Stops the Jetty server

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DEFAULT_JETTY_THREADS

    public static int DEFAULT_JETTY_THREADS

Constructor Detail

### SeleniumServer

    public SeleniumServer()
                   throws java.lang.Exception

Throws:
  `java.lang.Exception`

### SeleniumServer

    public SeleniumServer(RemoteControlConfiguration configuration)
                   throws java.lang.Exception

Throws:
  `java.lang.Exception`

### SeleniumServer

    public SeleniumServer(boolean slowResources)
                   throws java.lang.Exception

Throws:
  `java.lang.Exception`

### SeleniumServer

    public SeleniumServer(boolean slowResources,
                          RemoteControlConfiguration configuration)
                   throws java.lang.Exception

  Prepares a Jetty server with its HTTP handlers. p

  Parameters:
    `slowResources` - should the webserver return static resources more slowly? (Note that this will not slow down ordinary RC test runs; this setting is used to debug Selenese HTML tests.)
    `configuration` - Remote Control configuration. Cannot be null.
  Throws:
    `java.lang.Exception` - you know, just in case

Method Detail

### main

    public static void main(java.lang.String[] args)
                     throws java.lang.Exception

  Starts up the server on the specified port (or default if no port was specified) and then starts interactive mode if specified.

  Parameters:
    `args` - - either "-port" followed by a number, or "-interactive"
  Throws:
    `java.lang.Exception` - - you know, just in case.

### boot

    public void boot()
              throws java.lang.Exception

  Throws:
    `java.lang.Exception`

### createJettyServer

    protected void createJettyServer(boolean slowResources)

### createRootContextWithProxyHandler

    protected org.mortbay.http.HttpContext createRootContextWithProxyHandler(RemoteControlConfiguration configuration)

### generateSSLCertsForLoggingHosts

    public void generateSSLCertsForLoggingHosts()

  pre-compute the 1-16 SSL relays+certs for the logging hosts. (see selenium-remoterunner.js sendToRCAndForget for more info)

### makeProxyHandler

    protected ProxyHandler makeProxyHandler(RemoteControlConfiguration configuration)

### addNewStaticContent

    public void addNewStaticContent(java.io.File directory)

### handleHTMLRunnerResults

    public void handleHTMLRunnerResults(HTMLResultsListener listener)

### start

    public void start()
               throws java.lang.Exception

  Starts the Jetty server

  Throws:
    `java.lang.Exception` - on error.

### setCustomProxyHandler

    public static void setCustomProxyHandler(ProxyHandler customProxyHandler)

  Used for implementations that invoke SeleniumServer programmatically and require additional logic when proxying data.

### stop

    public void stop()

  Stops the Jetty server

### getConfiguration

    public RemoteControlConfiguration getConfiguration()

### getPort

    public int getPort()

### getServer

    public org.mortbay.jetty.Server getServer()

  Exposes the internal Jetty server used by Selenium. This lets users add their own webapp to the Selenium Server jetty instance. It is also a minor violation of encapsulation principles (what if we stop using Jetty?) but life is too short to worry about such things.

  Returns:
    the internal Jetty server, pre-configured with the /selenium-server context as well as the proxy server on /

### getResourceAsStream

    public java.io.InputStream getResourceAsStream(java.lang.String path)
                                            throws java.io.IOException

  Throws:
    `java.io.IOException`

### registerBrowserSession

    public void registerBrowserSession(BrowserSessionFactory.BrowserSessionInfo sessionInfo)

  Registers a running browser session

### deregisterBrowserSession

    public void deregisterBrowserSession(BrowserSessionFactory.BrowserSessionInfo sessionInfo)

  De-registers a previously registered running browser session

### getJettyThreads

    public int getJettyThreads()

  Get the number of threads that the server will use to configure the embedded Jetty instance.

  Returns:
    Returns the number of threads for Jetty.

### runHtmlSuite

    protected void runHtmlSuite()

### readUserCommands

    protected void readUserCommands()
                             throws java.io.IOException

  Throws:
    `java.io.IOException`

### runSelfTests

    protected boolean runSelfTests()
                            throws java.io.IOException

  Throws:
    `java.io.IOException`

### checkArgsSanity

    protected static void checkArgsSanity(RemoteControlConfiguration configuration)
                                   throws java.lang.Exception

  Throws:
    `java.lang.Exception`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2009. All Rights Reserved.