Fork of HTMLUnit with WebSocket support
JavaScript Java PHP Ruby Python Visual Basic
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


HTMLUnit with WebSocket support

This is a (temporary) fork of HTMLUnit with the purpose of adding WebSocket support. The fork is an import of revision 6270 of

I didn’t use git-svn as I couldn’t get it to work. This means this fork won’t be kept in sync with the official HTMLUnit in Subversion. Instead, a complete patch will be sent to the HTMLUnit project when WebSocket support is good enough.

HTMLUnit’s issue tracker has an open ticket for WebSocket support, but I’m not aware that anyone else has started working on it yet.

EDIT: I’ve been made aware of an unmerged patch by Marko Vuksanovic. It’s certainly more elaborate than this fork. You may want to apply that patch instead…

If you have comments and suggestions, please use this project’s issue tracker instead of sending me personal messages, so that other interested people can join the discussion.


The status of the API implementation is:


  • WebSocket(url): Implemented
  • WebSocket(url, protocols): Not Implemented

Event Handlers

  • onopen: Implemented
  • onmessage: Implemented
  • onerror: Not Implemented
  • onclose: Not Implemented

Readonly Properties

  • url: Implemented
  • readyState: Not Implemented
  • bufferedAmount: Not Implemented
  • protocol: Not Implemented


  • send: Implemented
  • close: Implemented


If you want to hack on this, the test you want to run is This test uses Webbit – a fast async Web Server. Until Webbit lands in a Maven repo, you can install it in your local Maven repo by cloning the Webbit repo and run:

mvn install:install-file -DgroupId=webbit -DartifactId=webbit -Dversion=0.0.1 -Dpackaging=jar -Dfile=build/webbit.jar

If you want to build htmlunit without running all of the tests (very slow):

mvn clean install -Dmaven.test.skip=true

When you have done this once, tack on -o to put maven offline and make it faster.


HTMLUnit uses Apache HTTP Components elsewhere in the code, but since it doesn’t implement the WebSocket protocol I couldn’t use that. I also looked at Ning Async Http Client, but it doesn’t implement WebSocket either.

I therefore went with Adam MacBeth’s WebSocket Client, which now lives in As Adam mentions in the README his implementation is out of date with the current spec, but it’s good enough for my purposes for now.

I may switch to or any other library that implements the protocol more faithfully later.


  1. Implement the entire Javascript API
  2. Find a way to close al websockets if the page doesn’t do it itself.

Currently the WebSocket must be closed in Javascript, or your JUnit tests will hang. Comment out the ws.close(); in to see this.
I haven’t found a way to work around this, so contributions are welcome.