README.test-apps

   1 Testing server with a browser
   2 -----------------------------
   3
   4 If you run libwebsockets-test-server 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   kill `cat /tmp/.lwsts-lock`
  31
  32 If it finds a stale lock (the pid mentioned in the file does not exist
  33 any more) it will delete the lock and create a new one during startup.
  34
  35 If the lock is valid, the daemon will exit with a note on stderr that
  36 it was already running.s
  37
  38
  39 Using SSL on the server side
  40 ----------------------------
  41
  42 To test it using SSL/WSS, just run the test server with
  43
  44 $ libwebsockets-test-server --ssl
  45
  46 and use the URL
  47
  48   https://127.0.0.1:7681
  49
  50 The connection will be entirely encrypted using some generated
  51 certificates that your browser will not accept, since they are
  52 not signed by any real Certificate Authority.  Just accept the
  53 certificates in the browser and the connection will proceed
  54 in first https and then websocket wss, acting exactly the
  55 same.
  56
  57 test-server.c is all that is needed to use libwebsockets for
  58 serving both the script html over http and websockets.
  59
  60
  61 Testing websocket client support
  62 --------------------------------
  63
  64 If you run the test server as described above, you can also
  65 connect to it using the test client as well as a browser.
  66
  67 $ libwebsockets-test-client localhost
  68
  69 will by default connect to the test server on localhost:7681
  70 and print the dumb increment number from the server at the
  71 same time as drawing random circles in the mirror protocol;
  72 if you connect to the test server using a browser at the
  73 same time you will be able to see the circles being drawn.
  74
  75
  76 Testing simple echo
  77 -------------------
  78
  79 You can test against echo.websockets.org as a sanity test like
  80 this (the client connects to port 80 by default):
  81
  82 $ libwebsockets-test-echo --client echo.websocket.org
  83
  84 This echo test is of limited use though because it doesn't
  85 negotiate any protocol.  You can run the same test app as a
  86 local server, by default on localhost:7681
  87
  88 $ libwebsockets-test-echo
  89
  90 and do the echo test against the local echo server
  91
  92 $ libwebsockets-test-echo --client localhost --port 7681
  93
  94 If you add the --ssl switch to both the client and server, you can also test
  95 with an encrypted link.
  96
  97
  98 Testing SSL on the client side
  99 ------------------------------
 100
 101 To test SSL/WSS client action, just run the client test with
 102
 103 $ libwebsockets-test-client localhost --ssl
 104
 105 By default the client test applet is set to accept selfsigned
 106 certificates used by the test server, this is indicated by the
 107 use_ssl var being set to 2.  Set it to 1 to reject any server
 108 certificate that it doesn't have a trusted CA cert for.
 109
 110
 111 Using the websocket ping utility
 112 --------------------------------
 113
 114 libwebsockets-test-ping connects as a client to a remote
 115 websocket server using 04 protocol and pings it like the
 116 normal unix ping utility.
 117
 118 $ libwebsockets-test-ping localhost
 119 handshake OK for protocol lws-mirror-protocol
 120 Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
 121 64 bytes from localhost: req=1 time=0.1ms
 122 64 bytes from localhost: req=2 time=0.1ms
 123 64 bytes from localhost: req=3 time=0.1ms
 124 64 bytes from localhost: req=4 time=0.2ms
 125 64 bytes from localhost: req=5 time=0.1ms
 126 64 bytes from localhost: req=6 time=0.2ms
 127 64 bytes from localhost: req=7 time=0.2ms
 128 64 bytes from localhost: req=8 time=0.1ms
 129 ^C
 130 --- localhost.localdomain websocket ping statistics ---
 131 8 packets transmitted, 8 received, 0% packet loss, time 7458ms
 132 rtt min/avg/max = 0.110/0.185/0.218 ms
 133 $
 134
 135 By default it sends 64 byte payload packets using the 04
 136 PING packet opcode type.  You can change the payload size
 137 using the -s= flag, up to a maximum of 125 mandated by the
 138 04 standard.
 139
 140 Using the lws-mirror protocol that is provided by the test
 141 server, libwebsockets-test-ping can also use larger payload
 142 sizes up to 4096 is BINARY packets; lws-mirror will copy
 143 them back to the client and they appear as a PONG.  Use the
 144 -m flag to select this operation.
 145
 146 The default interval between pings is 1s, you can use the -i=
 147 flag to set this, including fractions like -i=0.01 for 10ms
 148 interval.
 149
 150 Before you can even use the PING opcode that is part of the
 151 standard, you must complete a handshake with a specified
 152 protocol.  By default lws-mirror-protocol is used which is
 153 supported by the test server.  But if you are using it on
 154 another server, you can specify the protcol to handshake with
 155 by --protocol=protocolname
 156
 157
 158 Fraggle test app
 159 ----------------
 160
 161 By default it runs in server mode
 162
 163 $ libwebsockets-test-fraggle
 164 libwebsockets test fraggle
 165 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
 166  Compiled with SSL support, not using it
 167  Listening on port 7681
 168 server sees client connect
 169 accepted v06 connection
 170 Spamming 360 random fragments
 171 Spamming session over, len = 371913. sum = 0x2D3C0AE
 172 Spamming 895 random fragments
 173 Spamming session over, len = 875970. sum = 0x6A74DA1
 174 ...
 175
 176 You need to run a second session in client mode, you have to
 177 give the -c switch and the server address at least:
 178
 179 $ libwebsockets-test-fraggle -c localhost
 180 libwebsockets test fraggle
 181 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
 182  Client mode
 183 Connecting to localhost:7681
 184 denied deflate-stream extension
 185 handshake OK for protocol fraggle-protocol
 186 client connects to server
 187 EOM received 371913 correctly from 360 fragments
 188 EOM received 875970 correctly from 895 fragments
 189 EOM received 247140 correctly from 258 fragments
 190 EOM received 695451 correctly from 692 fragments
 191 ...
 192
 193 The fraggle test sends a random number up to 1024 fragmented websocket frames
 194 each of a random size between 1 and 2001 bytes in a single message, then sends
 195 a checksum and starts sending a new randomly sized and fragmented message.
 196
 197 The fraggle test client receives the same message fragments and computes the
 198 same checksum using websocket framing to see when the message has ended.  It
 199 then accepts the server checksum message and compares that to its checksum.
 200
 201
 202 proxy support
 203 -------------
 204
 205 The http_proxy environment variable is respected by the client
 206 connection code for both ws:// and wss://.  It doesn't support
 207 authentication.
 208
 209 You use it like this
 210
 211 export http_proxy=myproxy.com:3128
 212 libwebsockets-test-client someserver.com
 213
 214
 215 debug logging
 216 -------------
 217
 218 By default logging of severity "notice", "warn" or "err" is enabled to stderr.
 219
 220 Again by default other logging is comiled in but disabled from printing.
 221
 222 If you want to eliminate the debug logging below notice  in severity, use the
 223 --disable-debug configure option to have it removed from the code by the
 224 preprocesser.
 225
 226 If you want to see more detailed debug logs, you can control a bitfield to
 227 select which logs types may print using the lws_set_log_level() api, in the
 228 test apps you can use -d <number> to control this.  The types of logging
 229 available are (OR together the numbers to select multiple)
 230
 231  1   ERR
 232  2   WARN
 233  4   NOTICE
 234  8   INFO
 235  16  DEBUG
 236  32  PARSER
 237  64  HEADER
 238  128 EXTENSION
 239  256 CLIENT
 240  512 LATENCY
 241
 242
 243 Websocket version supported
 244 ---------------------------
 245
 246 The final IETF standard is supported for both client and server, protocol
 247 version 13.
 248
 249
 250 Latency Tracking
 251 ----------------
 252
 253 Since libwebsockets runs using poll() and a single threaded approach, any
 254 unexpected latency coming from system calls would be bad news.  There's now
 255 a latency tracking scheme that can be built in with --with-latency at
 256 configure-time, logging the time taken for system calls to complete and if
 257 the whole action did complete that time or was deferred.
 258
 259 You can see the detailed data by enabling logging level 512 (eg, -d 519 on
 260 the test server to see that and the usual logs), however even without that
 261 the "worst" latency is kept and reported to the logs with NOTICE severity
 262 when the context is destroyed.
 263
 264 Some care is needed interpreting them, if the action completed the first figure
 265 (in us) is the time taken for the whole action, which may have retried through
 266 the poll loop many times and will depend on network roundtrip times.  High
 267 figures here don't indicate a problem.  The figure in us reported after "lat"
 268 in the logging is the time taken by this particular attempt.  High figures
 269 here may indicate a problem, or if you system is loaded with another app at
 270 that time, such as the browser, it may simply indicate the OS gave preferential
 271 treatment to the other app during that call.
 272