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