1 Testing server with a browser
2 -----------------------------
4 If you run [libwebsockets-test-server](test-server/test-server.c) and point your browser
9 It will fetch a script in the form of `test.html`, and then run the
10 script in there on the browser to open a websocket connection.
11 Incrementing numbers should appear in the browser display.
13 By default the test server logs to both stderr and syslog, you can control
14 what is logged using `-d <log level>`, see later.
17 Running test server as a Daemon
18 -------------------------------
20 You can use the -D option on the test server to have it fork into the
21 background and return immediately. In this daemonized mode all stderr is
22 disabled and logging goes only to syslog, eg, `/var/log/messages` or similar.
24 The server maintains a lockfile at `/tmp/.lwsts-lock` that contains the pid
25 of the master process, and deletes this file when the master process
28 To stop the daemon, do
31 $ kill `cat /tmp/.lwsts-lock`
34 If it finds a stale lock (the pid mentioned in the file does not exist
35 any more) it will delete the lock and create a new one during startup.
37 If the lock is valid, the daemon will exit with a note on stderr that
38 it was already running.
41 Using SSL on the server side
42 ----------------------------
44 To test it using SSL/WSS, just run the test server with
47 $ libwebsockets-test-server --ssl
52 https://127.0.0.1:7681
54 The connection will be entirely encrypted using some generated
55 certificates that your browser will not accept, since they are
56 not signed by any real Certificate Authority. Just accept the
57 certificates in the browser and the connection will proceed
58 in first https and then websocket wss, acting exactly the
61 [test-server.c](test-server/test-server.c) is all that is needed to use libwebsockets for
62 serving both the script html over http and websockets.
65 Testing websocket client support
66 --------------------------------
68 If you run the test server as described above, you can also
69 connect to it using the test client as well as a browser.
72 $ libwebsockets-test-client localhost
75 will by default connect to the test server on localhost:7681
76 and print the dumb increment number from the server at the
77 same time as drawing random circles in the mirror protocol;
78 if you connect to the test server using a browser at the
79 same time you will be able to see the circles being drawn.
81 The test client supports SSL too, use
84 $ libwebsockets-test-client localhost --ssl -s
87 the -s tells it to accept the default selfsigned cert from the server,
88 otherwise it will strictly fail the connection if there is no CA cert to
89 validate the server's certificate.
92 Choosing between test server variations
93 ---------------------------------------
95 If you will be doing standalone serving with lws, ideally you should avoid
96 making your own server at all, and use lwsws with your own protocol plugins.
98 The second best option is follow test-server-v2.0.c, which uses a mount to
99 autoserve a directory, and lws protocol plugins for ws, without needing any
100 user callback code (other than what's needed in the protocol plugin).
102 For those two options libuv is needed to support the protocol plugins, if
103 that's not possible then the other variations with their own protocol code
104 should be considered.
110 You can test against `echo.websockets.org` as a sanity test like
111 this (the client connects to port `80` by default):
114 $ libwebsockets-test-echo --client echo.websocket.org
117 This echo test is of limited use though because it doesn't
118 negotiate any protocol. You can run the same test app as a
119 local server, by default on localhost:7681
122 $ libwebsockets-test-echo
125 and do the echo test against the local echo server
128 $ libwebsockets-test-echo --client localhost --port 7681
131 If you add the `--ssl` switch to both the client and server, you can also test
132 with an encrypted link.
135 Testing SSL on the client side
136 ------------------------------
138 To test SSL/WSS client action, just run the client test with
141 $ libwebsockets-test-client localhost --ssl
144 By default the client test applet is set to accept selfsigned
145 certificates used by the test server, this is indicated by the
146 `use_ssl` var being set to `2`. Set it to `1` to reject any server
147 certificate that it doesn't have a trusted CA cert for.
150 Using the websocket ping utility
151 --------------------------------
153 libwebsockets-test-ping connects as a client to a remote
154 websocket server using 04 protocol and pings it like the
155 normal unix ping utility.
158 $ libwebsockets-test-ping localhost
159 handshake OK for protocol lws-mirror-protocol
160 Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
161 64 bytes from localhost: req=1 time=0.1ms
162 64 bytes from localhost: req=2 time=0.1ms
163 64 bytes from localhost: req=3 time=0.1ms
164 64 bytes from localhost: req=4 time=0.2ms
165 64 bytes from localhost: req=5 time=0.1ms
166 64 bytes from localhost: req=6 time=0.2ms
167 64 bytes from localhost: req=7 time=0.2ms
168 64 bytes from localhost: req=8 time=0.1ms
170 --- localhost.localdomain websocket ping statistics ---
171 8 packets transmitted, 8 received, 0% packet loss, time 7458ms
172 rtt min/avg/max = 0.110/0.185/0.218 ms
176 By default it sends 64 byte payload packets using the 04
177 PING packet opcode type. You can change the payload size
178 using the `-s=` flag, up to a maximum of 125 mandated by the
181 Using the lws-mirror protocol that is provided by the test
182 server, libwebsockets-test-ping can also use larger payload
183 sizes up to 4096 is BINARY packets; lws-mirror will copy
184 them back to the client and they appear as a PONG. Use the
185 `-m` flag to select this operation.
187 The default interval between pings is 1s, you can use the -i=
188 flag to set this, including fractions like `-i=0.01` for 10ms
191 Before you can even use the PING opcode that is part of the
192 standard, you must complete a handshake with a specified
193 protocol. By default lws-mirror-protocol is used which is
194 supported by the test server. But if you are using it on
195 another server, you can specify the protcol to handshake with
196 by `--protocol=protocolname`
202 By default it runs in server mode
205 $ libwebsockets-test-fraggle
206 libwebsockets test fraggle
207 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
208 Compiled with SSL support, not using it
209 Listening on port 7681
210 server sees client connect
211 accepted v06 connection
212 Spamming 360 random fragments
213 Spamming session over, len = 371913. sum = 0x2D3C0AE
214 Spamming 895 random fragments
215 Spamming session over, len = 875970. sum = 0x6A74DA1
219 You need to run a second session in client mode, you have to
220 give the `-c` switch and the server address at least:
223 $ libwebsockets-test-fraggle -c localhost
224 libwebsockets test fraggle
225 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
227 Connecting to localhost:7681
228 denied deflate-stream extension
229 handshake OK for protocol fraggle-protocol
230 client connects to server
231 EOM received 371913 correctly from 360 fragments
232 EOM received 875970 correctly from 895 fragments
233 EOM received 247140 correctly from 258 fragments
234 EOM received 695451 correctly from 692 fragments
238 The fraggle test sends a random number up to 1024 fragmented websocket frames
239 each of a random size between 1 and 2001 bytes in a single message, then sends
240 a checksum and starts sending a new randomly sized and fragmented message.
242 The fraggle test client receives the same message fragments and computes the
243 same checksum using websocket framing to see when the message has ended. It
244 then accepts the server checksum message and compares that to its checksum.
250 The http_proxy environment variable is respected by the client
251 connection code for both `ws://` and `wss://`. It doesn't support
257 $ export http_proxy=myproxy.com:3128
258 $ libwebsockets-test-client someserver.com
265 By default logging of severity "notice", "warn" or "err" is enabled to stderr.
267 Again by default other logging is compiled in but disabled from printing.
269 If you want to eliminate the debug logging below notice in severity, use the
270 `--disable-debug` configure option to have it removed from the code by the
273 If you want to see more detailed debug logs, you can control a bitfield to
274 select which logs types may print using the `lws_set_log_level()` api, in the
275 test apps you can use `-d <number>` to control this. The types of logging
276 available are (OR together the numbers to select multiple)
290 Websocket version supported
291 ---------------------------
293 The final IETF standard is supported for both client and server, protocol
300 Since libwebsockets runs using `poll()` and a single threaded approach, any
301 unexpected latency coming from system calls would be bad news. There's now
302 a latency tracking scheme that can be built in with `--with-latency` at
303 configure-time, logging the time taken for system calls to complete and if
304 the whole action did complete that time or was deferred.
306 You can see the detailed data by enabling logging level 512 (eg, `-d 519` on
307 the test server to see that and the usual logs), however even without that
308 the "worst" latency is kept and reported to the logs with NOTICE severity
309 when the context is destroyed.
311 Some care is needed interpreting them, if the action completed the first figure
312 (in us) is the time taken for the whole action, which may have retried through
313 the poll loop many times and will depend on network roundtrip times. High
314 figures here don't indicate a problem. The figure in us reported after "lat"
315 in the logging is the time taken by this particular attempt. High figures
316 here may indicate a problem, or if you system is loaded with another app at
317 that time, such as the browser, it may simply indicate the OS gave preferential
318 treatment to the other app during that call.
324 Lws can be tested against the autobahn websocket fuzzer.
326 1) pip install autobahntestsuite
328 2) wstest -m fuzzingserver
330 3) Run tests like this
332 libwebsockets-test-echo --client localhost --port 9001 -u "/runCase?case=20&agent=libwebsockets" -v -d 65535 -n 1
336 4) In a browser, go here
338 http://localhost:8080/test_browser.html
340 fill in "libwebsockets" in "User Agent Identifier" and press "Update Reports (Manual)"
342 5) In a browser go to the directory you ran wstest in (eg, /projects/libwebsockets)
344 file:///projects/libwebsockets/reports/clients/index.html
352 1) Autobahn tests the user code + lws implementation. So to get the same
353 results, you need to follow test-echo.c in terms of user implmentation.
355 2) Some of the tests make no sense for Libwebsockets to support and we fail them.
357 - Tests 2.10 + 2.11: sends multiple pings on one connection. Lws policy is to
358 only allow one active ping in flight on each connection, the rest are dropped.
359 The autobahn test itself admits this is not part of the standard, just someone's
360 random opinion about how they think a ws server should act. So we will fail
361 this by design and it is no problem about RFC6455 compliance.