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. This needs to be installed in a way that python can
  64 find it. For example, with this command:
  65
  66 sudo cp ../wpaspy/wpaspy.py /usr/local/lib/python2.7/dist-packages
  67
  68
  69
  70 mac80211_hwsim
  71 --------------
  72
  73 mac80211_hwsim kernel module is available from the upstream Linux
  74 kernel. Some Linux distributions enable it by default. If that's not the
  75 case, you can either enable it in the kernel configuration
  76 (CONFIG_MAC80211_HWSIM=m) and rebuild your kernel or use Backports with
  77 CPTCFG_MAC80211_HWSIM=m to replace the wireless LAN components in the
  78 base kernel.
  79
  80
  81 sudo
  82 ----
  83
  84 Some parts of the testing process requires root privileges. The test
  85 scripts are currently using sudo to achieve this. To be able to run the
  86 tests, you'll probably want to enable sudo with a timeout to not expire
  87 password entry very quickly. For example, use this in the sudoers file:
  88
  89 Defaults        env_reset,timestamp_timeout=180
  90
  91 Or on a dedicated test system, you could even disable password prompting
  92 with this in sudoers:
  93
  94 %sudo   ALL=NOPASSWD: ALL
  95
  96
  97 Other network interfaces
  98 ------------------------
  99
 100 Some of the test scripts are still using hardcoded interface names, so
 101 the easiest way of making things work is to avoid using other network
 102 devices that may use conflicting interface names. For example, unload
 103 any wireless LAN driver before running the tests and make sure that
 104 wlan0..4 gets assigned as the interface names for the mac80211_hwsim
 105 radios. It may also be possible to rename the interface expectations in
 106 run-tests.py to allow other names to be used.
 107
 108
 109 Running tests
 110 -------------
 111
 112 Simplest way to run a full set of the test cases is by running
 113 run-all.sh in tests/hwsim directory. This will use start.sh to load the
 114 mac80211_hwsim module and start wpa_supplicant, hostapd, and various
 115 test tools. run-tests.sh is then used to run through all the defined
 116 test cases and stop-wifi.sh to stop the programs and unload the kernel
 117 module.
 118
 119 run-all.sh can be used to run the same test cases under different
 120 conditions:
 121
 122 # run normal test cases
 123 ./run-all.sh
 124
 125 # run normal test cases under valgrind
 126 ./run-all.sh valgrind
 127
 128 # run normal test cases with Linux tracing
 129 ./run-all.sh trace
 130
 131 # run P2P test cases with concurrent station interface
 132 ./run-all.sh concurrent
 133
 134 # run P2P test cases with concurrent station interface under valgrind
 135 ./run-all.sh concurrent-valgrind
 136
 137 run-all.sh directs debug logs into the logs subdirectory. Log file names
 138 include the current UNIX timestamp and a postfix to identify the
 139 specific log:
 140 - log0 = wpa_supplicant debug log for the first radio
 141 - log1 = wpa_supplicant debug log for the second radio
 142 - log2 = wpa_supplicant debug log for the third radio
 143 - hostapd = hostapd debug log
 144 - hwsim0 = wlantest debug log
 145 - hwsim0.dump = pcap containing all frames exchanged during the tests
 146 - tcpdump = tcpdump output
 147 - run = debug prints from the test scripts
 148 - trace.dat = Linux tracing record (if enabled)
 149 - hlr_auc_gw - hlr_auc_gw (EAP-SIM/AKA/AKA' authentication) log
 150 - auth_serv - hostapd as RADIUS authentication server log
 151
 152
 153 For manual testing, ./start.sh can be used to initialize interfaces and
 154 programs and run-tests.py to execute one or more test
 155 cases. run-tests.py output verbosity can be controlled with -d (more
 156 verbose debug output) and -q (less verbose output) on the command
 157 line. "-f <test_*.py>" can be used to specify that all test cases from a
 158 single file are to be run. Test name as the last command line argument
 159 can be specified that a single test case is to be run (e.g.,
 160 "./run-tests.py test_ap_pmf_required").
 161
 162
 163 Adding/modifying test cases
 164 ---------------------------
 165
 166 All the test cases are defined in the test_*.py files. These are python
 167 scripts that can use the local helper classes to interact with the test
 168 components. While various python constructs can be used in the scripts,
 169 only a minimal level of python knowledge should really be needed to
 170 modify and add new test cases. The easiest starting point for this is
 171 likely to take a look at some of the example scripts. When working on a
 172 new test, run-tests.py with -d and the test case name on the command
 173 line is a convenient way of verifying functionality.
 174
 175 run-tests.py will automatically import all test cases from the test_*.py
 176 files in this directory. All functions starting with the "test_" prefix
 177 in these files are assumed to be test cases.
 178
 179
 180 Results database
 181 ----------------
 182
 183 run-tests.py can be requested to write results from the execution of
 184 each test case into an sqlite database. The "-S <path to database>" and
 185 "-b <build id>" command line arguments can be used to do that. The
 186 database must have been prepared before this, e.g., with following:
 187
 188 cat | sqlite3 /tmp/example.db <<EOF
 189 CREATE TABLE results (test,result,run,time,duration,build,commitid);
 190 CREATE INDEX results_idx ON results (test);
 191 CREATE INDEX results_idx2 ON results (run);
 192 EOF