test-suite.html 9.7 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98
<!-- HTML header for doxygen 1.8.8-->
<!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="X-UA-Compatible" content="IE=edge">
        <!-- For Mobile Devices -->
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
        <meta name="generator" content="Doxygen 1.8.13"/>
        <script type="text/javascript" src="https://code.jquery.com/jquery-2.1.1.min.js"></script>
        <title>libinput: libinput test suite</title>
        <!--<link href="tabs.css" rel="stylesheet" type="text/css"/>-->
        <script type="text/javascript" src="dynsections.js"></script>
        <script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    extensions: ["tex2jax.js"],
    jax: ["input/TeX","output/HTML-CSS"],
});
</script><script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>
        <link href="doxygen.css" rel="stylesheet" type="text/css" />
        <link href="bootstrap.css" rel="stylesheet" type="text/css"/>
<link href="customdoxygen.css" rel="stylesheet" type="text/css"/>
<link href="libinputdoxygen.css" rel="stylesheet" type="text/css"/>
        <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.1/js/bootstrap.min.js"></script>
        <script type="text/javascript" src="doxy-boot.js"></script>
    </head>
    <body>
        <nav class="navbar navbar-default" role="navigation">
            <div class="container">
                <div class="navbar-header">
                    <a class="navbar-brand">libinput 1.10.7</a>
                </div>
            </div>
        </nav>
        <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
            <div class="content" id="content">
                <div class="container">
                    <div class="row">
                        <div class="col-sm-12 panel panel-default" style="padding-bottom: 15px;">
                            <div style="margin-bottom: 15px;">
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<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 id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="developers.html">Developers</a></li>  </ul>
</div>
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">libinput test suite </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>libinput ships with a number of tests all run automatically on <code>ninja test</code>.</p>
<p>The primary test suite is the <code>libinput-test-suite-runner</code>. When testing, the <code>libinput-test-suite-runner</code> should always be invoked to check for behavior changes.</p>
<p>The test suite runner uses <a href="http://check.sourceforge.net/doc/check_html/">Check</a> underneath the hood but most of the functionality is abstracted into <em>litest</em> wrappers.</p>
<p>The test suite runner has a make-like job control enabled by the <code>-j</code> or <code>--jobs</code> flag and will fork off as many parallel processes as given by this flag. The default if unspecified is 8. When debugging a specific test case failure it is recommended to employ test filtures (see <a class="el" href="test-suite.html#test-filtering">Selective running of tests</a>) and disable parallel tests. The test suite automatically disables parallel make when run in gdb.</p>
<h1><a class="anchor" id="test-config"></a>
X.Org config to avoid interference</h1>
<p>uinput devices created by the test suite are usually recognised by X as input devices. All events sent through these devices will generate X events and interfere with your desktop.</p>
<p>Copy the file <code>$srcdir/test/50-litest.conf</code> into your <code>/etc/X11/xorg.conf.d</code> and restart X. This will ignore any litest devices and thus not interfere with your desktop.</p>
<h1><a class="anchor" id="test-root"></a>
Permissions required to run tests</h1>
<p>Most tests require the creation of uinput devices and access to the resulting <code>/dev/input/eventX</code> nodes. Some tests require temporary udev rules. <b>This usually requires the tests to be run as root</b>. If not run as root, the test suite runner will exit with status 77, interpreted as "skipped" by ninja.</p>
<h1><a class="anchor" id="test-filtering"></a>
Selective running of tests</h1>
<p>litest's tests are grouped into test groups, test names and devices. A test group is e.g. "touchpad:tap" and incorporates all tapping-related tests for touchpads. Each test function is (usually) run with one or more specific devices. The <code>--list</code> commandline argument shows the list of suites and tests. This is useful when trying to figure out if a specific test is run for a device.</p>
<div class="fragment"><div class="line">$ ./test/libinput-test-suite-runner --list</div><div class="line">...</div><div class="line">pointer:left-handed:</div><div class="line">        pointer_left_handed_during_click_multiple_buttons:</div><div class="line">                trackpoint</div><div class="line">                ms-surface-cover</div><div class="line">                mouse-wheelclickcount</div><div class="line">                mouse-wheelclickangle</div><div class="line">                low-dpi-mouse</div><div class="line">                mouse-roccat</div><div class="line">                mouse-wheel-tilt</div><div class="line">                mouse</div><div class="line">                logitech-trackball</div><div class="line">                cyborg-rat</div><div class="line">                magicmouse</div><div class="line">        pointer_left_handed_during_click:</div><div class="line">                trackpoint</div><div class="line">                ms-surface-cover</div><div class="line">                mouse-wheelclickcount</div><div class="line">                mouse-wheelclickangle</div><div class="line">                low-dpi-mouse</div><div class="line">                mouse-roccat</div><div class="line">                mouse-wheel-tilt</div><div class="line">                mouse</div><div class="line">                logitech-trackball</div><div class="line">                cyborg-rat</div><div class="line">                litest-magicmouse-device</div><div class="line">        pointer_left_handed:</div><div class="line">                trackpoint</div><div class="line">                ms-surface-cover</div><div class="line">                mouse-wheelclickcount</div><div class="line">                mouse-wheelclickangle</div><div class="line">                low-dpi-mouse</div><div class="line">                mouse-roccat</div><div class="line">                mouse-wheel-tilt</div><div class="line">                mouse</div><div class="line">...</div></div><!-- fragment --><p>In the above example, the "pointer:left-handed" suite contains multiple tests, e.g. "pointer_left_handed_during_click" (this is also the function name of the test, making it easy to grep for). This particular test is run for various devices including the trackpoint device and the magic mouse device.</p>
<p>The "no device" entry signals that litest does not instantiate a uinput device for a specific test (though the test itself may instantiate one).</p>
<p>The <code>--filter-test</code> argument enables selective running of tests through basic shell-style function name matching. For example:</p>
<div class="fragment"><div class="line">$ ./test/libinput-test-suite-runner --filter-test=<span class="stringliteral">&quot;*1fg_tap*&quot;</span></div></div><!-- fragment --><p>The <code>--filter-device</code> argument enables selective running of tests through basic shell-style device name matching. The device names matched are the litest-specific shortnames, see the output of <code>--list</code>. For example:</p>
<div class="fragment"><div class="line">$ ./test/libinput-test-suite-runner --filter-device=<span class="stringliteral">&quot;synaptics*&quot;</span></div></div><!-- fragment --><p>The <code>--filter-group</code> argument enables selective running of test groups through basic shell-style test group matching. The test groups matched are litest-specific test groups, see the output of <code>--list</code>. For example:</p>
<div class="fragment"><div class="line">$ ./test/libinput-test-suite-runner --filter-group=<span class="stringliteral">&quot;touchpad:*hover*&quot;</span></div></div><!-- fragment --><p>The <code>--filter-device</code> and <code>--filter-group</code> arguments can be combined with <code>--list</code> to show which groups and devices will be affected.</p>
<h1><a class="anchor" id="test-verbosity"></a>
Controlling test output</h1>
<p>Each test supports the <code>--verbose</code> commandline option to enable debugging output, see <a class="el" href="group__base.html#ga75a500c54c61cfcecd4c76dbb8022933" title="Set the log priority for the libinput context. ">libinput_log_set_priority()</a> for details. The <code>LITEST_VERBOSE</code> environment variable, if set, also enables verbose mode.</p>
<div class="fragment"><div class="line">$ ./test/libinput-test-suite-runner --verbose</div><div class="line">$ LITEST_VERBOSE=1 ninja test</div></div><!-- fragment --> </div></div><!-- contents -->
<!-- HTML footer for doxygen 1.8.8-->
<!-- start footer part -->
</div>
</div>
</div>
</div>
</div>
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>