1# Running WiFi tests 2 3Most WiFi tests specify `DEPENDENCIES = 'wificell'` in their control file, 4which means they require not only an autotest server and a DUT, but also a 5special test-enabled Access Point (AP). Additionally, some tests require a 6packet capture (pcap) device or a signal attenuator. For instructions on how 7to set up a wifcell for testing, visit [Setting up a WiFi Test Cell](https://chromeos.google.com/partner/dlm/docs/component-qual/settinguptestcell.html). 8 9The basics of running a wificell autotest are the same as any other, except 10that autotest also needs to know where to find your test AP. For some 11configurations, this is sufficient: 12 13```bash 14# Run a 5HT40 test with DUT at 'my-host' and AP at 'my-host-router'. 15test_that my-host network_WiFi_SimpleConnect.wifi_check5HT40 16```` 17 18This works for most of the ChromeOS lab WiFi cells, where we configure DNS to 19pair a DUT at address `${HOST}` with its companion AP at an address 20`${HOST}-router`. See below for more info on addressing your test AP. 21 22## What is a test AP? 23 24A test AP can come in various forms, but as of this writing, it is typically a 25ChromeOS based router / access point such as Whirlwind or Gale, running a 26testbed-ap variant of a ChromeOS test image in Developer Mode. We have 27previously supported other consumer routers, running OpenWRT. Setting up a test 28AP is not in the scope for this document. 29 30The key purpose of a test AP is to run a variety of [hostapd] instances, such 31that we can test our DUTs using different PHY, cipher, etc., configurations. 32 33In autotest, a test AP is represented by a `LinuxRouter` object, in 34[site\_linux\_router]. 35 36## What suites should I run? 37 38There are a variety of WiFi-related suites, but developers are commonly 39interested in the functionality (`wifi_matfunc`) and performance (`wifi_perf`) 40suites. 41 42## Configuring DNS entries for test APs 43 44Autotest assumes that if you have a DUT at address `${HOST}`, then your AP is 45at an address `${HOST}-router` (see [dnsname\_mangler]). This is configured 46automatically by the lab team for most ChromeOS lab WiFi setups. 47 48For custom/local testing without modifying your DNS server, one can accomplish 49this by adding entries to your `/etc/hosts` file. Alternatively, you can supply 50the `router_addr=` and `pcap_addr=` arguments to autotest. For example: 51 52```bash 53# DUT at 'my-host', AP at 'my-other-router', and PCAP at 'my-other-pcap' 54test_that --args="router_addr=my-other-router pcap_addr=my-other-pcap" \ 55 my-host suite:wifi_matfunc 56``` 57 58If the test is using 59[Tast](https://chromium.googlesource.com/chromiumos/platform/tast/) instead of 60autotest, you can pass the `router` and `pcap` arguments to `tast run` instead: 61 62```bash 63# DUT at 'my-host', AP at 'my-other-router', and PCAP at 'my-other-pcap' 64tast run -var="router=my-other-router" -var="pcap=my-other-pcap" my-host \ 65 wifi.ChannelHop 66``` 67 68Also, note that if a pcap device isn't found at `${HOST}-pcap`, then we often 69can utilize the test AP to capture packets as well. The test framework does 70this by creating one or more monitor-mode interfaces in addition to the AP-mode 71interface(s) normally used for tests. Note that 802.11 radios cannot both 72transmit and receive at the same time, so this mode operates with slightly 73degraded functionality. In particular, while a typical mac80211-based AP driver 74can capture many aspects of its own transmitted frames (e.g., 802.11 headers 75are constructed in software), it cannot monitor how those frames really look 76over the air, so it will likely be missing most physical-layer information 77(e.g., bitrates, modulation, frequency) or firmware-controlled behaviors (e.g., 78802.11 ACKs). 79 80For example, consider the following AP + monitor capture, filtered for 81[AP-transmitted frames](https://screenshot.googleplex.com/DWSaResO583) and 82[AP-received frames](https://screenshot.googleplex.com/5EsZvbBpKEc) (links are 83Google-internal). While the AP-transmitted frames contain 802.11 header 84information like MAC-layer addresses and sequence numbers, only the received 85frames contain information like frequency and bitrate. As such, if you need 86this sort of information for debugging your tests, ensure you are using a 87dedicated pcap device. Note that all supported tests should support running in 88either configuration. 89 90[dnsname\_mangler]: ../server/cros/dnsname_mangler.py 91[hostapd]: https://w1.fi/hostapd/ 92[site\_linux\_router]: ../server/site_linux_router.py 93