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 Forkless operation
  62 ------------------
  63
  64 If your target device does not offer fork(), you can use
  65 libwebsockets from your own main loop instead.  Use the
  66 configure option --nofork and simply call libwebsocket_service()
  67 from your own main loop as shown in the test app sources.
  68
  69
  70
  71
  72 Testing websocket client support
  73 --------------------------------
  74
  75 If you run the test server as described above, you can also
  76 connect to it using the test client as well as a browser.
  77
  78 $ libwebsockets-test-client localhost
  79
  80 will by default connect to the test server on localhost:7681
  81 and print the dumb increment number from the server at the
  82 same time as drawing random circles in the mirror protocol;
  83 if you connect to the test server using a browser at the
  84 same time you will be able to see the circles being drawn.
  85
  86
  87 Testing SSL on the client side
  88 ------------------------------
  89
  90 To test SSL/WSS client action, just run the client test with
  91
  92 $ libwebsockets-test-client localhost --ssl
  93
  94 By default the client test applet is set to accept selfsigned
  95 certificates used by the test server, this is indicated by the
  96 use_ssl var being set to 2.  Set it to 1 to reject any server
  97 certificate that it doesn't have a trusted CA cert for.
  98
  99
 100 Using the websocket ping utility
 101 --------------------------------
 102
 103 libwebsockets-test-ping connects as a client to a remote
 104 websocket server using 04 protocol and pings it like the
 105 normal unix ping utility.
 106
 107 $ libwebsockets-test-ping localhost
 108 handshake OK for protocol lws-mirror-protocol
 109 Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
 110 64 bytes from localhost: req=1 time=0.1ms
 111 64 bytes from localhost: req=2 time=0.1ms
 112 64 bytes from localhost: req=3 time=0.1ms
 113 64 bytes from localhost: req=4 time=0.2ms
 114 64 bytes from localhost: req=5 time=0.1ms
 115 64 bytes from localhost: req=6 time=0.2ms
 116 64 bytes from localhost: req=7 time=0.2ms
 117 64 bytes from localhost: req=8 time=0.1ms
 118 ^C
 119 --- localhost.localdomain websocket ping statistics ---
 120 8 packets transmitted, 8 received, 0% packet loss, time 7458ms
 121 rtt min/avg/max = 0.110/0.185/0.218 ms
 122 $
 123
 124 By default it sends 64 byte payload packets using the 04
 125 PING packet opcode type.  You can change the payload size
 126 using the -s= flag, up to a maximum of 125 mandated by the
 127 04 standard.
 128
 129 Using the lws-mirror protocol that is provided by the test
 130 server, libwebsockets-test-ping can also use larger payload
 131 sizes up to 4096 is BINARY packets; lws-mirror will copy
 132 them back to the client and they appear as a PONG.  Use the
 133 -m flag to select this operation.
 134
 135 The default interval between pings is 1s, you can use the -i=
 136 flag to set this, including fractions like -i=0.01 for 10ms
 137 interval.
 138
 139 Before you can even use the PING opcode that is part of the
 140 standard, you must complete a handshake with a specified
 141 protocol.  By default lws-mirror-protocol is used which is
 142 supported by the test server.  But if you are using it on
 143 another server, you can specify the protcol to handshake with
 144 by --protocol=protocolname
 145
 146
 147 Fraggle test app
 148 ----------------
 149
 150 By default it runs in server mode
 151
 152 $ libwebsockets-test-fraggle
 153 libwebsockets test fraggle
 154 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
 155  Compiled with SSL support, not using it
 156  Listening on port 7681
 157 server sees client connect
 158 accepted v06 connection
 159 Spamming 360 random fragments
 160 Spamming session over, len = 371913. sum = 0x2D3C0AE
 161 Spamming 895 random fragments
 162 Spamming session over, len = 875970. sum = 0x6A74DA1
 163 ...
 164
 165 You need to run a second session in client mode, you have to
 166 give the -c switch and the server address at least:
 167
 168 $ libwebsockets-test-fraggle -c localhost
 169 libwebsockets test fraggle
 170 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
 171  Client mode
 172 Connecting to localhost:7681
 173 denied deflate-stream extension
 174 handshake OK for protocol fraggle-protocol
 175 client connects to server
 176 EOM received 371913 correctly from 360 fragments
 177 EOM received 875970 correctly from 895 fragments
 178 EOM received 247140 correctly from 258 fragments
 179 EOM received 695451 correctly from 692 fragments
 180 ...
 181
 182 The fraggle test sends a random number up to 1024 fragmented websocket frames
 183 each of a random size between 1 and 2001 bytes in a single message, then sends
 184 a checksum and starts sending a new randomly sized and fragmented message.
 185
 186 The fraggle test client receives the same message fragments and computes the
 187 same checksum using websocket framing to see when the message has ended.  It
 188 then accepts the server checksum message and compares that to its checksum.
 189
 190
 191 proxy support
 192 -------------
 193
 194 The http_proxy environment variable is respected by the client
 195 connection code for both ws:// and wss://.  It doesn't support
 196 authentication.
 197
 198 You use it like this
 199
 200 export http_proxy=myproxy.com:3128
 201 libwebsockets-test-client someserver.com
 202
 203
 204 debug logging
 205 -------------
 206
 207 By default logging of severity "notice", "warn" or "err" is enabled to stderr.
 208
 209 Again by default other logging is comiled in but disabled from printing.
 210
 211 If you want to eliminate the debug logging below notice  in severity, use the
 212 --disable-debug configure option to have it removed from the code by the
 213 preprocesser.
 214
 215 If you want to see more detailed debug logs, you can control a bitfield to
 216 select which logs types may print using the lws_set_log_level() api, in the
 217 test apps you can use -d <number> to control this.  The types of logging
 218 available are (OR together the numbers to select multiple)
 219
 220  1   ERR
 221  2   WARN
 222  4   NOTICE
 223  8   INFO
 224  16  DEBUG
 225  32  PARSER
 226  64  HEADER
 227  128 EXTENSION
 228  256 CLIENT
 229
 230
 231 Websocket version supported
 232 ---------------------------
 233
 234 The final IETF standard is supported along with various older ones that will
 235 be removed at some point, -76, -04 and -05.
 236
 237