tests/hwsim/README

   1 Automated hostapd/wpa_supplicant testing with mac80211_hwsim
   2 ------------------------------------------------------------
   3
   4 This directory contains testing infrastructure and test cases to run
   5 automated tests of full hostapd and wpa_supplicant functionality. This
   6 testing is done with the help of mac80211_hwsim which is Linux kernel
   7 driver that simulates IEEE 802.11 radios without requiring any
   8 additional hardware. This setup most of the hostapd and wpa_supplicant
   9 functionality (and large parts of the Linux cfg80211 and mac80211
  10 functionality for that matter) to be tested.
  11
  12 mac80211_hwsim is loaded with five simulated radios to allow different
  13 device combinations to be tested. wlantest is used analyze raw packets
  14 captured through the hwsim0 monitor interface that capture all frames
  15 sent on all channels. tcpdump is used to store the frames for
  16 analysis. Three wpa_supplicant processed are used to control three
  17 virtual radios and one hostapd process is used to dynamically control
  18 the other two virtual radios. hwsim_test is used to verify that data
  19 connection (both unicast and broadcast) works between two netdevs.
  20
  21 The python scripts and tools in this directory control test case
  22 execution. They interact wpa_supplicant and hostapd through control
  23 interfaces to perform the operations. In addition, wlantest_cli and
  24 hwsim_test are used to verify that operations have been performed
  25 correctly and that the network connection works in the expected way.
  26
  27 These test cases are run automatically against the hostap.git commits
  28 for regression testing and to help in keeping the hostap.git master
  29 branch in stable state. Results from these tests are available here:
  30 http://buildbot.w1.fi:8010/waterfall
  31
  32
  33 Building binaries for testing
  34 -----------------------------
  35
  36 You will need to build (or use already built) components to be
  37 tested. These are available in the hostap.git repository and can be
  38 built for example as follows:
  39
  40 cd ../../wpa_supplicant
  41 cp ../tests/hwsim/example-wpa_supplicant.config .config
  42 make clean
  43 make
  44 cd ../hostapd
  45 cp ../tests/hwsim/example-hostapd.config .config
  46 make clean
  47 make hostapd hlr_auc_gw
  48 cd ../wlantest
  49 make clean
  50 make
  51 cd ../mac80211_hwsim/tools
  52 make
  53
  54 The test scripts can find the binaries in the locations where they were
  55 built. It is also possible to install hwsim_test and wlantest_cli
  56 somewhat on the path to use pre-built tools.
  57
  58
  59 wpaspy
  60 ------
  61
  62 The python scripts use wpaspy.py to interact with the wpa_supplicant
  63 control interface, but the run-tests.py script adds the (relative)
  64 path into the environment so it doesn't need to be installed.
  65
  66
  67 mac80211_hwsim
  68 --------------
  69
  70 mac80211_hwsim kernel module is available from the upstream Linux
  71 kernel. Some Linux distributions enable it by default. If that's not the
  72 case, you can either enable it in the kernel configuration
  73 (CONFIG_MAC80211_HWSIM=m) and rebuild your kernel or use Backports with
  74 CPTCFG_MAC80211_HWSIM=m to replace the wireless LAN components in the
  75 base kernel.
  76
  77
  78 sudo
  79 ----
  80
  81 Some parts of the testing process requires root privileges. The test
  82 scripts are currently using sudo to achieve this. To be able to run the
  83 tests, you'll probably want to enable sudo with a timeout to not expire
  84 password entry very quickly. For example, use this in the sudoers file:
  85
  86 Defaults        env_reset,timestamp_timeout=180
  87
  88 Or on a dedicated test system, you could even disable password prompting
  89 with this in sudoers:
  90
  91 %sudo   ALL=NOPASSWD: ALL
  92
  93
  94 Other network interfaces
  95 ------------------------
  96
  97 Some of the test scripts are still using hardcoded interface names, so
  98 the easiest way of making things work is to avoid using other network
  99 devices that may use conflicting interface names. For example, unload
 100 any wireless LAN driver before running the tests and make sure that
 101 wlan0..4 gets assigned as the interface names for the mac80211_hwsim
 102 radios. It may also be possible to rename the interface expectations in
 103 run-tests.py to allow other names to be used.
 104
 105
 106 Running tests
 107 -------------
 108
 109 Simplest way to run a full set of the test cases is by running
 110 run-all.sh in tests/hwsim directory. This will use start.sh to load the
 111 mac80211_hwsim module and start wpa_supplicant, hostapd, and various
 112 test tools. run-tests.sh is then used to run through all the defined
 113 test cases and stop-wifi.sh to stop the programs and unload the kernel
 114 module.
 115
 116 run-all.sh can be used to run the same test cases under different
 117 conditions:
 118
 119 # run normal test cases
 120 ./run-all.sh
 121
 122 # run normal test cases under valgrind
 123 ./run-all.sh valgrind
 124
 125 # run normal test cases with Linux tracing
 126 ./run-all.sh trace
 127
 128 # run P2P test cases with concurrent station interface
 129 ./run-all.sh concurrent
 130
 131 # run P2P test cases with concurrent station interface under valgrind
 132 ./run-all.sh concurrent-valgrind
 133
 134 run-all.sh directs debug logs into the logs subdirectory (or $LOGDIR if
 135 present in the environment). Log file names include the current UNIX
 136 timestamp and a postfix to identify the specific log:
 137 - log0 = wpa_supplicant debug log for the first radio
 138 - log1 = wpa_supplicant debug log for the second radio
 139 - log2 = wpa_supplicant debug log for the third radio
 140 - hostapd = hostapd debug log
 141 - hwsim0 = wlantest debug log
 142 - hwsim0.pcapng = capture with all frames exchanged during the tests
 143 - tcpdump = tcpdump output
 144 - run = debug prints from the test scripts
 145 - trace.dat = Linux tracing record (if enabled)
 146 - hlr_auc_gw - hlr_auc_gw (EAP-SIM/AKA/AKA' authentication) log
 147 - auth_serv - hostapd as RADIUS authentication server log
 148
 149
 150 For manual testing, ./start.sh can be used to initialize interfaces and
 151 programs and run-tests.py to execute one or more test
 152 cases. run-tests.py output verbosity can be controlled with -d (more
 153 verbose debug output) and -q (less verbose output) on the command
 154 line. "-f <test_filename(without.py)>" can be used to specify that all
 155 test cases from a single file are to be run. Test name as the last
 156 command line argument can be specified that a single test case is to be
 157 run (e.g., "./run-tests.py ap_pmf_required").
 158
 159
 160 Adding/modifying test cases
 161 ---------------------------
 162
 163 All the test cases are defined in the test_*.py files. These are python
 164 scripts that can use the local helper classes to interact with the test
 165 components. While various python constructs can be used in the scripts,
 166 only a minimal level of python knowledge should really be needed to
 167 modify and add new test cases. The easiest starting point for this is
 168 likely to take a look at some of the example scripts. When working on a
 169 new test, run-tests.py with -d and the test case name on the command
 170 line is a convenient way of verifying functionality.
 171
 172 run-tests.py will automatically import all test cases from the test_*.py
 173 files in this directory. All functions starting with the "test_" prefix
 174 in these files are assumed to be test cases. Each test case is named by
 175 the function name following the "test_" prefix.
 176
 177
 178 Results database
 179 ----------------
 180
 181 run-tests.py can be requested to write results from the execution of
 182 each test case into an sqlite database. The "-S <path to database>" and
 183 "-b <build id>" command line arguments can be used to do that. The
 184 database must have been prepared before this, e.g., with following:
 185
 186 cat | sqlite3 /tmp/example.db <<EOF
 187 CREATE TABLE results (test,result,run,time,duration,build,commitid);
 188 CREATE INDEX results_idx ON results (test);
 189 CREATE INDEX results_idx2 ON results (run);
 190 CREATE TABLE tests (test,description);
 191 EOF