# Autobahn|Testsuite: running the WebSocket conformance suite against your server

> Autobahn|Testsuite is a Python package that acts as a fuzzing server and client, drives an implementation through over 500 WebSocket test cases, and writes an HTML report per case. It is Apache-2.0 licensed, versioned on PyPI rather than through GitHub releases, and one of its coverage areas, the opening handshake, is still marked as under development.

**crossbario/autobahn-testsuite** — Autobahn WebSocket protocol testsuite

- Repository: https://github.com/crossbario/autobahn-testsuite
- Website: https://github.com/crossbario
- Stars: 1,693 · Forks: 112
- Language: Python
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/crossbario-autobahn-testsuite

## One tool, two roles: your code gets driven, not inspected

Autobahn|Testsuite does not analyse your source. It runs conversations against a live implementation and records what happens. That design is the reason it works across languages: the implementation only has to speak WebSocket over a socket.

The README describes it as a fully automated suite that verifies client and server implementations of The WebSocket Protocol, RFC 6455, for specification conformance and implementation robustness. It is also described as a fuzzing server and client, which names the mechanism. Rather than asserting specific values, the suite attempts handshakes, sends deliberately awkward frames and compares the responses against what the specification requires.

Both directions are covered. The same package can act as the server while your client connects to it, or as the client while your server accepts its connections, and the README points at separate report directories for client functionality and server functionality.

## What the 500 cases actually cover

Coverage is grouped by protocol area, and the list is worth reading as a checklist for your own implementation. Framing is first, then pings and pongs, reserved bits, opcodes, fragmentation, UTF-8 handling, limits and performance, and the closing handshake. Two more areas round it out: WebSocket compression through the permessage-deflate extension, and the opening handshake, which is explicitly marked as under development.

That parenthetical is the single most useful caveat in the README. Opening a WebSocket is where the upgrade request, the `Sec-WebSocket-Key` exchange, origin checks and extension negotiation happen, so the area with the most application-visible consequences is the one still being written. Treat a green report as evidence about framing and fragmentation rather than as a statement about your handshake policy.

The other distinction is between compliance and limits. The suite also includes limits and performance testing.

## wstest is more than the suite

The `wstest` command carries several modes beyond the conformance run, and they are what makes it useful day to day rather than only at release time.

There is a WebSocket echo server and client, which is the smallest thing you can point a browser or a script at to check connectivity. There is a WebSocket broadcast server with a client driver, so you can push one message to many connections. There is a WAMP server and client for developing WAMP implementations, plus testee modes for testing AutobahnPython against the suite itself.

Two entries are performance oriented. `wsperf` provides a controller and a master, so you can drive throughput measurements across many connections, and WebSocket Mass-Connect is a separate mode for opening large numbers of connections at once. The echo server and Mass-Connect provide two different modes.

## Install and run: PyPI, then point it at your implementation

The package is published on PyPI as `autobahntestsuite`, and the README links the Read the Docs site at `autobahntestsuite.readthedocs.io` for the full documentation. The executable is `wstest`.

The README does not print a `wstest` invocation with its flags, so take the exact option names from the documentation rather than from a tutorial. The shape of a run is determined by which side your code is on: if you are testing a server, the suite acts as the client and connects to the port your server listens on, and if you are testing a client, the suite listens and your client connects to it.

The example directories in the repository show both arrangements. `examples/fuzzingserver/` and `examples/fuzzingclient/` are the two halves, with `fuzzingwampclient/` for the WAMP variant, `publicreports/` for published report output and `wsperfcontrol/` for the performance controller.

One packaging detail is worth knowing. The `justfile` sets the package version to `25.10.1` and the copyright to typedef int GmbH, and it distinguishes two Python environments: a CPython 2.7 environment for packaging the testsuite and a CPython 3.14 environment for tooling such as Sphinx and Twine. That split is historical but it is still in the build file.

## No GitHub releases, and a repository that is still being reorganised

