README.test-apps.md

   1 Testing server with a browser
   2 -----------------------------
   3
   4 If you run [libwebsockets-test-server](test-server/test-server.c) and point your browser
   5 (eg, Chrome) to
   6
   7   http://127.0.0.1:7681
   8
   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.
  12
  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.
  15
  16
  17 Running test server as a Daemon
  18 -------------------------------
  19
  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.
  23
  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
  26 terminates.
  27
  28 To stop the daemon, do
  29
  30 ```bash
  31 $ kill `cat /tmp/.lwsts-lock`
  32 ```
  33
  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.
  36
  37 If the lock is valid, the daemon will exit with a note on stderr that
  38 it was already running.
  39
  40
  41 Using SSL on the server side
  42 ----------------------------
  43
  44 To test it using SSL/WSS, just run the test server with
  45
  46 ```bash
  47 $ libwebsockets-test-server --ssl
  48 ```
  49
  50 and use the URL
  51
  52   https://127.0.0.1:7681
  53
  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
  59 same.
  60
  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.
  63
  64
  65 Testing websocket client support
  66 --------------------------------
  67
  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.
  70
  71 ```bash
  72 $ libwebsockets-test-client localhost
  73 ```
  74
  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.
  80
  81
  82 Testing simple echo
  83 -------------------
  84
  85 You can test against `echo.websockets.org` as a sanity test like
  86 this (the client connects to port `80` by default):
  87
  88 ```bash
  89 $ libwebsockets-test-echo --client echo.websocket.org
  90 ```
  91
  92 This echo test is of limited use though because it doesn't
  93 negotiate any protocol.  You can run the same test app as a
  94 local server, by default on localhost:7681
  95
  96 ```bash
  97 $ libwebsockets-test-echo
  98 ```
  99
 100 and do the echo test against the local echo server
 101
 102 ```bash
 103 $ libwebsockets-test-echo --client localhost --port 7681
 104 ```
 105
 106 If you add the `--ssl` switch to both the client and server, you can also test
 107 with an encrypted link.
 108
 109
 110 Testing SSL on the client side
 111 ------------------------------
 112
 113 To test SSL/WSS client action, just run the client test with
 114
 115 ```bash
 116 $ libwebsockets-test-client localhost --ssl
 117 ```
 118
 119 By default the client test applet is set to accept selfsigned
 120 certificates used by the test server, this is indicated by the
 121 `use_ssl` var being set to `2`.  Set it to `1` to reject any server
 122 certificate that it doesn't have a trusted CA cert for.
 123
 124
 125 Using the websocket ping utility
 126 --------------------------------
 127
 128 libwebsockets-test-ping connects as a client to a remote
 129 websocket server using 04 protocol and pings it like the
 130 normal unix ping utility.
 131
 132 ```bash
 133 $ libwebsockets-test-ping localhost
 134 handshake OK for protocol lws-mirror-protocol
 135 Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
 136 64 bytes from localhost: req=1 time=0.1ms
 137 64 bytes from localhost: req=2 time=0.1ms
 138 64 bytes from localhost: req=3 time=0.1ms
 139 64 bytes from localhost: req=4 time=0.2ms
 140 64 bytes from localhost: req=5 time=0.1ms
 141 64 bytes from localhost: req=6 time=0.2ms
 142 64 bytes from localhost: req=7 time=0.2ms
 143 64 bytes from localhost: req=8 time=0.1ms
 144 ^C
 145 --- localhost.localdomain websocket ping statistics ---
 146 8 packets transmitted, 8 received, 0% packet loss, time 7458ms
 147 rtt min/avg/max = 0.110/0.185/0.218 ms
 148 $
 149 ```
 150
 151 By default it sends 64 byte payload packets using the 04
 152 PING packet opcode type.  You can change the payload size
 153 using the `-s=` flag, up to a maximum of 125 mandated by the
 154 04 standard.
 155
 156 Using the lws-mirror protocol that is provided by the test
 157 server, libwebsockets-test-ping can also use larger payload
 158 sizes up to 4096 is BINARY packets; lws-mirror will copy
 159 them back to the client and they appear as a PONG.  Use the
 160 `-m` flag to select this operation.
 161
 162 The default interval between pings is 1s, you can use the -i=
 163 flag to set this, including fractions like `-i=0.01` for 10ms
 164 interval.
 165
 166 Before you can even use the PING opcode that is part of the
 167 standard, you must complete a handshake with a specified
 168 protocol.  By default lws-mirror-protocol is used which is
 169 supported by the test server.  But if you are using it on
 170 another server, you can specify the protcol to handshake with
 171 by `--protocol=protocolname`
 172
 173
 174 Fraggle test app
 175 ----------------
 176
 177 By default it runs in server mode
 178
 179 ```bash
 180 $ libwebsockets-test-fraggle
 181 libwebsockets test fraggle
 182 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
 183  Compiled with SSL support, not using it
 184  Listening on port 7681
 185 server sees client connect
 186 accepted v06 connection
 187 Spamming 360 random fragments
 188 Spamming session over, len = 371913. sum = 0x2D3C0AE
 189 Spamming 895 random fragments
 190 Spamming session over, len = 875970. sum = 0x6A74DA1
 191 ...
 192 ```
 193
 194 You need to run a second session in client mode, you have to
 195 give the `-c` switch and the server address at least:
 196
 197 ```bash
 198 $ libwebsockets-test-fraggle -c localhost
 199 libwebsockets test fraggle
 200 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
 201  Client mode
 202 Connecting to localhost:7681
 203 denied deflate-stream extension
 204 handshake OK for protocol fraggle-protocol
 205 client connects to server
 206 EOM received 371913 correctly from 360 fragments
 207 EOM received 875970 correctly from 895 fragments
 208 EOM received 247140 correctly from 258 fragments
 209 EOM received 695451 correctly from 692 fragments
 210 ...
 211 ```
 212
 213 The fraggle test sends a random number up to 1024 fragmented websocket frames
 214 each of a random size between 1 and 2001 bytes in a single message, then sends
 215 a checksum and starts sending a new randomly sized and fragmented message.
 216
 217 The fraggle test client receives the same message fragments and computes the
 218 same checksum using websocket framing to see when the message has ended.  It
 219 then accepts the server checksum message and compares that to its checksum.
 220
 221
 222 proxy support
 223 -------------
 224
 225 The http_proxy environment variable is respected by the client
 226 connection code for both `ws://` and `wss://`.  It doesn't support
 227 authentication.
 228
 229 You use it like this
 230
 231 ```bash
 232 $ export http_proxy=myproxy.com:3128
 233 $ libwebsockets-test-client someserver.com
 234 ```
 235
 236
 237 debug logging
 238 -------------
 239
 240 By default logging of severity "notice", "warn" or "err" is enabled to stderr.
 241
 242 Again by default other logging is compiled in but disabled from printing.
 243
 244 If you want to eliminate the debug logging below notice  in severity, use the
 245 `--disable-debug` configure option to have it removed from the code by the
 246 preprocesser.
 247
 248 If you want to see more detailed debug logs, you can control a bitfield to
 249 select which logs types may print using the `lws_set_log_level()` api, in the
 250 test apps you can use `-d <number>` to control this.  The types of logging
 251 available are (OR together the numbers to select multiple)
 252
 253  - 1   ERR
 254  - 2   WARN
 255  - 4   NOTICE
 256  - 8   INFO
 257  - 16  DEBUG
 258  - 32  PARSER
 259  - 64  HEADER
 260  - 128 EXTENSION
 261  - 256 CLIENT
 262  - 512 LATENCY
 263
 264
 265 Websocket version supported
 266 ---------------------------
 267
 268 The final IETF standard is supported for both client and server, protocol
 269 version 13.
 270
 271
 272 Latency Tracking
 273 ----------------
 274
 275 Since libwebsockets runs using `poll()` and a single threaded approach, any
 276 unexpected latency coming from system calls would be bad news.  There's now
 277 a latency tracking scheme that can be built in with `--with-latency` at
 278 configure-time, logging the time taken for system calls to complete and if
 279 the whole action did complete that time or was deferred.
 280
 281 You can see the detailed data by enabling logging level 512 (eg, `-d 519` on
 282 the test server to see that and the usual logs), however even without that
 283 the "worst" latency is kept and reported to the logs with NOTICE severity
 284 when the context is destroyed.
 285
 286 Some care is needed interpreting them, if the action completed the first figure
 287 (in us) is the time taken for the whole action, which may have retried through
 288 the poll loop many times and will depend on network roundtrip times.  High
 289 figures here don't indicate a problem.  The figure in us reported after "lat"
 290 in the logging is the time taken by this particular attempt.  High figures
 291 here may indicate a problem, or if you system is loaded with another app at
 292 that time, such as the browser, it may simply indicate the OS gave preferential
 293 treatment to the other app during that call.
 294
 295
 296 Autobahn Test Suite
 297 -------------------
 298
 299 Lws can be tested against the autobahn websocket fuzzer.
 300
 301 1) pip install autobahntestsuite
 302
 303 2) wstest -m fuzzingserver
 304
 305 3) Run tests like this
 306
 307 libwebsockets-test-echo --client localhost --port 9001 -u "/runCase?case=20&agent=libwebsockets" -v -d 65535 -n 1
 308
 309 (this runs test 20)
 310
 311 4) In a browser, go here
 312
 313 http://localhost:8080/test_browser.html
 314
 315 fill in "libwebsockets" in "User Agent Identifier" and press "Update Reports (Manual)"
 316
 317 5) In a browser go to the directory you ran wstest in (eg, /projects/libwebsockets)
 318
 319 file:///projects/libwebsockets/reports/clients/index.html
 320
 321 to see the results
 322
 323
 324 Autobahn Test Notes
 325 -------------------
 326
 327 1) Autobahn tests the user code + lws implementation.  So to get the same
 328 results, you need to follow test-echo.c in terms of user implmentation.
 329
 330 2) Some of the tests make no sense for Libwebsockets to support and we fail them.
 331
 332  - Tests 2.10 + 2.11: sends multiple pings on one connection.  Lws policy is to
 333 only allow one active ping in flight on each connection, the rest are dropped.
 334 The autobahn test itself admits this is not part of the standard, just someone's
 335 random opinion about how they think a ws server should act.  So we will fail
 336 this by design and it is no problem about RFC6455 compliance.
 337
 338
 339