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