Distribution runs through PyPI, not GitHub releases, and the repository has no GitHub releases at all. The version badge in the README points at the PyPI page, so the version you install is whatever is on PyPI, and the `justfile` carries the matching `PACKAGE_VERSION` of `25.10.1`.

Maintenance is current by the push record: the last push was on 2026-10-14. What is less settled is the repository layout. Alongside the usual `autobahntestsuite/` package, `doc/`, `docs/`, `test/` and `examples/` directories, the top level contains `.ai`, `.audit/`, `.cicd/`, `.gemini/`, an `aspects.toml`, `AGENTS.md`-style files through `CLAUDE.md`, `AI_POLICY.md` and a `justfile`. The `.gitmodules` entry indicates submodules are in use, and `.cicd/workflow.just` is imported by the main `justfile` with a comment explaining that duplicate variable settings between the two files are a hard error in `just`.

The Apache-2.0 licence applies, and the repository carries both a LICENSE file and a CHANGELOG.

## Against your own unit tests, and against a modern runtime

The obvious comparison is with the unit tests you already have, and the README includes a user account that answers it directly. Norman Maurer of Red Hat, quoted on the topic of implementing the WebSocket version in Netty and Undertow, describes already having unit tests in place and finding a lack of good tests for the whole implementation, with the testsuite allowing the team to concentrate on the implementation and making it easy to catch regressions.

That is the real division of labour. Unit tests assert what you decided to build. This suite asserts what the specification requires, including the frames you did not think to handle.

The second alternative is a modern runtime with its own WebSocket test tooling. Python's own ecosystem, for instance, has libraries that come with test helpers written against the same runtime you deploy on. Those tests are faster to write and closer to your actual stack. They will also only ever exercise behaviour that library chose to model, which is the same blind spot the suite exists to remove.

A third option is a lighter conformance check written as a handful of hand built cases against the specific corner conditions you suspect. That is cheap and quick, and it will not find the problem in the area you did not suspect.

## Conclusion

Adopt Autobahn|Testsuite when you maintain a WebSocket server or client in any language and need an independent check against RFC 6455 rather than your own unit tests. Do not treat a passing report as complete coverage, since the README marks the opening handshake area as under development. Verify first that your implementation can be started on demand by the tool, because the suite connects to it as a client or accepts its connections as a server, and no integration recipe is documented in the README.

## FAQ

### What does Autobahn|Testsuite test?

It runs an implementation through over 500 WebSocket test cases covering framing, pings and pongs, reserved bits, opcodes, fragmentation, UTF-8 handling, limits and performance, the closing handshake and the permessage-deflate compression extension. The opening handshake area is marked as under development.

### How do I install Autobahn|Testsuite and what command do I run?

The package is published on PyPI as `autobahntestsuite` and the executable is `wstest`. The README does not list `wstest` flags, so the option names come from the documentation at autobahntestsuite.readthedocs.io.

### Can Autobahn|Testsuite test both my WebSocket server and my client?

Yes. The README describes both a fuzzing server and a fuzzing client mode, and publishes separate reports for WebSocket client functionality and WebSocket server functionality. The repository carries matching `examples/fuzzingserver/` and `examples/fuzzingclient/` directories.

### What other modes does wstest provide besides the conformance suite?

A WebSocket echo server and client, a WebSocket broadcast server with a client driver, testee modes for testing AutobahnPython, a WAMP server and client for WAMP implementors, WebSocket Mass-Connect, and the `wsperf` controller and master for performance runs.

### Does Autobahn|Testsuite support WebSocket compression?

Yes. The README lists WebSocket compression through the permessage-deflate extension among the covered areas.

## Sources

- [crossbario/autobahn-testsuite on GitHub](https://github.com/crossbario/autobahn-testsuite)
- [Issues](https://github.com/crossbario/autobahn-testsuite/issues)
- [License: Apache-2.0](https://github.com/crossbario/autobahn-testsuite/blob/master/LICENSE)
- [Project website](https://github.com/crossbario)
- [README](https://github.com/crossbario/autobahn-testsuite/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/crossbario-autobahn-testsuite