blob: 74c5a6d347edf5d098dacf1c7eeee71fc99f9d13 [file] [log] [blame] [view]
# antlion
Collection of host-driven, hardware-agnostic Fuchsia connectivity tests. Mainly
targeting WLAN and Netstack testing.
[Docs] | [Report Bug] | [Request Feature]
[TOC]
[Docs]: http://go/antlion
[Report Bug]: http://go/conn-test-bug
[Request Feature]: http://b/issues/new?component=1182297&template=1680893
## 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-local-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/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/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.11+
1. Clone the repo
```sh
git clone https://fuchsia.googlesource.com/antlion
```
2. Install dependencies using [venv](https://docs.python.org/3/library/venv.html#how-venvs-work)
```sh
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 ".[mdns]"
# Run `deactivate` later to exit the virtual environment
```
3. Write the sample config and update the Fuchsia controller to match your
development environment
```sh
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
python tests/examples/Sl4fSanityTest.py -c simple-config.yaml
```
## 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:
- Install developer Python packages for formatting and linting
```sh
pip install --editable ".[dev]"
```
- Install an [EditorConfig](https://editorconfig.org/) plugin for consistent
whitespace
- Complete the steps in '[Contribute source changes]' to gain authorization to
upload CLs to Fuchsia's Gerrit.
To create a CL:
1. Create a branch (`git checkout -b feature/amazing-feature`)
2. Make changes
3. Document the changes in `CHANGELOG.md`
4. Auto-format changes (`./format.sh`)
> Note: antlion follows the [Black code style] (rather than the
> [Google Python Style Guide])
5. Verify no typing errors (`mypy .`)
6. Commit changes (`git add . && git commit -m 'Add some amazing feature'`)
7. Upload CL (`git push origin HEAD:refs/for/main`)
> A public bug tracker is not (yet) available.
[Black code style]: https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html
[Google Python Style Guide]: https://google.github.io/styleguide/pyguide.html
[Contribute source changes]: https://fuchsia.dev/fuchsia-src/development/source_code/contribute_changes#prerequisites
### Recommended git aliases
There are a handful of git commands that will be commonly used throughout the
process of contributing. Here are a few aliases to add to your git config
(`~/.gitconfig`) for a smoother workflow:
- `git amend` to modify your CL in response to code review comments
- `git uc` to upload your CL, run pre-submit tests, enable auto-submit, and
add a reviewer
```gitconfig
[alias]
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
[blame]
ignoreRevsFile = .git-blame-ignore-revs
```
## License
Distributed under the Apache 2.0 License. See `LICENSE` for more information.
## Acknowledgments
This is a fork of [ACTS][ACTS], the connectivity testing framework used by
Android. The folks over there did a great job at cultivating amazing tools, much
of which are being used or have been extended with additional features.
[ACTS]: https://fuchsia.googlesource.com/third_party/android.googlesource.com/platform/tools/test/connectivity/
### Migrating CLs from ACTS
`antlion` and ACTS share the same git history, so migrating existing changes is
straightforward:
1. Checkout to latest `main`
```sh
git checkout main
git pull --rebase origin main
```
2. Cherry-pick the ACTS change
```sh
git fetch acts refs/changes/16/12345/6 && git checkout -b change-12345 FETCH_HEAD
git fetch https://android.googlesource.com/platform/tools/test/connectivity refs/changes/30/2320530/1 && git cherry-pick FETCH_HEAD
```
3. Resolve any merge conflicts, if any
```sh
git add [...]
git rebase --continue
```
4. Upload CL
```sh
git push origin HEAD:refs/for/main # or "git uc" if using the alias
```