blob: a046b76582ca85b26fe3f93e86700be340069fa9 [file] [log] [blame] [view] [edit]
# Hostap Hwsim Tests
The [hostap project] consists of `wpa_supplicant` and `hostapd`, used for WiFi
clients and APs respectively. The project includes a number of tests, many of
which are run under a [hwsim-based test framework]. They rely on the
`mac80211_hwsim` kernel module, which provides support for simulated client and
AP devices. See the upstream project documentation for more info.
The upstream test framework is integrated within Chrome OS to run via the
[wifi.HostapHwsim] Tast test wrapper. This test has some limited software
dependencies, which are installed via the `USE=wifi_hostap_test` feature flag.
Currently, this `USE` flag is enabled only on `BOARD=amd64-generic` and those
that inherit from it. The easiest way to use the tests is via a VM target, like
`BOARD=betty` (Google-only).
See these [slides] (Google-only) for a rough primer on how and why they were
integrated into Chrome OS.
## HOWTO
Below is a walkthrough on building and running a VM test, and modifying the
tests yourself. See the [cros_vm docs] for more thorough VM instructions.
```bash
# Build a board for a VM.
export BOARD=betty
./build_packages --board=${BOARD}
./build_image --board=${BOARD} test
# Start the VM.
cros_vm --start --board=${BOARD}
# Run the validity test.
tast -verbose run localhost:9222 wifi.HostapHwsim.validity
# Make modifications.
## Find the appropriate src/third_party/wpa_supplicant-*/
## source tree. See the hostap-test ebuild for its CROS_WORKON_LOCALNAME:
## https://chromium.googlesource.com/chromiumos/overlays/chromiumos-overlay/+/refs/heads/main/net-wireless/hostap-test/hostap-test-9999.ebuild
## That is, src/third_party/wpa_supplicant-2.8 as of May 2020.
## Make your modifications to, e.g., tests/hwsim/test_<relevant_module>.py, or
## wpa_supplicant/<foo>.c.
# Deploy modifications.
cros_workon-${BOARD} start hostap-test
emerge-${BOARD} hostap-test && cros deploy --root=/usr/local localhost:9222 hostap-test
# Rerun validity tests.
tast -verbose run localhost:9222 wifi.HostapHwsim.validity
# Run a specific module, the 'ap_roam' module.
tast -verbose run -var=wifi.HostapHwsim.runArgs='-f ap_roam' \
localhost:9222 wifi.HostapHwsim.full
```
## Tips
* **Pitfall**: Tests are packaged via the `net-wireless/hostap-test` package,
not the `net-wireless/wpa_supplicant` or `net-wireless/hostapd` packages.
Be sure to `cros_workon` and `cros deploy` the correct one.
* **Pitfall**: Until `cros deploy` learns to [deploy to the correct root],
remember to use `--root=/usr/local` with `cros deploy`. Test-image-only
packages are installed at `/usr/local`, so you should deploy the
`hostap-test` package there too.
* Logs are stored to the Tast results directory
(`/tmp/tast/results/latest/tests/wifi.HostapHwsim.*/`). These include
kernel logs and logs for one or more `hostapd` or `wpa_supplicant`
instance, as well as packet captures.
* You can pass arbitrary arguments to the `wifi.HostapHwsim.full` variant
via the `-var=wifi.HostapHwsim.runArgs='...'` parameter, to run specific
tests, or to add extra debugging information. e.g., the `-T` parameter
captures kernel tracing information via `trace-cmd`. See the `--help`
descriptions for more info:
```
localhost ~ # /usr/local/libexec/hostap/tests/hwsim/run-all.sh -h
/usr/local/libexec/hostap/tests/hwsim/run-all.sh [-v | --valgrind | valgrind] [-t | --trace | trace]
[-n <num> | --channels <num>] [-B | --build]
[-c | --codecov ] [run-tests.py parameters]
localhost ~ # /usr/local/libexec/hostap/tests/hwsim/run-tests.py -h
usage: run-tests.py [-h] [--logdir <directory>] [-d | -q] [-S <sqlite3 db>]
[--prefill-tests] [--commit <commit id>] [-b <build>] [-L]
[-T] [-D] [--dbus] [--shuffle-tests] [--split SPLIT]
[--no-reset] [--long]
[-f <test module> [<test module> ...]] [-l <modules file>]
[-i]
[<test> [<test> ...]]
hwsim test runner
positional arguments:
<test> tests to run (only valid without -f)
optional arguments:
-h, --help show this help message and exit
--logdir <directory> log output directory for all other options, must be
given if other log options are used
-d verbose debug output
-q be quiet
-S <sqlite3 db> database to write results to
--prefill-tests prefill test database with NOTRUN before all tests
--commit <commit id> commit ID, only for database
-b <build> build ID
-L List tests (and update descriptions in DB)
-T collect tracing per test case (in log directory)
-D collect dmesg per test case (in log directory)
--dbus collect dbus per test case (in log directory)
--shuffle-tests Shuffle test cases to randomize order
--split SPLIT split tests for parallel execution (<server
number>/<total servers>)
--no-reset Do not reset devices at the end of the test
--long Include test cases that take long time
-f <test module> [<test module> ...]
execute only tests from these test modules
-l <modules file> test modules file name
-i stdin-controlled test case execution
```
[hostap project]: https://w1.fi/
[hwsim-based test framework]: https://w1.fi/cgit/hostap/plain/tests/hwsim/README
[wifi.HostapHwsim]: hostap_hwsim.go
[slides]: https://goto.google.com/hostap-hwsim-slides
[cros_vm docs]: https://chromium.googlesource.com/chromiumos/docs/+/main/cros_vm.md
[deploy to the correct root]: https://crbug.com/341708