Update README to prefer use of antlion in-tree
The new recommended way to run antlion is within a Fuchsia checkout.
This allows use of GN and multi-repo testing before submitting changes.
Also supports the migration to Mobly by removing use of the deprecated
act.py script (which is aliased as "antlion"). When not using
antlion-runner, execute the test script directly.
Bug: b/274619290
Change-Id: I35180d781513c83bb5b775fd9192207e79a503c1
Reviewed-on: https://fuchsia-review.googlesource.com/c/antlion/+/857909
Commit-Queue: Auto-Submit <auto-submit@fuchsia-infra.iam.gserviceaccount.com>
Fuchsia-Auto-Submit: Sam Balana <sbalana@google.com>
Reviewed-by: Patrick Lu <patricklu@google.com>
diff --git a/README.md b/README.md
index b5240c8..7d5950b 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,85 @@
[Report Bug]: http://go/conn-test-bug
[Request Feature]: http://b/issues/new?component=1182297&template=1680893
-## Getting Started
+## Getting started with QEMU
+
+The quickest way to run antlion is by using the Fuchsia QEMU emulator. This
+enables antlion tests that do not require hardware-specific capabilities like
+WLAN. This is especially useful to verify if antlion builds and runs without
+syntax errors. If you require WLAN capabilities, see
+[below](#running-with-a-physical-device).
+
+1. [Checkout Fuchsia](https://fuchsia.dev/fuchsia-src/get-started/get_fuchsia_source)
+
+2. Configure and build Fuchsia to run antlion tests virtually on QEMU
+
+ ```sh
+ fx set core.qemu-x64 \
+ --with //src/testing/sl4f \
+ --with //src/sys/bin/start_sl4f \
+ --args 'core_realm_shards += [ "//src/testing/sl4f:sl4f_core_shard" ]' \
+ --with-host //third_party/antlion:e2e_tests_quick
+ fx build
+ ```
+
+3. In a separate terminal, run the emulator with networking enabled
+
+ ```sh
+ ffx emu stop && ffx emu start -H --net tap && ffx log
+ ```
+
+4. In a separate terminal, run a package server
+
+ ```sh
+ fx serve
+ ```
+
+5. Run an antlion test
+
+ ```sh
+ fx test --e2e --output //third_party/antlion/src/antlion/tests/examples:sl4f_sanity_test
+ ```
+
+## Running with a local physical device
+
+A physical device is required for most antlion tests, which rely on physical I/O
+such as WLAN and Bluetooth. Antlion is designed to make testing physical devices
+as easy, reliable, and reproducible as possible. The device will be discovered
+using mDNS, so make sure your host machine has a network connection to the
+device.
+
+1. Configure and build Fuchsia for your target with the following extra
+ arguments:
+
+ ```sh
+ fx set core.my-super-cool-product \
+ --with //src/testing/sl4f \
+ --with //src/sys/bin/start_sl4f \
+ --args='core_realm_shards += [ "//src/testing/sl4f:sl4f_core_shard" ]' \
+ --with-host //third_party/antlion:e2e_tests
+ fx build
+ ```
+
+2. Flash your device with the new build
+
+3. In a separate terminal, run a package server
+
+ ```sh
+ fx serve
+ ```
+
+4. Run an antlion test
+
+ ```sh
+ fx test --e2e --output //third_party/antlion/src/antlion/tests/functional:ping_stress_test
+ ```
+
+> Local auxiliary devices are not yet support by `antlion-runner`, which is
+> responsible for generating Mobly configs. In the meantime, see the
+> section below for manually crafting Mobly configs to support auxiliary
+> devices.
+
+## Running without a Fuchsia checkout
Requires Python 3.8+
@@ -27,7 +105,7 @@
cd antlion
python3 -m venv .venv # Create a virtual environment in the `.venv` directory
source .venv/bin/activate # Activate the virtual environment
- pip install --editable .
+ pip install --editable ".[mdns]"
# Run `deactivate` later to exit the virtual environment
```
@@ -35,57 +113,66 @@
development environment
```sh
- mkdir -p config
- cat <<EOF > config/simple.json
- {
- "testbed": [{
- "name": "simple_testbed",
- "FuchsiaDevice": [{
- "ip": "fuchsia-00e0-4c01-04df"
- }]
- }],
- "logpath": "logs"
- }
+ cat <<EOF > simple-config.yaml
+ TestBeds:
+ - Name: antlion-runner
+ Controllers:
+ FuchsiaDevice:
+ - ip: fuchsia-00e0-4c01-04df
+ MoblyParams:
+ LogPath: logs
EOF
```
+ Replace `fuchsia-00e0-4c01-04df` with your device's nodename, or
+ `fuchsia-emulator` if using an emulator. The nodename can be found by looking
+ for a log similar to the one below.
+
+ ```text
+ [0.524][klog][klog][I] netsvc: nodename='fuchsia-emulator'
+ ```
+
4. Run the sanity test
```sh
- antlion -c config/simple.json -tc Sl4fSanityTest
+ python src/antlion/tests/examples/Sl4fSanityTest.py -c simple-config.yaml
```
-See `antlion -h` for more full usage.
-
## Contributing
Contributions are what make open source projects a great place to learn,
inspire, and create. Any contributions you make are **greatly appreciated**.
If you have a suggestion that would make this better, please create a CL.
+Before contributing, additional setup is necessary:
-Before contributing, a few more tools are necessary:
+- Install developer Python packages for formatting and linting
-- Install these additional dependencies:
- ```
+ ```sh
pip install --editable ".[dev]"
```
-- Install the [EditorConfig](https://editorconfig.org/) plugin for your editor
+
+- Install an [EditorConfig](https://editorconfig.org/) plugin for consistent
+ whitespace
+
- Install [Black](https://pypi.org/project/black/) our preferred code formatter.
- Optionally, add the extension to your editor.
-- Complete the steps in '[Contribute source changes]' to gain authorization
+ Optionally, add the extension to your editor.
+
+- Complete the steps in '[Contribute source changes]' to gain authorization to
+ upload CLs to Fuchsia's Gerrit.
To create a CL:
-1. Create a feature branch (`git checkout -b feature/amazing-feature`)
-2. Document your change in `CHANGELOG.md`
-3. Run your change through `Black` formatter
-4. Commit changes (`git add . && git commit -m 'Add some amazing feature'`)
-5. Upload CL (`git push origin HEAD:refs/for/main`)
+1. Create a branch (`git checkout -b feature/amazing-feature`)
+2. Make changes
+3. Document the changes in `CHANGELOG.md`
+4. Run your change through `Black` formatter
+5. Commit changes (`git add . && git commit -m 'Add some amazing feature'`)
+6. Upload CL (`git push origin HEAD:refs/for/main`)
> A public bug tracker is not (yet) available.
-[Contribute source changes]: https://fuchsia.dev/fuchsia-src/development/source_code/contribute_changes#create-and-upload-a-patch
+[Contribute source changes]: https://fuchsia.dev/fuchsia-src/development/source_code/contribute_changes#prerequisites
### Recommended git aliases
@@ -102,6 +189,7 @@
amend = commit --amend --no-edit
uc = push origin HEAD:refs/for/main%l=Commit-Queue+1,l=Fuchsia-Auto-Submit+1,publish-comments,r=sbalana
```
+
You may also want to add a section to ignore the project's large formatting changes:
```gitconfig
