Add wificell doc
Some starter info for people trying to run wificell-based autotests.
BUG=none
TEST=none
Change-Id: Iee736b29f3a775aa7a1f5e8af48c3640c9cb5c13
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/third_party/autotest/+/1516936
Tested-by: Brian Norris <[email protected]>
Reviewed-by: Kirtika Ruchandani <[email protected]>
diff --git a/docs/wificell.md b/docs/wificell.md
new file mode 100644
index 0000000..e96269f
--- /dev/null
+++ b/docs/wificell.md
@@ -0,0 +1,61 @@
+# Running WiFi tests
+
+Most WiFi tests specify `DEPENDENCIES = 'wificell'` in their control file,
+which means they require not only an autotest server and a DUT, but also a
+special test-enabled Access Point (AP). Additionally, some tests require a
+packet capture (pcap) device or a signal attenuator.
+
+The basics of running a wificell autotest are the same as any other, except
+that autotest also needs to know where to find your test AP. For some
+configurations, this is sufficient:
+
+```bash
+# Run a 5HT40 test with DUT at 'my-host' and AP at 'my-host-router'.
+test_that my-host network_WiFi_SimpleConnect.wifi_check5HT40
+````
+
+This works for most of the Chrome OS lab WiFi cells, where we configure DNS to
+pair a DUT at address `${HOST}` with its companion AP at an address
+`${HOST}-router`. See below for more info on addressing your test AP.
+
+## What is a test AP?
+
+A test AP can come in various forms, but as of this writing, it is typically a
+Chrome OS based router / access point such as Whirlwind or Gale, running a
+testbed-ap variant of a Chrome OS test image in Developer Mode. We have
+previously supported other consumer routers, running OpenWRT. Setting up a test
+AP is not in the scope for this document.
+
+The key purpose of a test AP is to run a variety of [hostapd] instances, such
+that we can test our DUTs using different PHY, cipher, etc., configurations.
+
+In autotest, a test AP is represented by a `LinuxRouter` object, in
+[site\_linux\_router].
+
+## What suites should I run?
+
+There are a variety of WiFi-related suites, but developers are commonly
+interested in the functionality (`wifi_matfunc` or its servo-less variant,
+`wifi_matfunc_noservo`) and performance (`wifi_perf`) suites.
+
+## Configuring DNS entries for test APs
+
+Autotest assumes that if you have a DUT at address `${HOST}`, then your AP is
+at an address `${HOST}-router` (see [dnsname\_mangler]). This is configured
+automatically by the lab team for most Chrome OS lab WiFi setups.
+
+For custom/local testing without modifying your DNS server, one can accomplish
+this by adding entries to your `/etc/hosts` file. Alternatively, you can supply
+the `router_addr=` arguments to autotest. For example:
+
+```bash
+# DUT at 'my-host' and AP at 'my-other-router'
+test_that --args=router_addr=my-other-router my-host suite:wifi_matfunc
+```
+
+Also, note that if a pcap device isn't found at `${HOST}-pcap`, then we often
+can utilize the test AP to capture packets as well.
+
+[dnsname\_mangler]: ../server/cros/dnsname_mangler.py
+[hostapd]: https://w1.fi/hostapd/
+[site\_linux\_router]: ../server/site_linux_router.py
