1 Overview of lws test apps
2 =========================
4 Are you building a client? You just need to look at the test client
5 [libwebsockets-test-client](test-server/test-client.c).
7 If you are building a standalone server, there are three choices, in order of
10 1) lwsws + protocol plugins
12 Lws provides a generic web server app that can be configured with JSON
13 config files. https://libwebsockets.org itself uses this method.
15 With lwsws handling the serving part, you only need to write an lws protocol
16 plugin. See [plugin-standalone](plugin-standalone) for an example of how
17 to do that outside lws itself, using lws public apis.
19 $ cmake .. -DLWS_WITH_LWSWS=1
21 See [README.lwsws.md](README.lwsws.md) for information on how to configure
24 NOTE this method implies libuv is used by lws, to provide crossplatform
25 implementations of timers, dynamic lib loading etc for plugins and lwsws.
29 This method lets you configure web serving in code, instead of using lwsws.
31 Plugins are still used, which implies libuv needed.
33 $ cmake .. -DLWS_WITH_PLUGINS=1
35 See [test-server-v2.0.c](test-server/test-server-v2.0.c)
37 3) protocols in the server app
39 This is the original way lws implemented servers, plugins and libuv are not
40 required, but without plugins separating the protocol code directly, the
41 combined code is all squidged together and is much less maintainable.
43 This method is still supported in lws but all ongoing and future work is
44 being done in protocol plugins only.
47 Notes about lws test apps
48 =========================
50 @section tsb Testing server with a browser
52 If you run [libwebsockets-test-server](test-server/test-server.c) and point your browser
57 It will fetch a script in the form of `test.html`, and then run the
58 script in there on the browser to open a websocket connection.
59 Incrementing numbers should appear in the browser display.
61 By default the test server logs to both stderr and syslog, you can control
62 what is logged using `-d <log level>`, see later.
65 @section tsd Running test server as a Daemon
67 You can use the -D option on the test server to have it fork into the
68 background and return immediately. In this daemonized mode all stderr is
69 disabled and logging goes only to syslog, eg, `/var/log/messages` or similar.
71 The server maintains a lockfile at `/tmp/.lwsts-lock` that contains the pid
72 of the master process, and deletes this file when the master process
75 To stop the daemon, do
77 $ kill cat /tmp/.lwsts-lock
79 If it finds a stale lock (the pid mentioned in the file does not exist
80 any more) it will delete the lock and create a new one during startup.
82 If the lock is valid, the daemon will exit with a note on stderr that
83 it was already running.
86 @section sssl Using SSL on the server side
88 To test it using SSL/WSS, just run the test server with
90 $ libwebsockets-test-server --ssl
94 https://127.0.0.1:7681
96 The connection will be entirely encrypted using some generated
97 certificates that your browser will not accept, since they are
98 not signed by any real Certificate Authority. Just accept the
99 certificates in the browser and the connection will proceed
100 in first https and then websocket wss, acting exactly the
103 [test-server.c](test-server/test-server.c) is all that is needed to use libwebsockets for
104 serving both the script html over http and websockets.
106 @section lwstsdynvhost Dynamic Vhosts
108 You can send libwebsockets-test-server or libwebsockets-test-server-v2.0 a SIGUSR1
109 to toggle the creation and destruction of an identical second vhost on port + 1.
111 This is intended as a test and demonstration for how to bring up and remove
114 @section wscl Testing websocket client support
116 If you run the test server as described above, you can also
117 connect to it using the test client as well as a browser.
120 $ libwebsockets-test-client localhost
123 will by default connect to the test server on localhost:7681
124 and print the dumb increment number from the server at the
125 same time as drawing random circles in the mirror protocol;
126 if you connect to the test server using a browser at the
127 same time you will be able to see the circles being drawn.
129 The test client supports SSL too, use
132 $ libwebsockets-test-client localhost --ssl -s
135 the -s tells it to accept the default self-signed cert from the server,
136 otherwise it will strictly fail the connection if there is no CA cert to
137 validate the server's certificate.
140 @section choosingts Choosing between test server variations
142 If you will be doing standalone serving with lws, ideally you should avoid
143 making your own server at all, and use lwsws with your own protocol plugins.
145 The second best option is follow test-server-v2.0.c, which uses a mount to
146 autoserve a directory, and lws protocol plugins for ws, without needing any
147 user callback code (other than what's needed in the protocol plugin).
149 For those two options libuv is needed to support the protocol plugins, if
150 that's not possible then the other variations with their own protocol code
151 should be considered.
154 @section echo Testing simple echo
156 You can test against `echo.websockets.org` as a sanity test like
157 this (the client connects to port `80` by default):
160 $ libwebsockets-test-echo --client echo.websocket.org
163 This echo test is of limited use though because it doesn't
164 negotiate any protocol. You can run the same test app as a
165 local server, by default on localhost:7681
167 $ libwebsockets-test-echo
169 and do the echo test against the local echo server
171 $ libwebsockets-test-echo --client localhost --port 7681
173 If you add the `--ssl` switch to both the client and server, you can also test
174 with an encrypted link.
177 @section tassl Testing SSL on the client side
179 To test SSL/WSS client action, just run the client test with
181 $ libwebsockets-test-client localhost --ssl
183 By default the client test applet is set to accept self-signed
184 certificates used by the test server, this is indicated by the
185 `use_ssl` var being set to `2`. Set it to `1` to reject any server
186 certificate that it doesn't have a trusted CA cert for.
189 @section taping Using the websocket ping utility
191 libwebsockets-test-ping connects as a client to a remote
192 websocket server and pings it like the
193 normal unix ping utility.
195 $ libwebsockets-test-ping localhost
196 handshake OK for protocol lws-mirror-protocol
197 Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
198 64 bytes from localhost: req=1 time=0.1ms
199 64 bytes from localhost: req=2 time=0.1ms
200 64 bytes from localhost: req=3 time=0.1ms
201 64 bytes from localhost: req=4 time=0.2ms
202 64 bytes from localhost: req=5 time=0.1ms
203 64 bytes from localhost: req=6 time=0.2ms
204 64 bytes from localhost: req=7 time=0.2ms
205 64 bytes from localhost: req=8 time=0.1ms
207 --- localhost.localdomain websocket ping statistics ---
208 8 packets transmitted, 8 received, 0% packet loss, time 7458ms
209 rtt min/avg/max = 0.110/0.185/0.218 ms
212 By default it sends 64 byte payload packets using the 04
213 PING packet opcode type. You can change the payload size
214 using the `-s=` flag, up to a maximum of 125 mandated by the
217 Using the lws-mirror protocol that is provided by the test
218 server, libwebsockets-test-ping can also use larger payload
219 sizes up to 4096 is BINARY packets; lws-mirror will copy
220 them back to the client and they appear as a PONG. Use the
221 `-m` flag to select this operation.
223 The default interval between pings is 1s, you can use the -i=
224 flag to set this, including fractions like `-i=0.01` for 10ms
227 Before you can even use the PING opcode that is part of the
228 standard, you must complete a handshake with a specified
229 protocol. By default lws-mirror-protocol is used which is
230 supported by the test server. But if you are using it on
231 another server, you can specify the protocol to handshake with
232 by `--protocol=protocolname`
235 @section ta fraggle Fraggle test app
237 By default it runs in server mode
239 $ libwebsockets-test-fraggle
240 libwebsockets test fraggle
241 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
242 Compiled with SSL support, not using it
243 Listening on port 7681
244 server sees client connect
245 accepted v06 connection
246 Spamming 360 random fragments
247 Spamming session over, len = 371913. sum = 0x2D3C0AE
248 Spamming 895 random fragments
249 Spamming session over, len = 875970. sum = 0x6A74DA1
252 You need to run a second session in client mode, you have to
253 give the `-c` switch and the server address at least:
255 $ libwebsockets-test-fraggle -c localhost
256 libwebsockets test fraggle
257 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
259 Connecting to localhost:7681
260 denied deflate-stream extension
261 handshake OK for protocol fraggle-protocol
262 client connects to server
263 EOM received 371913 correctly from 360 fragments
264 EOM received 875970 correctly from 895 fragments
265 EOM received 247140 correctly from 258 fragments
266 EOM received 695451 correctly from 692 fragments
269 The fraggle test sends a random number up to 1024 fragmented websocket frames
270 each of a random size between 1 and 2001 bytes in a single message, then sends
271 a checksum and starts sending a new randomly sized and fragmented message.
273 The fraggle test client receives the same message fragments and computes the
274 same checksum using websocket framing to see when the message has ended. It
275 then accepts the server checksum message and compares that to its checksum.
278 @section taproxy proxy support
280 The http_proxy environment variable is respected by the client
281 connection code for both `ws://` and `wss://`. It doesn't support
286 $ export http_proxy=myproxy.com:3128
287 $ libwebsockets-test-client someserver.com
290 @section talog debug logging
292 By default logging of severity "notice", "warn" or "err" is enabled to stderr.
294 Again by default other logging is compiled in but disabled from printing.
296 By default debug logs below "notice" in severity are not compiled in. To get
297 them included, add this option in CMAKE
300 $ cmake .. -DCMAKE_BUILD_TYPE=DEBUG
303 If you want to see more detailed debug logs, you can control a bitfield to
304 select which logs types may print using the `lws_set_log_level()` api, in the
305 test apps you can use `-d <number>` to control this. The types of logging
306 available are (OR together the numbers to select multiple)
320 @section ws13 Websocket version supported
322 The final IETF standard is supported for both client and server, protocol
326 @section latency Latency Tracking
328 Since libwebsockets runs using `poll()` and a single threaded approach, any
329 unexpected latency coming from system calls would be bad news. There's now
330 a latency tracking scheme that can be built in with `--with-latency` at
331 configure-time, logging the time taken for system calls to complete and if
332 the whole action did complete that time or was deferred.
334 You can see the detailed data by enabling logging level 512 (eg, `-d 519` on
335 the test server to see that and the usual logs), however even without that
336 the "worst" latency is kept and reported to the logs with NOTICE severity
337 when the context is destroyed.
339 Some care is needed interpreting them, if the action completed the first figure
340 (in us) is the time taken for the whole action, which may have retried through
341 the poll loop many times and will depend on network roundtrip times. High
342 figures here don't indicate a problem. The figure in us reported after "lat"
343 in the logging is the time taken by this particular attempt. High figures
344 here may indicate a problem, or if you system is loaded with another app at
345 that time, such as the browser, it may simply indicate the OS gave preferential
346 treatment to the other app during that call.
349 @section autobahn Autobahn Test Suite
351 Lws can be tested against the autobahn websocket fuzzer.
353 1) pip install autobahntestsuite
355 2) wstest -m fuzzingserver
357 3) Run tests like this
359 libwebsockets-test-echo --client localhost --port 9001 -u "/runCase?case=20&agent=libwebsockets" -v -d 65535 -n 1
363 4) In a browser, go here
365 http://localhost:8080/test_browser.html
367 fill in "libwebsockets" in "User Agent Identifier" and press "Update Reports (Manual)"
369 5) In a browser go to the directory you ran wstest in (eg, /projects/libwebsockets)
371 file:///projects/libwebsockets/reports/clients/index.html
376 @section autobahnnotes Autobahn Test Notes
378 1) Autobahn tests the user code + lws implementation. So to get the same
379 results, you need to follow test-echo.c in terms of user implementation.
381 2) Two of the tests make no sense for Libwebsockets to support and we fail them.
383 - Tests 2.10 + 2.11: sends multiple pings on one connection. Lws policy is to
384 only allow one active ping in flight on each connection, the rest are dropped.
385 The autobahn test itself admits this is not part of the standard, just someone's
386 random opinion about how they think a ws server should act. So we will fail
387 this by design and it is no problem about RFC6455 compliance.