doc/html/md_README_8test-apps.html - platform/external/libwebsockets - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
 <meta name="generator" content="Doxygen 1.8.12"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
 <title>libwebsockets: Overview of lws test apps</title>
 <link href="tabs.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="jquery.js"></script>
 <script type="text/javascript" src="dynsections.js"></script>
 <link href="navtree.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="resize.js"></script>
 <script type="text/javascript" src="navtreedata.js"></script>
 <script type="text/javascript" src="navtree.js"></script>
 <script type="text/javascript">
   $(document).ready(initResizable);
 </script>
 <link href="doxygen.css" rel="stylesheet" type="text/css" />
 </head>
 <body>
 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
 <div id="titlearea">
 <table cellspacing="0" cellpadding="0">
  <tbody>
  <tr style="height: 56px;">
   <td id="projectlogo"><img alt="Logo" src="libwebsockets.org-logo.png"/></td>
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">libwebsockets
    </div>
    <div id="projectbrief">Lightweight C library for HTML5 websockets</div>
   </td>
  </tr>
  </tbody>
 </table>
 </div>
 <!-- end header part -->
 <!-- Generated by Doxygen 1.8.12 -->
 <script type="text/javascript" src="menudata.js"></script>
 <script type="text/javascript" src="menu.js"></script>
 <script type="text/javascript">
 $(function() {
   initMenu('',false,false,'search.php','Search');
 });
 </script>
 <div id="main-nav"></div>
 </div><!-- top -->
 <div id="side-nav" class="ui-resizable side-nav-resizable">
   <div id="nav-tree">
     <div id="nav-tree-contents">
       <div id="nav-sync" class="sync"></div>
     </div>
   </div>
   <div id="splitbar" style="-moz-user-select:none;"
        class="ui-resizable-handle">
   </div>
 </div>
 <script type="text/javascript">
 $(document).ready(function(){initNavTree('md_README_8test-apps.html','');});
 </script>
 <div id="doc-content">
 <div class="header">
   <div class="headertitle">
 <div class="title">Overview of lws test apps </div>  </div>
 </div><!--header-->
 <div class="contents">
 <div class="textblock"><p>Are you building a client? You just need to look at the test client <a href="test-server/test-client.c">libwebsockets-test-client</a>.</p>
 <p>If you are building a standalone server, there are three choices, in order of preferability.</p>
 <p>1) lwsws + protocol plugins</p>
 <p>Lws provides a generic web server app that can be configured with JSON config files. <a href="https://libwebsockets.org">https://libwebsockets.org</a> itself uses this method.</p>
 <p>With lwsws handling the serving part, you only need to write an lws protocol plugin. See [plugin-standalone](plugin-standalone) for an example of how to do that outside lws itself, using lws public apis.</p>
 <p>$ cmake .. -DLWS_WITH_LWSWS=1</p>
 <p>See <a class="el" href="md_README_8lwsws.html">README.lwsws.md</a> for information on how to configure lwsws.</p>
 <p>NOTE this method implies libuv is used by lws, to provide crossplatform implementations of timers, dynamic lib loading etc for plugins and lwsws.</p>
 <p>2) test-server-v2.0.c</p>
 <p>This method lets you configure web serving in code, instead of using lwsws.</p>
 <p>Plugins are still used, which implies libuv needed.</p>
 <p>$ cmake .. -DLWS_WITH_PLUGINS=1</p>
 <p>See <a href="test-server/test-server-v2.0.c">test-server-v2.0.c</a></p>
 <p>3) protocols in the server app</p>
 <p>This is the original way lws implemented servers, plugins and libuv are not required, but without plugins separating the protocol code directly, the combined code is all squidged together and is much less maintainable.</p>
 <p>This method is still supported in lws but all ongoing and future work is being done in protocol plugins only.</p>
 <h1>Notes about lws test apps </h1>
 <h1><a class="anchor" id="tsb"></a>
 Testing server with a browser</h1>
 <p>If you run <a href="test-server/test-server.c">libwebsockets-test-server</a> and point your browser (eg, Chrome) to </p><pre class="fragment">    http://127.0.0.1:7681
 </pre><p>It will fetch a script in the form of <code>test.html</code>, and then run the script in there on the browser to open a websocket connection. Incrementing numbers should appear in the browser display.</p>
 <p>By default the test server logs to both stderr and syslog, you can control what is logged using <code>-d &lt;log level&gt;</code>, see later.</p>
 <h1><a class="anchor" id="tsd"></a>
 Running test server as a Daemon</h1>
 <p>You can use the -D option on the test server to have it fork into the background and return immediately. In this daemonized mode all stderr is disabled and logging goes only to syslog, eg, <code>/var/log/messages</code> or similar.</p>
 <p>The server maintains a lockfile at <code>/tmp/.lwsts-lock</code> that contains the pid of the master process, and deletes this file when the master process terminates.</p>
 <p>To stop the daemon, do </p><div class="fragment"><div class="line">$ kill cat /tmp/.lwsts-lock </div></div><!-- fragment --><p> If it finds a stale lock (the pid mentioned in the file does not exist any more) it will delete the lock and create a new one during startup.</p>
 <p>If the lock is valid, the daemon will exit with a note on stderr that it was already running.</p>
 <h1><a class="anchor" id="sssl"></a>
 Using SSL on the server side</h1>
 <p>To test it using SSL/WSS, just run the test server with </p><div class="fragment"><div class="line">$ libwebsockets-test-server --ssl</div></div><!-- fragment --><p> and use the URL </p><div class="fragment"><div class="line">https://127.0.0.1:7681</div></div><!-- fragment --><p> The connection will be entirely encrypted using some generated certificates that your browser will not accept, since they are not signed by any real Certificate Authority. Just accept the certificates in the browser and the connection will proceed in first https and then websocket wss, acting exactly the same.</p>
 <p><a href="test-server/test-server.c">test-server.c</a> is all that is needed to use libwebsockets for serving both the script html over http and websockets.</p>
 <h1><a class="anchor" id="wscl"></a>
 Testing websocket client support</h1>
 <p>If you run the test server as described above, you can also connect to it using the test client as well as a browser.</p>
 <div class="fragment"><div class="line">$ libwebsockets-test-client localhost</div></div><!-- fragment --><p>will by default connect to the test server on localhost:7681 and print the dumb increment number from the server at the same time as drawing random circles in the mirror protocol; if you connect to the test server using a browser at the same time you will be able to see the circles being drawn.</p>
 <p>The test client supports SSL too, use</p>
 <div class="fragment"><div class="line">$ libwebsockets-test-client localhost --ssl -s</div></div><!-- fragment --><p>the -s tells it to accept the default self-signed cert from the server, otherwise it will strictly fail the connection if there is no CA cert to validate the server's certificate.</p>
 <h1><a class="anchor" id="choosingts"></a>
 Choosing between test server variations</h1>
 <p>If you will be doing standalone serving with lws, ideally you should avoid making your own server at all, and use lwsws with your own protocol plugins.</p>
 <p>The second best option is follow test-server-v2.0.c, which uses a mount to autoserve a directory, and lws protocol plugins for ws, without needing any user callback code (other than what's needed in the protocol plugin).</p>
 <p>For those two options libuv is needed to support the protocol plugins, if that's not possible then the other variations with their own protocol code should be considered.</p>
 <h1><a class="anchor" id="echo"></a>
 Testing simple echo</h1>
 <p>You can test against <code>echo.websockets.org</code> as a sanity test like this (the client connects to port <code>80</code> by default):</p>
 <div class="fragment"><div class="line">$ libwebsockets-test-echo --client echo.websocket.org</div></div><!-- fragment --><p>This echo test is of limited use though because it doesn't negotiate any protocol. You can run the same test app as a local server, by default on localhost:7681 </p><div class="fragment"><div class="line">$ libwebsockets-test-echo</div></div><!-- fragment --><p> and do the echo test against the local echo server </p><div class="fragment"><div class="line">$ libwebsockets-test-echo --client localhost --port 7681</div></div><!-- fragment --><p> If you add the <code>--ssl</code> switch to both the client and server, you can also test with an encrypted link.</p>
 <h1><a class="anchor" id="tassl"></a>
 Testing SSL on the client side</h1>
 <p>To test SSL/WSS client action, just run the client test with </p><div class="fragment"><div class="line">$ libwebsockets-test-client localhost --ssl</div></div><!-- fragment --><p> By default the client test applet is set to accept self-signed certificates used by the test server, this is indicated by the <code>use_ssl</code> var being set to <code>2</code>. Set it to <code>1</code> to reject any server certificate that it doesn't have a trusted CA cert for.</p>
 <h1><a class="anchor" id="taping"></a>
 Using the websocket ping utility</h1>
 <p>libwebsockets-test-ping connects as a client to a remote websocket server and pings it like the normal unix ping utility. </p><div class="fragment"><div class="line">$ libwebsockets-test-ping localhost</div><div class="line">handshake OK for protocol lws-mirror-protocol</div><div class="line">Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.</div><div class="line">64 bytes from localhost: req=1 time=0.1ms</div><div class="line">64 bytes from localhost: req=2 time=0.1ms</div><div class="line">64 bytes from localhost: req=3 time=0.1ms</div><div class="line">64 bytes from localhost: req=4 time=0.2ms</div><div class="line">64 bytes from localhost: req=5 time=0.1ms</div><div class="line">64 bytes from localhost: req=6 time=0.2ms</div><div class="line">64 bytes from localhost: req=7 time=0.2ms</div><div class="line">64 bytes from localhost: req=8 time=0.1ms</div><div class="line">^C</div><div class="line">--- localhost.localdomain websocket ping statistics ---</div><div class="line">8 packets transmitted, 8 received, 0% packet loss, time 7458ms</div><div class="line">rtt min/avg/max = 0.110/0.185/0.218 ms</div><div class="line">$</div></div><!-- fragment --><p> By default it sends 64 byte payload packets using the 04 PING packet opcode type. You can change the payload size using the <code>-s=</code> flag, up to a maximum of 125 mandated by the 04 standard.</p>
 <p>Using the lws-mirror protocol that is provided by the test server, libwebsockets-test-ping can also use larger payload sizes up to 4096 is BINARY packets; lws-mirror will copy them back to the client and they appear as a PONG. Use the <code>-m</code> flag to select this operation.</p>
 <p>The default interval between pings is 1s, you can use the -i= flag to set this, including fractions like <code>-i=0.01</code> for 10ms interval.</p>
 <p>Before you can even use the PING opcode that is part of the standard, you must complete a handshake with a specified protocol. By default lws-mirror-protocol is used which is supported by the test server. But if you are using it on another server, you can specify the protocol to handshake with by <code>--protocol=protocolname</code></p>
 <h1><a class="anchor" id="ta"></a>
 fraggle Fraggle test app</h1>
 <p>By default it runs in server mode </p><div class="fragment"><div class="line">$ libwebsockets-test-fraggle</div><div class="line">libwebsockets test fraggle</div><div class="line">(C) Copyright 2010-2011 Andy Green &lt;andy@warmcat.com&gt; licensed under LGPL2.1</div><div class="line"> Compiled with SSL support, not using it</div><div class="line"> Listening on port 7681</div><div class="line">server sees client connect</div><div class="line">accepted v06 connection</div><div class="line">Spamming 360 random fragments</div><div class="line">Spamming session over, len = 371913. sum = 0x2D3C0AE</div><div class="line">Spamming 895 random fragments</div><div class="line">Spamming session over, len = 875970. sum = 0x6A74DA1</div><div class="line">...</div></div><!-- fragment --><p> You need to run a second session in client mode, you have to give the <code>-c</code> switch and the server address at least: </p><div class="fragment"><div class="line">$ libwebsockets-test-fraggle -c localhost</div><div class="line">libwebsockets test fraggle</div><div class="line">(C) Copyright 2010-2011 Andy Green &lt;andy@warmcat.com&gt; licensed under LGPL2.1</div><div class="line"> Client mode</div><div class="line">Connecting to localhost:7681</div><div class="line">denied deflate-stream extension</div><div class="line">handshake OK for protocol fraggle-protocol</div><div class="line">client connects to server</div><div class="line">EOM received 371913 correctly from 360 fragments</div><div class="line">EOM received 875970 correctly from 895 fragments</div><div class="line">EOM received 247140 correctly from 258 fragments</div><div class="line">EOM received 695451 correctly from 692 fragments</div><div class="line">...</div></div><!-- fragment --><p> The fraggle test sends a random number up to 1024 fragmented websocket frames each of a random size between 1 and 2001 bytes in a single message, then sends a checksum and starts sending a new randomly sized and fragmented message.</p>
 <p>The fraggle test client receives the same message fragments and computes the same checksum using websocket framing to see when the message has ended. It then accepts the server checksum message and compares that to its checksum.</p>
 <h1><a class="anchor" id="taproxy"></a>
 proxy support</h1>
 <p>The http_proxy environment variable is respected by the client connection code for both <code>ws://</code> and <code>wss://</code>. It doesn't support authentication.</p>
 <p>You use it like this </p><div class="fragment"><div class="line">$ export http_proxy=myproxy.com:3128</div><div class="line">$ libwebsockets-test-client someserver.com</div></div><!-- fragment --><h1><a class="anchor" id="talog"></a>
 debug logging</h1>
 <p>By default logging of severity "notice", "warn" or "err" is enabled to stderr.</p>
 <p>Again by default other logging is compiled in but disabled from printing.</p>
 <p>By default debug logs below "notice" in severity are not compiled in. To get them included, add this option in CMAKE</p>
 <div class="fragment"><div class="line">$ cmake .. -DCMAKE_BUILD_TYPE=DEBUG</div></div><!-- fragment --><p>If you want to see more detailed debug logs, you can control a bitfield to select which logs types may print using the <code><a class="el" href="group__log.html#ga244647f9e1bf0097ccdde66d74f41e26">lws_set_log_level()</a></code> api, in the test apps you can use <code>-d &lt;number&gt;</code> to control this. The types of logging available are (OR together the numbers to select multiple)</p>
 <ul>
 <li>1 ERR</li>
 <li>2 WARN</li>
 <li>4 NOTICE</li>
 <li>8 INFO</li>
 <li>16 DEBUG</li>
 <li>32 PARSER</li>
 <li>64 HEADER</li>
 <li>128 EXTENSION</li>
 <li>256 CLIENT</li>
 <li>512 LATENCY</li>
 </ul>
 <h1><a class="anchor" id="ws13"></a>
 Websocket version supported</h1>
 <p>The final IETF standard is supported for both client and server, protocol version 13.</p>
 <h1><a class="anchor" id="latency"></a>
 Latency Tracking</h1>
 <p>Since libwebsockets runs using <code>poll()</code> and a single threaded approach, any unexpected latency coming from system calls would be bad news. There's now a latency tracking scheme that can be built in with <code>--with-latency</code> at configure-time, logging the time taken for system calls to complete and if the whole action did complete that time or was deferred.</p>
 <p>You can see the detailed data by enabling logging level 512 (eg, <code>-d 519</code> on the test server to see that and the usual logs), however even without that the "worst" latency is kept and reported to the logs with NOTICE severity when the context is destroyed.</p>
 <p>Some care is needed interpreting them, if the action completed the first figure (in us) is the time taken for the whole action, which may have retried through the poll loop many times and will depend on network roundtrip times. High figures here don't indicate a problem. The figure in us reported after "lat" in the logging is the time taken by this particular attempt. High figures here may indicate a problem, or if you system is loaded with another app at that time, such as the browser, it may simply indicate the OS gave preferential treatment to the other app during that call.</p>
 <h1><a class="anchor" id="autobahn"></a>
 Autobahn Test Suite</h1>
 <p>Lws can be tested against the autobahn websocket fuzzer.</p>
 <p>1) pip install autobahntestsuite</p>
 <p>2) wstest -m fuzzingserver</p>
 <p>3) Run tests like this</p>
 <p>libwebsockets-test-echo &ndash;client localhost &ndash;port 9001 -u "/runCase?case=20&amp;agent=libwebsockets" -v -d 65535 -n 1</p>
 <p>(this runs test 20)</p>
 <p>4) In a browser, go here</p>
 <p><a href="http://localhost:8080/test_browser.html">http://localhost:8080/test_browser.html</a></p>
 <p>fill in "libwebsockets" in "User Agent Identifier" and press "Update Reports (Manual)"</p>
 <p>5) In a browser go to the directory you ran wstest in (eg, /projects/libwebsockets)</p>
 <p><a href="file:///projects/libwebsockets/reports/clients/index.html">file:///projects/libwebsockets/reports/clients/index.html</a></p>
 <p>to see the results</p>
 <h1><a class="anchor" id="autobahnnotes"></a>
 Autobahn Test Notes</h1>
 <p>1) Autobahn tests the user code + lws implementation. So to get the same results, you need to follow test-echo.c in terms of user implementation.</p>
 <p>2) Two of the tests make no sense for Libwebsockets to support and we fail them.</p>
 <ul>
 <li>Tests 2.10 + 2.11: sends multiple pings on one connection. Lws policy is to only allow one active ping in flight on each connection, the rest are dropped. The autobahn test itself admits this is not part of the standard, just someone's random opinion about how they think a ws server should act. So we will fail this by design and it is no problem about RFC6455 compliance. </li>
 </ul>
 </div></div><!-- contents -->
 </div><!-- doc-content -->
 <!-- start footer part -->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     <li class="footer">Generated by
     <a href="http://www.doxygen.org/index.html">
     <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.12 </li>
   </ul>
 </div>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
	<meta http-equiv="X-UA-Compatible" content="IE=9"/>
	<meta name="generator" content="Doxygen 1.8.12"/>
	<meta name="viewport" content="width=device-width, initial-scale=1"/>
	<title>libwebsockets: Overview of lws test apps</title>
	<link href="tabs.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="jquery.js"></script>
	<script type="text/javascript" src="dynsections.js"></script>
	<link href="navtree.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="resize.js"></script>
	<script type="text/javascript" src="navtreedata.js"></script>
	<script type="text/javascript" src="navtree.js"></script>
	<script type="text/javascript">
	$(document).ready(initResizable);
	</script>
	<link href="doxygen.css" rel="stylesheet" type="text/css" />
	</head>
	<body>
	<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
	<div id="titlearea">
	<table cellspacing="0" cellpadding="0">
	<tbody>
	<tr style="height: 56px;">
	<td id="projectlogo"><img alt="Logo" src="libwebsockets.org-logo.png"/></td>
	<td id="projectalign" style="padding-left: 0.5em;">
	<div id="projectname">libwebsockets
	</div>
	<div id="projectbrief">Lightweight C library for HTML5 websockets</div>
	</td>
	</tr>
	</tbody>
	</table>
	</div>
	<!-- end header part -->
	<!-- Generated by Doxygen 1.8.12 -->
	<script type="text/javascript" src="menudata.js"></script>
	<script type="text/javascript" src="menu.js"></script>
	<script type="text/javascript">
	$(function() {
	initMenu('',false,false,'search.php','Search');
	});
	</script>
	<div id="main-nav"></div>
	</div><!-- top -->
	<div id="side-nav" class="ui-resizable side-nav-resizable">
	<div id="nav-tree">
	<div id="nav-tree-contents">
	<div id="nav-sync" class="sync"></div>
	</div>
	</div>
	<div id="splitbar" style="-moz-user-select:none;"
	class="ui-resizable-handle">
	</div>
	</div>
	<script type="text/javascript">
	$(document).ready(function(){initNavTree('md_README_8test-apps.html','');});
	</script>
	<div id="doc-content">
	<div class="header">
	<div class="headertitle">
	<div class="title">Overview of lws test apps </div> </div>
	</div><!--header-->
	<div class="contents">
	<div class="textblock"><p>Are you building a client? You just need to look at the test client <a href="test-server/test-client.c">libwebsockets-test-client</a>.</p>
	<p>If you are building a standalone server, there are three choices, in order of preferability.</p>
	<p>1) lwsws + protocol plugins</p>
	<p>Lws provides a generic web server app that can be configured with JSON config files. <a href="https://libwebsockets.org">https://libwebsockets.org</a> itself uses this method.</p>
	<p>With lwsws handling the serving part, you only need to write an lws protocol plugin. See [plugin-standalone](plugin-standalone) for an example of how to do that outside lws itself, using lws public apis.</p>
	<p>$ cmake .. -DLWS_WITH_LWSWS=1</p>
	<p>See <a class="el" href="md_README_8lwsws.html">README.lwsws.md</a> for information on how to configure lwsws.</p>
	<p>NOTE this method implies libuv is used by lws, to provide crossplatform implementations of timers, dynamic lib loading etc for plugins and lwsws.</p>
	<p>2) test-server-v2.0.c</p>
	<p>This method lets you configure web serving in code, instead of using lwsws.</p>
	<p>Plugins are still used, which implies libuv needed.</p>
	<p>$ cmake .. -DLWS_WITH_PLUGINS=1</p>
	<p>See <a href="test-server/test-server-v2.0.c">test-server-v2.0.c</a></p>
	<p>3) protocols in the server app</p>
	<p>This is the original way lws implemented servers, plugins and libuv are not required, but without plugins separating the protocol code directly, the combined code is all squidged together and is much less maintainable.</p>
	<p>This method is still supported in lws but all ongoing and future work is being done in protocol plugins only.</p>
	<h1>Notes about lws test apps </h1>
	<h1><a class="anchor" id="tsb"></a>
	Testing server with a browser</h1>
	<p>If you run <a href="test-server/test-server.c">libwebsockets-test-server</a> and point your browser (eg, Chrome) to </p><pre class="fragment"> http://127.0.0.1:7681
	</pre><p>It will fetch a script in the form of <code>test.html</code>, and then run the script in there on the browser to open a websocket connection. Incrementing numbers should appear in the browser display.</p>
	<p>By default the test server logs to both stderr and syslog, you can control what is logged using <code>-d <log level></code>, see later.</p>
	<h1><a class="anchor" id="tsd"></a>
	Running test server as a Daemon</h1>
	<p>You can use the -D option on the test server to have it fork into the background and return immediately. In this daemonized mode all stderr is disabled and logging goes only to syslog, eg, <code>/var/log/messages</code> or similar.</p>
	<p>The server maintains a lockfile at <code>/tmp/.lwsts-lock</code> that contains the pid of the master process, and deletes this file when the master process terminates.</p>
	<p>To stop the daemon, do </p><div class="fragment"><div class="line">$ kill cat /tmp/.lwsts-lock </div></div><!-- fragment --><p> If it finds a stale lock (the pid mentioned in the file does not exist any more) it will delete the lock and create a new one during startup.</p>
	<p>If the lock is valid, the daemon will exit with a note on stderr that it was already running.</p>
	<h1><a class="anchor" id="sssl"></a>
	Using SSL on the server side</h1>
	<p>To test it using SSL/WSS, just run the test server with </p><div class="fragment"><div class="line">$ libwebsockets-test-server --ssl</div></div><!-- fragment --><p> and use the URL </p><div class="fragment"><div class="line">https://127.0.0.1:7681</div></div><!-- fragment --><p> The connection will be entirely encrypted using some generated certificates that your browser will not accept, since they are not signed by any real Certificate Authority. Just accept the certificates in the browser and the connection will proceed in first https and then websocket wss, acting exactly the same.</p>
	<p><a href="test-server/test-server.c">test-server.c</a> is all that is needed to use libwebsockets for serving both the script html over http and websockets.</p>
	<h1><a class="anchor" id="wscl"></a>
	Testing websocket client support</h1>
	<p>If you run the test server as described above, you can also connect to it using the test client as well as a browser.</p>
	<div class="fragment"><div class="line">$ libwebsockets-test-client localhost</div></div><!-- fragment --><p>will by default connect to the test server on localhost:7681 and print the dumb increment number from the server at the same time as drawing random circles in the mirror protocol; if you connect to the test server using a browser at the same time you will be able to see the circles being drawn.</p>
	<p>The test client supports SSL too, use</p>
	<div class="fragment"><div class="line">$ libwebsockets-test-client localhost --ssl -s</div></div><!-- fragment --><p>the -s tells it to accept the default self-signed cert from the server, otherwise it will strictly fail the connection if there is no CA cert to validate the server's certificate.</p>
	<h1><a class="anchor" id="choosingts"></a>
	Choosing between test server variations</h1>
	<p>If you will be doing standalone serving with lws, ideally you should avoid making your own server at all, and use lwsws with your own protocol plugins.</p>
	<p>The second best option is follow test-server-v2.0.c, which uses a mount to autoserve a directory, and lws protocol plugins for ws, without needing any user callback code (other than what's needed in the protocol plugin).</p>
	<p>For those two options libuv is needed to support the protocol plugins, if that's not possible then the other variations with their own protocol code should be considered.</p>
	<h1><a class="anchor" id="echo"></a>
	Testing simple echo</h1>
	<p>You can test against <code>echo.websockets.org</code> as a sanity test like this (the client connects to port <code>80</code> by default):</p>
	<div class="fragment"><div class="line">$ libwebsockets-test-echo --client echo.websocket.org</div></div><!-- fragment --><p>This echo test is of limited use though because it doesn't negotiate any protocol. You can run the same test app as a local server, by default on localhost:7681 </p><div class="fragment"><div class="line">$ libwebsockets-test-echo</div></div><!-- fragment --><p> and do the echo test against the local echo server </p><div class="fragment"><div class="line">$ libwebsockets-test-echo --client localhost --port 7681</div></div><!-- fragment --><p> If you add the <code>--ssl</code> switch to both the client and server, you can also test with an encrypted link.</p>
	<h1><a class="anchor" id="tassl"></a>
	Testing SSL on the client side</h1>
	<p>To test SSL/WSS client action, just run the client test with </p><div class="fragment"><div class="line">$ libwebsockets-test-client localhost --ssl</div></div><!-- fragment --><p> By default the client test applet is set to accept self-signed certificates used by the test server, this is indicated by the <code>use_ssl</code> var being set to <code>2</code>. Set it to <code>1</code> to reject any server certificate that it doesn't have a trusted CA cert for.</p>
	<h1><a class="anchor" id="taping"></a>
	Using the websocket ping utility</h1>
	<p>libwebsockets-test-ping connects as a client to a remote websocket server and pings it like the normal unix ping utility. </p><div class="fragment"><div class="line">$ libwebsockets-test-ping localhost</div><div class="line">handshake OK for protocol lws-mirror-protocol</div><div class="line">Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.</div><div class="line">64 bytes from localhost: req=1 time=0.1ms</div><div class="line">64 bytes from localhost: req=2 time=0.1ms</div><div class="line">64 bytes from localhost: req=3 time=0.1ms</div><div class="line">64 bytes from localhost: req=4 time=0.2ms</div><div class="line">64 bytes from localhost: req=5 time=0.1ms</div><div class="line">64 bytes from localhost: req=6 time=0.2ms</div><div class="line">64 bytes from localhost: req=7 time=0.2ms</div><div class="line">64 bytes from localhost: req=8 time=0.1ms</div><div class="line">^C</div><div class="line">--- localhost.localdomain websocket ping statistics ---</div><div class="line">8 packets transmitted, 8 received, 0% packet loss, time 7458ms</div><div class="line">rtt min/avg/max = 0.110/0.185/0.218 ms</div><div class="line">$</div></div><!-- fragment --><p> By default it sends 64 byte payload packets using the 04 PING packet opcode type. You can change the payload size using the <code>-s=</code> flag, up to a maximum of 125 mandated by the 04 standard.</p>
	<p>Using the lws-mirror protocol that is provided by the test server, libwebsockets-test-ping can also use larger payload sizes up to 4096 is BINARY packets; lws-mirror will copy them back to the client and they appear as a PONG. Use the <code>-m</code> flag to select this operation.</p>
	<p>The default interval between pings is 1s, you can use the -i= flag to set this, including fractions like <code>-i=0.01</code> for 10ms interval.</p>
	<p>Before you can even use the PING opcode that is part of the standard, you must complete a handshake with a specified protocol. By default lws-mirror-protocol is used which is supported by the test server. But if you are using it on another server, you can specify the protocol to handshake with by <code>--protocol=protocolname</code></p>
	<h1><a class="anchor" id="ta"></a>
	fraggle Fraggle test app</h1>
	<p>By default it runs in server mode </p><div class="fragment"><div class="line">$ libwebsockets-test-fraggle</div><div class="line">libwebsockets test fraggle</div><div class="line">(C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1</div><div class="line"> Compiled with SSL support, not using it</div><div class="line"> Listening on port 7681</div><div class="line">server sees client connect</div><div class="line">accepted v06 connection</div><div class="line">Spamming 360 random fragments</div><div class="line">Spamming session over, len = 371913. sum = 0x2D3C0AE</div><div class="line">Spamming 895 random fragments</div><div class="line">Spamming session over, len = 875970. sum = 0x6A74DA1</div><div class="line">...</div></div><!-- fragment --><p> You need to run a second session in client mode, you have to give the <code>-c</code> switch and the server address at least: </p><div class="fragment"><div class="line">$ libwebsockets-test-fraggle -c localhost</div><div class="line">libwebsockets test fraggle</div><div class="line">(C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1</div><div class="line"> Client mode</div><div class="line">Connecting to localhost:7681</div><div class="line">denied deflate-stream extension</div><div class="line">handshake OK for protocol fraggle-protocol</div><div class="line">client connects to server</div><div class="line">EOM received 371913 correctly from 360 fragments</div><div class="line">EOM received 875970 correctly from 895 fragments</div><div class="line">EOM received 247140 correctly from 258 fragments</div><div class="line">EOM received 695451 correctly from 692 fragments</div><div class="line">...</div></div><!-- fragment --><p> The fraggle test sends a random number up to 1024 fragmented websocket frames each of a random size between 1 and 2001 bytes in a single message, then sends a checksum and starts sending a new randomly sized and fragmented message.</p>
	<p>The fraggle test client receives the same message fragments and computes the same checksum using websocket framing to see when the message has ended. It then accepts the server checksum message and compares that to its checksum.</p>
	<h1><a class="anchor" id="taproxy"></a>
	proxy support</h1>
	<p>The http_proxy environment variable is respected by the client connection code for both <code>ws://</code> and <code>wss://</code>. It doesn't support authentication.</p>
	<p>You use it like this </p><div class="fragment"><div class="line">$ export http_proxy=myproxy.com:3128</div><div class="line">$ libwebsockets-test-client someserver.com</div></div><!-- fragment --><h1><a class="anchor" id="talog"></a>
	debug logging</h1>
	<p>By default logging of severity "notice", "warn" or "err" is enabled to stderr.</p>
	<p>Again by default other logging is compiled in but disabled from printing.</p>
	<p>By default debug logs below "notice" in severity are not compiled in. To get them included, add this option in CMAKE</p>
	<div class="fragment"><div class="line">$ cmake .. -DCMAKE_BUILD_TYPE=DEBUG</div></div><!-- fragment --><p>If you want to see more detailed debug logs, you can control a bitfield to select which logs types may print using the <code><a class="el" href="group__log.html#ga244647f9e1bf0097ccdde66d74f41e26">lws_set_log_level()</a></code> api, in the test apps you can use <code>-d <number></code> to control this. The types of logging available are (OR together the numbers to select multiple)</p>
	<ul>
	<li>1 ERR</li>
	<li>2 WARN</li>
	<li>4 NOTICE</li>
	<li>8 INFO</li>
	<li>16 DEBUG</li>
	<li>32 PARSER</li>
	<li>64 HEADER</li>
	<li>128 EXTENSION</li>
	<li>256 CLIENT</li>
	<li>512 LATENCY</li>
	</ul>
	<h1><a class="anchor" id="ws13"></a>
	Websocket version supported</h1>
	<p>The final IETF standard is supported for both client and server, protocol version 13.</p>
	<h1><a class="anchor" id="latency"></a>
	Latency Tracking</h1>
	<p>Since libwebsockets runs using <code>poll()</code> and a single threaded approach, any unexpected latency coming from system calls would be bad news. There's now a latency tracking scheme that can be built in with <code>--with-latency</code> at configure-time, logging the time taken for system calls to complete and if the whole action did complete that time or was deferred.</p>
	<p>You can see the detailed data by enabling logging level 512 (eg, <code>-d 519</code> on the test server to see that and the usual logs), however even without that the "worst" latency is kept and reported to the logs with NOTICE severity when the context is destroyed.</p>
	<p>Some care is needed interpreting them, if the action completed the first figure (in us) is the time taken for the whole action, which may have retried through the poll loop many times and will depend on network roundtrip times. High figures here don't indicate a problem. The figure in us reported after "lat" in the logging is the time taken by this particular attempt. High figures here may indicate a problem, or if you system is loaded with another app at that time, such as the browser, it may simply indicate the OS gave preferential treatment to the other app during that call.</p>
	<h1><a class="anchor" id="autobahn"></a>
	Autobahn Test Suite</h1>
	<p>Lws can be tested against the autobahn websocket fuzzer.</p>
	<p>1) pip install autobahntestsuite</p>
	<p>2) wstest -m fuzzingserver</p>
	<p>3) Run tests like this</p>
	<p>libwebsockets-test-echo –client localhost –port 9001 -u "/runCase?case=20&agent=libwebsockets" -v -d 65535 -n 1</p>
	<p>(this runs test 20)</p>
	<p>4) In a browser, go here</p>
	<p><a href="http://localhost:8080/test_browser.html">http://localhost:8080/test_browser.html</a></p>
	<p>fill in "libwebsockets" in "User Agent Identifier" and press "Update Reports (Manual)"</p>
	<p>5) In a browser go to the directory you ran wstest in (eg, /projects/libwebsockets)</p>
	<p><a href="file:///projects/libwebsockets/reports/clients/index.html">file:///projects/libwebsockets/reports/clients/index.html</a></p>
	<p>to see the results</p>
	<h1><a class="anchor" id="autobahnnotes"></a>
	Autobahn Test Notes</h1>
	<p>1) Autobahn tests the user code + lws implementation. So to get the same results, you need to follow test-echo.c in terms of user implementation.</p>
	<p>2) Two of the tests make no sense for Libwebsockets to support and we fail them.</p>
	<ul>
	<li>Tests 2.10 + 2.11: sends multiple pings on one connection. Lws policy is to only allow one active ping in flight on each connection, the rest are dropped. The autobahn test itself admits this is not part of the standard, just someone's random opinion about how they think a ws server should act. So we will fail this by design and it is no problem about RFC6455 compliance. </li>
	</ul>
	</div></div><!-- contents -->
	</div><!-- doc-content -->
	<!-- start footer part -->
	<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
	<ul>
	<li class="footer">Generated by
	<a href="http://www.doxygen.org/index.html">
	<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.12 </li>
	</ul>
	</div>
	</body>
	</html>