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